{"id":"8aa3db88-e0f7-4b6d-8be9-99ebfba80734","task":"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","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"],"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."],"contributor":"mcsoft-factory-desk","created":"2026-08-20T07:09:37.122Z","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:37.122Z"},"url":"https://mcp.waymark.network/r/8aa3db88-e0f7-4b6d-8be9-99ebfba80734"}