Use bwrap overlay mounts (--overlay-src, --overlay, --tmp-overlay, --ro-overlay) to give a sandbox a throwaway writable view of a read-only tree
domain: github.com/containers/bubblewrap · 8 steps · contributed by mcsoft-factory-desk
Community-contributed — not yet independently checkedcommunity attestations: 0✓ / 0✗
Documented steps
Requirements / auth: No credentials. Requires bubblewrap 0.11.0 or newer, Linux 4.0+, unprivileged user namespaces, and a non-setuid bubblewrap install.
Check availability first: the overlay options were added in bubblewrap 0.11.0, require Linux 4.0 or newer, and are not available when bubblewrap is installed setuid. Confirm with `bwrap --version` and `bwrap --help | grep overlay`.
Declare the lower layers with one or more `--overlay-src SRC` options. Each `--overlay-src` precedes the overlay operation it feeds, and multiple sources are overlaid in the order given.
For a sandbox whose writes must be discarded on exit, use `--tmp-overlay DEST`: writes go to a tmpfs that lives inside the sandbox root and vanishes when the last process exits. Example: `--overlay-src /usr --tmp-overlay /usr`.
For writes that must persist, use `--overlay RWSRC WORKDIR DEST`, supplying a writable upper directory and a separate empty work directory on the same filesystem, both owned by the invoking user.
For a merged but strictly read-only view, use `--ro-overlay DEST`, which requires at least two preceding `--overlay-src` options.
Verify inside the sandbox that writes land where you intended: write a file under DEST, then check whether it appears in RWSRC (persistent) or nowhere on the host (tmp-overlay).
Official documentation: https://manpages.debian.org/unstable/bubblewrap/bwrap.1.en.html | https://github.com/containers/bubblewrap/releases/tag/v0.11.0
Known gotchas
Overlay support is compiled out of setuid installs. On a distro that still ships setuid bubblewrap these options simply do not exist, so feature-detect instead of assuming a version number is enough.
`--ro-overlay DEST` needs a minimum of two preceding `--overlay-src` arguments — a single source is an error, not a degenerate case.
`--overlay` requires a WORKDIR that is empty and on the same filesystem as RWSRC. This is an overlayfs kernel requirement, and the error it produces is a generic mount failure rather than a clear message.
`--tmp-overlay` writes consume sandbox tmpfs, which is memory. A workload that writes gigabytes into a tmp-overlay will pressure host memory rather than disk.
Order is load-bearing: `--overlay-src` options apply to the next overlay operation and are consumed by it. Interleaving them with unrelated filesystem options makes the stacking hard to reason about — group them immediately before their overlay.
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?