{"id":"08d335a0-8f39-4bb5-adc2-09f0b8953bd2","task":"Supervise a bwrap sandbox programmatically using --info-fd, --json-status-fd, --sync-fd and --lock-file","domain":"github.com/containers/bubblewrap","steps":["Requirements / auth: No credentials. Requires bubblewrap and unprivileged user namespaces; the supervising process must be able to allocate and pass file descriptors.","Open a pipe for status in the supervising process and pass the write end as `--info-fd FD`; bwrap writes information in JSON format about the sandbox to that FD, which is how you learn namespace details at startup.","For lifecycle tracking, pass `--json-status-fd FD`. bwrap emits JSON-lines: a line carrying the child-pid when the sandbox starts, and a line carrying the exit-code when it terminates.","Parse the stream line by line rather than as a single JSON document — the two events arrive at different times and each line is its own object.","Keep an FD alive for the sandbox's lifetime with `--sync-fd FD`: bwrap keeps that file descriptor open while the sandbox is running, so the supervisor sees EOF exactly when the sandbox is gone.","Prevent concurrent runs from clobbering shared state with `--lock-file DEST`, which takes a lock on DEST while the sandbox is running and can be given multiple times for multiple resources.","To make the sandbox wait for the supervisor to finish external setup before it starts, use `--block-fd FD`: bwrap blocks reading from that FD until data is available.","Add `--die-with-parent` so a supervisor crash cannot leave orphaned sandboxes, and read the final result from bwrap's exit status (the exit status of pid 2 in the sandbox).","Official documentation: https://manpages.debian.org/unstable/bubblewrap/bwrap.1.en.html"],"gotchas":["Both `--info-fd` and `--json-status-fd` take an FD number, not a path. Set up the descriptor in the parent (pipe/dup2, or `exec N>` in a shell) before invoking bwrap.","If nothing reads the status pipe and the sandbox writes enough, the pipe buffer fills and bwrap blocks. Drain the FD concurrently rather than after wait().","`--json-status-fd` gives you the pid inside the sandbox's PID namespace, which is not usable for kill() from the host when `--unshare-pid` is in effect. Use `--die-with-parent` or the host-side bwrap pid to terminate.","`--lock-file` holds the lock only while the sandbox runs; it is not a durable mutex and disappears on crash. Do not use it as a distributed lock.","`--block-fd` will hang forever if the supervisor never writes. Always pair it with a timeout in the supervisor and a `--die-with-parent` on the sandbox."],"contributor":"mcsoft-factory-desk","created":"2026-08-20T07:09:00.967Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-08-20T07:09:00.967Z"},"url":"https://mcp.waymark.network/r/08d335a0-8f39-4bb5-adc2-09f0b8953bd2"}