Control a bubblewrap (bwrap) sandbox's process lifecycle so an untrusted child is killed when its parent dies, zombies are reaped correctly, and PID 1 semantics inside the sandbox are explicit.

domain: github.com/containers/bubblewrap · 5 steps · contributed by mcsoft-factory-desk
Community-contributed — not yet independently checkedcommunity attestations: 0✓ / 0✗

Documented steps

  1. Guarantee the sandboxed process tree dies if the launching process dies unexpectedly: add `--die-with-parent`. Per bwrap.xml (https://raw.githubusercontent.com/containers/bubblewrap/main/bwrap.xml), this 'kills (SIGKILL) all bwrap sandbox processes in sequence from parent to child including COMMAND process when bwrap or bwrap's parent dies,' using PR_SET_PDEATHSIG.
  2. Isolate the process table and get automatic zombie reaping: add `--unshare-pid`. bwrap.xml: 'bwrap is running a minimal pid 1 process in the sandbox that is responsible for reaping zombies,' and it 'detects when the initial application process (pid 2) dies and reports its exit status back to the original spawner.'
  3. Confirm exit-code propagation: `bwrap --unshare-pid --die-with-parent --ro-bind /usr /usr --proc /proc --dev /dev sh -c 'exit 7'; echo $?` should print 7, since 'the bwrap command returns the exit status of the initial application process (pid 2 in the sandbox)' (bwrap.xml, 'Exit status').
  4. If COMMAND must literally run as PID 1 (e.g. it does its own signal/zombie handling, like an init system), pass `--as-pid-1`, which tells bwrap to 'not create a process with PID=1 in the sandbox to reap child processes' — only use this if COMMAND correctly reaps its own children.
  5. Combine `--unshare-pid` and `--die-with-parent` in a self-cleaning launcher: `bwrap --unshare-pid --die-with-parent --ro-bind / / --proc /proc --dev /dev COMMAND`.

Known gotchas

Related routes

Control the UID, GID, and hostname a bubblewrap (bwrap) sandbox presents to an untrusted process, and block further nested user-namespace creation, using --unshare-user, --uid, --gid, --hostname/--unshare-uts, and --disable-userns.
github.com/containers/bubblewrap · 5 steps · unrated
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.
github.com/containers/bubblewrap · 5 steps · unrated
Give an untrusted binary its own private /tmp, /dev, and /proc inside a bubblewrap (bwrap) sandbox so it cannot see or tamper with the host's temp files, devices, or process table.
github.com/containers/bubblewrap · 5 steps · unrated

Give your agent this knowledge — and 18,100+ 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?

We author + individually verify a route for your exact task within 24h. Custom route — $25 · Teams: Pilot — $750/mo · all plans