explaingit

containers/bubblewrap

7,122CAudience · ops devopsComplexity · 4/5Setup · moderate

TLDR

Bubblewrap is a Linux command-line tool that lets regular users run programs in an isolated sandbox without root access, using Linux kernel user namespaces to restrict what files, network, and system calls a process can reach.

Mindmap

mindmap
  root((Bubblewrap))
    What it does
      Unprivileged sandbox
      Filesystem isolation
      No root needed
    Tech Stack
      C
      Meson
      Linux namespaces
      seccomp
    Use Cases
      App sandboxing
      Flatpak backend
      Untrusted code
    Security
      Seccomp filters
      Mount control
      Network isolation
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Things people build with this

USE CASE 1

Build a custom application sandbox on Linux that restricts which files and system calls a program can access, without requiring root privileges.

USE CASE 2

Use bubblewrap as the underlying isolation layer in a Linux desktop application packaging tool like Flatpak.

USE CASE 3

Run an untrusted program in a restricted filesystem view where it can only see the directories you explicitly allow.

USE CASE 4

Apply seccomp filters to limit which kernel system calls a sandboxed process is permitted to make.

Tech stack

CMesonLinuxseccomp

Getting it running

Difficulty · moderate Time to first run · 30min

Available in most Linux distro package repos, building from source requires Meson and a C compiler.

In plain English

Bubblewrap is a low-level Linux tool that lets a regular user run a program inside an isolated environment without needing administrator access. Most container tools require root or elevated privileges to operate, which makes them unsuitable for ordinary users because that level of access can be exploited to take full control of the host machine. Bubblewrap avoids this by relying on a Linux kernel feature called user namespaces, which allows unprivileged users to create isolated environments where a process sees a restricted view of the system. The tool is primarily used as a building block by other software rather than directly by end users. Flatpak, the application sandboxing system used on many Linux desktops, uses bubblewrap internally to isolate the apps it runs. Other container-related tools in the same ecosystem also rely on it. When you run a program through bubblewrap, it starts in a fresh, empty filesystem that is invisible to the rest of the host. You then pass command-line arguments to specify exactly which parts of the real filesystem the sandboxed program is allowed to see, whether those parts are read-only or writable, and whether the process can access the network or see other running processes. You can also apply seccomp filters, which restrict which low-level operating system calls the sandboxed process is permitted to make. Bubblewrap does not come with its own security policy built in. The security of any sandbox built on top of it depends entirely on the arguments passed when launching it. The README includes a section on limitations, noting specific cases where a poorly constructed sandbox can still allow a process to affect the host, such as through D-Bus sockets or the absence of certain seccomp filters. The tool is available through the package repositories of most Linux distributions and can also be built from source using the Meson build system.

Copy-paste prompts

Prompt 1
Show me a bubblewrap command that runs a program isolated with read-only access to /usr and /lib but no access to my home directory or network.
Prompt 2
I want to use bubblewrap to sandbox a desktop app on Linux. Walk me through the arguments for binding mount points and restricting filesystem access.
Prompt 3
How do I compile bubblewrap from source using the Meson build system on Ubuntu?
Prompt 4
Explain the difference between --ro-bind and --bind in bubblewrap and when I would choose one over the other.
Prompt 5
How does bubblewrap use Linux user namespaces to run sandboxes without root? Explain the security model and its documented limitations.
Open on GitHub → Explain another repo

← containers on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.