bwrap: Lightweight sandboxing for Linux commands

What is bwrap?

Bubblewrap (bwrap) is a small tool that runs a program in a lightweight, sandboxed environment. It creates a restricted filesystem view and optional bindings to privileges, helping isolate the executed program from the host system.

Quickstart: run something in a read-only root

A simple, safe way to sandbox a command is to mount the host root read-only and start a shell inside the sandbox:

bwrap --ro-bind / / {{/bin/bash}}

Notes:

  • The root filesystem is exposed read-only, reducing the risk of modifying your system.
  • The shell inside the sandbox inherits limited visibility depending on bindings.

More practical sandbox options

If you want a more functional sandbox (with device information, limited /proc, and a writable tmpfs), you can bind specific paths and create a temporary filesystem for /tmp:

bwrap --dev-bind /dev /dev --proc /proc --ro-bind / / --tmpfs /tmp {{/bin/bash}}

What this does:

  • —dev-bind /dev /dev: exposes devices to the sandbox.
  • —proc /proc: exposes process information inside the sandbox.
  • —ro-bind / /: mounts the host root read-only to the sandbox.
  • —tmpfs /tmp: provides a writable /tmp inside the sandbox.

Common variations

  • Run a specific program in a restricted environment:
bwrap --ro-bind / / {{/usr/bin/python3 /path/to/script.py}}
  • Bind a subset of the filesystem for a more permissive sandbox:
bwrap --ro-bind /usr /usr --ro-bind /bin /bin {{/bin/bash}}

Practical tips and pitfalls

  • Start simple: begin with —ro-bind / / to understand how the sandbox affects your command.
  • Be mindful of absolute paths: the command inside the sandbox uses the path you specify; if a binary isn’t available inside the sandbox, it will fail.
  • Dealing with GUI or network access: bwrap is designed for confinement, not full desktop virtualization. Network access may be restricted depending on the host setup.
  • Permissions matter: if your command needs access to files outside the sandbox, explicitly bind them with —bind or —ro-bind as needed.

Troubleshooting common issues

  • If your command inside the sandbox cannot find a binary, ensure the path exists inside the sandbox and consider binding a directory that contains it.
  • If you get permission errors on /proc or /dev, adjust bindings (e.g., remove —ro-bind or add —proc —dev-bind as appropriate).
  • For safer defaults, start with a minimal sandbox and incrementally add bindings.

Quick reference cheat sheet

  • Read-only root sandbox:
bwrap --ro-bind / / {{/bin/bash}}
  • Full sandbox with /dev, /proc, and tmpfs for /tmp:
bwrap --dev-bind /dev /dev --proc /proc --ro-bind / / --tmpfs /tmp {{/bin/bash}}
  • Run a script inside the sandbox:
bwrap --ro-bind / / {{/usr/bin/python3 /path/to/script.py}}

Conclusion

Bubblewrap provides a lightweight, flexible way to isolate commands. Start with a minimal read-only root and gradually add bindings as your needs grow, keeping security and reproducibility in mind.

See Also