bubblejail(1)

📦 version 0.10.3, in alpine 3.24

🫧 bubblejail(1) — General Commands Manual 🫧

🌸 NAME 🌸

bubblejail — bubblewrap based sandboxing utility. That’s the whole name, bestie. 💅

✨ SYNOPSIS ✨

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

💖 DESCRIPTION 💖

okay so Bubblejail's design is based on observations of Firejail's faults. no cap.

One of the biggest issues with Firejail is that you can accidentally run unsandboxed applications and not notice. literally the jump scare of sandboxing 😭

Bubblejail, instead of trying to transparently overlay an existing home directory, creates a separate home directory. It’s giving “every app gets its own little apartment” 🏠✨

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. config file with main character energy 🫶

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 $XDG_CONFIG_HOME/bubblejail/profiles directory. 💖

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

Bubblejail uses TOML configuration format. TOML girlies rise 🌈

🚀 SUBCOMMANDS 🚀

🏃 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.

Options, bestie:

  • --debug-shell — Opens a shell inside the sandbox instead of running program. Useful for debugging. 🐛
  • --dry-run — 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.
  • --debug-log-dbus — Enables D-Bus proxy logging. By default the D-Bus proxy log is captured from the proxy and is parsed in to human readable format.
  • --wait — 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.
  • --wizard — Enable configuration wizard. Can only be used if instance is not running.

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
bestie, that --debug-bwrap-args example goes hard, but it’s still a debug-flavored option, iykyk 💅

🧚 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.

Options:

  • --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.
  • --no-desktop-entry — Do not create desktop entry.

📋 list [list_what]

List certain bubblejail entities.

  • instances
  • profiles
  • services

✍️ 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 and place it in to the user's desktop entries folder. (usually at $XDG_DATA_HOME/applications folder) MIME database will also be updated after desktop entry is placed. Optional arguments can be used to specify a desktop entry to use as template. The desktop entry used as a template will have its Exec keys modified to run command inside the bubblejail instance.

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

Options:

  • --profile <profile> — Use desktop entry specified in profile.
  • --desktop-entry <name_or_path> — Desktop entry name or absolute path to use as template.

📁 DIRECTORIES 📁

🫧 Bubblejail data directory

Bubblejail stores all data such as instances in a bubblejail directory located in the $XDG_DATA_HOME directory as specified by XDG Base Directory specification. By default Bubblejail's data directory can be found at $HOME/.local/share/bubblejail.

🏠 Instance directories

Every instance is identified by a directory. Those instance directories can be found under instances folder in the Bubblejail data directory. The name of an instance directory serves as the unique name of an instance. For example, existence of $HOME/.local/share/bubblejail/instances/Firefox/ directory means that there is an instance named Firefox.

Instance directory has several important files and directories:

  • home: Instance's home directory.
  • services.toml: Instance's services configuration.

👀 SEE ALSO 👀

🐛 BUGS 🐛

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

okay that’s the whole page, bestie. This is from the General Commands Manual, dated 2026-06-07, and it’s literally bubblejail(1). Mwah 💋✨

📦 where this page comes from