Bubblewrap is a low-level unprivileged sandboxing tool written in C that enables container features for regular users without requiring root privileges. It serves as a foundational component for larger container projects like Flatpak and is designed specifically to address the security limitations of traditional container tools such as systemd-nspawn and Docker, which are unsuitable for unprivileged users because they can trivially be exploited to gain full root access on the host system.
The tool leverages Linux kernel user namespaces to construct sandboxes safely. User namespaces allow unprivileged users to access container features that were previously restricted to administrators. Bubblewrap's codebase has historical roots in the xdg-app helper and linux-user-chroot projects, representing an evolution of unprivileged sandboxing approaches. The project no longer supports setuid mode, having fully committed to user namespace-based operation.
Bubblewrap operates by creating a new, completely empty mount namespace with a tmpfs root that is invisible from the host and automatically cleaned up when processes exit. Users can then construct the root filesystem and process environment through command-line options. The tool always creates a new mount namespace and allows users to specify exactly which filesystem parts should be visible in the sandbox. By default, mounted directories are marked nodev and can be made read-only.
The sandboxing capabilities include support for multiple Linux kernel features. User namespaces hide all but the current uid and gid from the sandbox while allowing uid/gid remapping. IPC namespaces provide isolated System V shared memory and semaphores. PID namespaces prevent the sandbox from seeing external processes and include a trivial pid1 implementation to handle child reaping, addressing the Docker pid 1 zombie problem. Network namespaces isolate the sandbox network with only a loopback device. UTS namespaces provide isolated hostnames. Seccomp filters restrict which system calls are available in the sandbox.
Security is enforced through PR_SET_NO_NEW_PRIVS to disable setuid binaries, closing the traditional chroot escape vector. The maintainers believe bubblewrap does not enable privilege escalation even when combined with typical distribution software, though it may increase denial of service capabilities for logged-in users.
Importantly, bubblewrap is a tool for constructing sandboxes rather than a complete ready-made sandbox with a specific security policy. The level of protection between sandboxed processes and the host is entirely determined by command-line arguments. Frameworks like Flatpak, libgnome-desktop, and sandwine are responsible for defining their own security models and choosing appropriate bubblewrap arguments.
Enhancement requests and help-wanted issues are the most active labels. The repository overlaps with major projects including microsoft/vscode, rust-lang/rust, and microsoft/typescript through shared contributors, indicating its integration into broader ecosystems.
Bubblewrap is available in most Linux distribution package repositories and can be built from source using meson. The tool is used by Flatpak, rpm-ostree unprivileged mode, and bwrap-oci, with potential applications in Kubernetes and OpenShift clusters for enabling unprivileged user container features in interactive debugging scenarios.
