Sanitize the environment variables seen by a process inside a bubblewrap (bwrap) sandbox using --clearenv, --setenv, and --unsetenv, and set a custom argv[0] with --argv0.

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

Documented steps

  1. Wipe the entire inherited environment before adding anything back: `bwrap --clearenv --setenv PATH /usr/bin --setenv HOME /home/sandboxuser --ro-bind /usr /usr --proc /proc --dev /dev COMMAND`. Per bwrap.xml (https://raw.githubusercontent.com/containers/bubblewrap/main/bwrap.xml), `--clearenv` unsets 'all environment variables, except for PWD and any that are subsequently set by --setenv.'
  2. Add exactly the variables the sandboxed program needs, one at a time: `--setenv LANG C.UTF-8 --setenv TERM xterm-256color`.
  3. Strip one sensitive variable while keeping the rest of the ambient environment: `--unsetenv SSH_AUTH_SOCK` (use instead of `--clearenv` when most of the inherited environment should be kept).
  4. Normalize how the sandboxed process identifies itself in `ps`/`/proc/self/cmdline`: `bwrap --argv0 my-app-name /usr/bin/real-binary --some-flag`. bwrap.xml: `--argv0 VALUE` 'Set argv[0] to the value VALUE before running the program.'
  5. Verify: `bwrap --clearenv --setenv PATH /usr/bin --argv0 renamed-proc /usr/bin/env` should print only PATH (and PWD) among the environment, and `ps` should show the process name as 'renamed-proc'.

Known gotchas

Related routes

Give an untrusted binary its own private /tmp, /dev, and /proc inside a bubblewrap (bwrap) sandbox so it cannot see or tamper with the host's temp files, devices, or process table.
github.com/containers/bubblewrap · 5 steps · unrated
Control the UID, GID, and hostname a bubblewrap (bwrap) sandbox presents to an untrusted process, and block further nested user-namespace creation, using --unshare-user, --uid, --gid, --hostname/--unshare-uts, and --disable-userns.
github.com/containers/bubblewrap · 5 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 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