BubbleBox: Simple Application Sandboxing


This is the documentation of BubbleBox, a tool to easily sandbox Linux applications.

The primary use-case for BubbleBox is running applications that you do not trust enough to give them full access to hour home directory, and in particular the secret keys stored there. BubbleBox is based on bubblewrap and xdg-dbus-proxy which do all of the heavy lifting.

The goals of this project are similar to firejail, but I found firejail’s configuration to be extremely hard to maintain and debug. BubbleBox is meant for people that are comfortable editing its Python source code to adjust it to their needs; if you are looking for something with a more out-of-the-box experience, try bubblejail.


The typical way to use BubbleBox is to create a new “jail” script in the BubbleBox source folder. For instance, if you want a “gamejail” that you can use to run games, create a file gamejail in a BubbleBox checkout with contents like this:

from bubblebox import *


    ".steam": Access.Write,

Then add a symlink to this file somewhere to your PATH, and now you can use gamejail <application> to run arbitrary games inside the BubbleBox.

Configuration directives

A BubbleBox sandbox is configured by passing a list of directives to the bubblebox functions that declare things the sandbox has access to. Everything else is blocked by default.

These directives are basically lists of bubblewrap and xdg-dbus-proxy flags, but BubbleBox provides some convenience functions to allow higher-level configuration and to share common patterns.

The profiles.py file contains some useful directives that are needed by most applications:

I recommend looking at the sources in default.py to learn how to configure your own sandboxes. Here are the key directives to use:

Source, License

You can find the sources in the git repository (also available on GitHub). They are provided under the GPLv2 or (at your option) any later version of the GPL. See the file LICENSE-GPL2 for more details.


If you found a bug, or want to leave a comment, please send me a mail. I’m also happy about pull requests :)