bwrap

Run a program in a read-only environment

$ bwrap --ro-bind / / [/bin/bash]

$ bwrap --dev-bind /dev /dev --proc /proc --ro-bind / / --tmpfs /tmp [/bin/bash]

bwrap [OPTION...] [--] PROGRAM [ARG...]

--help
    Display help and exit

--version
    Output version info and exit

--args <N>
    Expect N args (for caps/auditing)

--as-pid-1
    Run PROGRAM as PID 1 (e.g., for systemd)

--bind <old> <new>
    Bind mount <old> rw to <new>

--bind-data <data> <old> <new>
    Bind with fstype/options <data>

--cap-add <CAP>
    Add Linux capability CAP

--cap-drop <CAP>
    Drop Linux capability CAP

--chdir <DIR>
    Chdir to DIR in sandbox

--clearenv
    Clear all environment variables

--dev <PATH>
    Bind /dev/PATH rw to same name

--dev-bind <old> <new>
    Bind /dev/old rw to new

--dev-pid-file <FILE>
    Write sandbox PID to FILE in /dev

--dir <DIR>
    Create empty dir DIR

--dir-bind <old> <new>
    Bind old ro to new

--exec-label <CONTEXT>
    Set SELinux exec label

--file <FD> <PATH>
    Move FD to PATH

--hostname <NAME>
    Set hostname

--idmap-lowest <UID>
    Start uidmap at UID

--idmap-next <RANGE>
    Add idmap range

--ifsock <FD> <PATH>
    FD to unix sock PATH

--ipc-nns
    New IPC namespace

--lock-label <CONTEXT>
    SELinux lock label

--max-threads <N>
    RLIMIT_NPROC to N

--netns <PATH|PID>
    Join netns by path/PID

--new-session
    New session

--newpid
    New PID namespace

--noatime [<REGEX>]
    Noatime on matching mounts

--nofile <N>
    RLIMIT_NOFILE to N

--nogroup
    No supplementary groups

--noprofile
    Skip profile loading

--nosymfollow
    Don't follow symlinks in binds

--notify-fd <FD>
    Write ready notify to FD

--profile <NAME>
    Load seccomp profile NAME

--profile-from-path <PATH>
    Load profile from PATH

--proc <LABEL>
    Relabel /proc

--ro-bind <old> <new>
    Bind old ro to new

--seccomp <FD>
    Load seccomp filter from FD

--seccomp-and-log <FD>
    Seccomp filter, log violations

--seccomp-remove-all <FD>
    Remove seccomp filters from FD

--setenv <VAR> <VAL>
    Set environment VAR=VAL

--share-net
    Share parent's netns

--symlink <old> <new>
    Symlink old to new

--uid <UID>
    Set UID

--unshare-all
    Unshare mount/IPC/net/PID/user

--unshare-pid
    Unshare PID ns

--unshare-ipc
    Unshare IPC ns

--unshare-net
    Unshare net ns

--unshare-user[-try]
    Unshare user ns (try if fail)

--userns2
    Use user ns v2 API

--user-json <JSON>
    User ns from JSON

--wd <PATH>
    Set working directory

bwrap (bubblewrap) is a lightweight Linux command-line tool for sandboxing applications. It leverages kernel features like mount, user, PID, IPC, network namespaces, Linux capabilities, and seccomp-BPF syscall filters to isolate processes.

Typically, bwrap creates a new mount namespace, binds host directories/files into the sandbox (read-only by default for security), drops root privileges, sets user/group IDs, and executes a program. It's designed for simplicity and speed, making it ideal for running untrusted code securely.

Developed primarily for Flatpak, it sandboxes desktop applications by providing only necessary access (e.g., home dir subsets, X11 sockets). Standalone uses include testing scripts, running exploits safely, or confining servers. Unlike heavier tools like Docker, bwrap doesn't daemonize or layer filesystems but focuses on per-invocation isolation. Security relies on correct binds and seccomp profiles; misconfiguration can escape the sandbox.

Requires kernel ≥3.8 with namespaces/seccomp. No automatic escapes prevention; user must configure binds/seccomp correctly. Not for multi-process daemons without --as-pid-1. SELinux/AppArmor may interfere.

bwrap --ro-bind /usr /usr --bind /tmp /tmp --dev /dev --proc /proc firefox

Use --profile 9 or custom JSON for syscall restriction. Profiles in /usr/share/bubblewrap/*.

Flatpak portals use bwrap internally for document/X11 access.

Created 2016 by Colin Walters (Red Hat) for Flatpak's OSTree-based sandboxing. Initial release in flatpak repo; spun out to independent libbubblewrap project. Evolved with kernel features like user ns v2, seccomp profiles. Widely adopted in Flatpak, GNOME Software.

unshare(1), firejail(1), systemd-nspawn(1), flatpak(1), seccomp(8)