Choose correctly between bwrap --bind, --ro-bind and --dev-bind and make only one working directory writable

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

Documented steps

  1. Requirements / auth: No credentials. Requires bubblewrap and unprivileged user namespaces; the invoking user must already be able to read SRC on the host (bwrap grants no new host access).
  2. Default to `--ro-bind SRC DEST` for everything the sandboxed process only needs to read: system libraries, interpreters, config, input data. Read-only is the correct default for a sandbox root.
  3. Use `--bind SRC DEST` only for the single path the process is allowed to modify, e.g. `--bind $PWD/out /workspace/out`. Keep the writable set as small as the task allows.
  4. Use `--dev-bind SRC DEST` only when the process genuinely needs device access through the bind (it is `--bind` plus permission to access devices). Treat it as a privileged operation, not a stronger `--bind`.
  5. Use the `-try` variants (`--bind-try`, `--ro-bind-try`, `--dev-bind-try`) for optional host paths: they behave identically but silently ignore a non-existent SRC instead of failing the whole sandbox.
  6. Replace whole directory subtrees you want to hide with `--tmpfs DEST`, and size it explicitly by putting `--size BYTES` immediately before the `--tmpfs` it applies to.
  7. Downgrade a single already-mounted path to read-only with `--remount-ro DEST` — it affects only that exact mount point and does not recurse into mount points beneath it.
  8. Verify the result from inside before trusting it: `bwrap ... --ro-bind / / --bind $PWD/out /out sh -c 'cat /proc/self/mountinfo; touch /etc/proof 2>&1'` and confirm the write is refused.
  9. Official documentation: https://manpages.debian.org/unstable/bubblewrap/bwrap.1.en.html

Known gotchas

Related routes

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.
github.com/containers/bubblewrap · 6 steps · unrated
Inject generated configuration data, secrets, or a stub /etc/passwd into a bubblewrap (bwrap) sandbox directly from file descriptors, without writing temporary files to the host filesystem, using --file, --bind-data, --ro-bind-data, and --args.
github.com/containers/bubblewrap · 5 steps · unrated
Give a bubblewrap (bwrap) sandbox a writable overlay filesystem so an untrusted process can write to what looks like a full directory tree without touching host files, using --overlay, --tmp-overlay, or --ro-overlay.
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