bubblejail - bubblewrap based sandboxing utility

NAME  SYNOPSIS  DESCRIPTION  SUBCOMMANDS  run [options...] [instance_name] [args_to_instance...]  create [options...] [new_instance_name]  list [list_what]  edit [instance_name]  generate-desktop-entry [options...] [instance_name]  SEE ALSO  BUGS 


bubblejail - bubblewrap based sandboxing utility


bubblejail <command> [--option] [args]


Bubblejail’s design is based on observations of Firejail’s faults.

One of the biggest issues with Firejail is that you can accidentally run unsandboxed applications and not notice.

Bubblejail, instead of trying to transparently overlay an existing home directory, creates a separate home directory.

Every Instance represents a separate home directory. Typically, every sandboxed application has its own home directory.

Each instance has a services.toml file which defines the configuration of the instance such as system resources that the sandbox should have access to.

Service represents some system resources that the sandbox can be given access to. For example, the Pulse Audio service gives access to the Pulse Audio socket so that the application can use sound.

Profile is a predefined set of services that a particular application uses. For example, Firefox profiles gives access to network, pulse audio and ˜/Downloads folder. Users can define their own profiles in ˜/.config/bubblejail/profiles directory.

Profiles also specify the desktop entry to copy and MIME types the application has.

Bubblejail uses TOML configuration format.


run [options...] [instance_name] [args_to_instance...]

Launch instance or run command inside.

The arguments are optional if you have executable_name key set in config.

Otherwise, you must specify arguments to run.

The arguments must include the program executable. Example:

bubblejail run FirefoxInstance firefox google.com

If the instance already running this command will run the arguments inside the sandbox. If --wait option is passed the output of the command will be returned.



Opens a shell inside the sandbox instead of running program. Useful for debugging.


Prints the bwrap and xdg-desktop-entry arguments instead of running.

--debug-helper-script <script_path>

Use the specified helper script. This is mainly development command.


Enables D-Bus proxy logging.


Wait on the command inserted in to sandbox and get the output.

--debug-bwrap-args <bwrap_option> <bwrap_option_args>

Add extra option to bwrap. First argument will be prefixed with ‘--‘.

The instance name must be separated with extra -- from the instance name.

This option can be repeated multiple times for multiple args to bwrap.

Example with adding capability and running as UID and GID 0 for test_instance instance:

bubblejail run --debug-bwrap-args cap-add CAP_SYS_ADMIN --debug-bwrap-args uid 0 --debug-bwrap-args gid 0 -- test_instance

create [options...] [new_instance_name]

Create new bubblejail instance.

When a new instance is created a desktop entry will be also created.

Creating an instance from profile will print some import tips that you can use to import configuration from unsandboxed application.


--profile <profile>

Bubblejail profile to use.

If omitted an empty profile will be used and the user will have to define the configuration manually.

There is also a generic profile which has some common settings such as network and windowing system access.


Do not create desktop entry.

list [list_what]

List certain bubblejail entities.


edit [instance_name]

Open instance config in $EDITOR.

After exiting the editor, the file is validated and only written if validation is successful.

EDITOR environmental variable must be set.

generate-desktop-entry [options...] [instance_name]

Generate XDG desktop entry for an instance.

Desktop entry can either be specified by profile, path, name or extracted from metadata when instance was created.


--profile <profile>

Use desktop entry specified in profile.

--desktop-entry <name_or_path>

Desktop entry name or path to use.



Bubblejail home page: https://github.com/igo95862/bubblejail


Report bugs to the bugtracker: https://github.com/igo95862/bubblejail/issues

Updated 2024-01-29 - jenkler.se | uex.se