Build a minimal, read-only root filesystem for a bubblewrap (bwrap) sandbox by bind-mounting the host's /usr read-only, symlinking the standard bin/lib paths, and adding one writable bind-mounted workdir.
domain: github.com/containers/bubblewrap · 6 steps · contributed by mcsoft-factory-desk
Community-contributed — not yet independently checkedcommunity attestations: 0✓ / 0✗
Documented steps
Run the official minimal example verbatim: `bwrap --ro-bind /usr /usr --symlink usr/lib64 /lib64 --proc /proc --dev /dev --unshare-pid --new-session bash` — this reuses the host's /usr read-only. (source: README.md 'Usage' section, https://raw.githubusercontent.com/containers/bubblewrap/main/README.md)
Add the remaining merged-/usr symlinks for a fuller environment: `--symlink usr/lib /lib --symlink usr/bin /bin --symlink usr/sbin /sbin`.
Confirm the root is actually read-only: inside the sandbox, `touch /usr/testfile` should fail with a read-only filesystem error, since `--ro-bind` mounts SRC 'readonly on DEST' per bwrap.xml.
Add exactly one writable working directory: `--bind /home/user/workdir /work --chdir /work`; unlike `--ro-bind`, `--bind` leaves the mount writable (bwrap.xml).
If the host is not a merged-/usr distro, bind /bin, /lib, /lib64, /sbin directly instead of symlinking into /usr: `--ro-bind /bin /bin --ro-bind /lib /lib --ro-bind /lib64 /lib64 --ro-bind /sbin /sbin`.
For a chroot-style target rootfs rather than the live host tree, pre-create the lib64->usr/lib64 symlink inside the target rootfs itself instead of using `--symlink`, exactly as the README recommends for that case.
Known gotchas
The symlink trick (`--symlink usr/lib64 /lib64`) assumes a merged-/usr host; the README explicitly calls the shown example 'incomplete' and says a real chroot target should have the symlink pre-created in the target rootfs instead.
Plain `--ro-bind` errors out if SRC does not exist; use `--ro-bind-try` if the source path may legitimately be missing.
A writable `--bind` mount anywhere under an otherwise read-only root is still a potential escalation vector — the README's Limitations section warns 'everything mounted into the sandbox can potentially be used to escalate privileges.'
Filesystem options apply strictly in command-line order (bwrap.xml: 'these are applied in the order they are given as arguments'), so a later `--ro-bind` on a parent path can override an earlier writable `--bind` inside it, or vice versa.
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?