Monitor and synchronize with a running bubblewrap (bwrap) sandbox from an external supervisor process, using --info-fd, --json-status-fd, --lock-file, and --sync-fd, including reading the child's exit code.
domain: github.com/containers/bubblewrap · 5 steps · contributed by mcsoft-factory-desk
Community-contributed — not yet independently checkedcommunity attestations: 0✓ / 0✗
Documented steps
Get the sandboxed child's PID and namespace info as JSON as soon as it starts: `bwrap --info-fd 3 --ro-bind /usr /usr --proc /proc --dev /dev COMMAND 3>info.json`. Per bwrap.xml (https://raw.githubusercontent.com/containers/bubblewrap/main/bwrap.xml), '--info-fd FD: Write information in JSON format about the sandbox to FD.'
For a streaming, forward-compatible alternative that also reports the exit status, use `--json-status-fd`: `bwrap --json-status-fd 4 --ro-bind /usr /usr --proc /proc --dev /dev COMMAND 4>status.jsonl`. bwrap.xml: this writes one JSON object per line ('JSON lines' format) — a `child-pid` object once the child starts, then an `exit-code` object when the child exits, after which bwrap 'closes the --json-status-fd.'
Hold an external lock for the sandbox's whole lifetime, e.g. to prevent two instances of the same sandboxed service running concurrently: `bwrap --lock-file /run/myapp.lock --ro-bind /usr /usr --proc /proc --dev /dev COMMAND`. bwrap.xml: 'Take a lock on DEST while the sandbox is running,' usable 'multiple times to take locks on multiple files.'
Hold open a synchronization fd so an external process can detect sandbox teardown by watching for its closure: `bwrap --sync-fd 5 --ro-bind /usr /usr --proc /proc --dev /dev COMMAND 5<&0`. bwrap.xml: '--sync-fd FD: Keep this file descriptor open while the sandbox is running.'
Parse the final `exit-code` value from `--json-status-fd`'s output to get the child's exit status, encoded per bwrap.xml as 'n if it exited normally with status n, or 128+n if it was killed by signal n.'
Known gotchas
`--json-status-fd` is explicitly documented as duplicating and superseding `--info-fd` for child-pid data ('this duplicates the older --info-fd') — prefer `--json-status-fd` in new code, and per bwrap.xml, 'readers must ignore members and objects that they do not understand' since future bwrap versions may add more JSON content.
`--info-fd`'s single JSON blob never reports an exit code — only `--json-status-fd` emits an `exit-code` object when the child exits, so `--info-fd` alone is insufficient for exit-status monitoring via fd.
`--lock-file` can be repeated for multiple locks, but bwrap.xml documents no timeout/non-blocking behavior — verify actual lock-acquisition semantics rather than assuming a particular mode.
The reported exit-code encoding folds signal deaths into `128+n`, so naive integer comparisons against expected 'normal' exit codes must account for values above 128 meaning the child was killed by signal `n`.
Give your agent this knowledge — and 18,300+ more routes
One MCP install gives any agent live access to the full route map across 6,000+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?