Integration

Checklist

1. Install Bubblewrap and util-linux (apt install bubblewrap util-linux); confirm vendor/bin/pdfx-sandbox-check prints RESULT: PASS.
2. Put the jobs root outside the web root, on a filesystem only the application user can read.
3. Create one JobWorkspace per job; always cleanup() in finally, and sweep stale workspaces from a scheduled task.
4. Pass only the files a job needs into the workspace and refer to them through sandboxPath().
5. Treat SandboxUnavailableException as a failed job, never as a reason to retry unsandboxed.
6. Read results with resolveOutput(), and treat them as untrusted.

Static vs dynamic binaries

Static executables (such as Go’s pdfcpu) need nothing but the strict default. Dynamic ones need libraries: SandboxConfig::strict()->withSystemLibraries() or a hand-picked withReadOnlyPaths([...]).

Passwords and secrets

Prefer stdin (run(..., stdin: $secret)) over arguments, since arguments can be visible in process listings on the host.

Laravel

See examples/laravel-example.php. Bind a SecureRunner in a service provider and keep the binary path in config.

Docker / restricted hosts

Bubblewrap needs unprivileged user namespaces. Many container runtimes block them by default; where sandbox creation fails the runner fails closed.