Run a program in a bubblewrap sandbox. No profiles: the system is read-only, your real home is hidden, and the program gets a private home.
sbx firefox
sbx --net=none --here python3 script.py
sbx-gui is an optional GTK4/libadwaita editor for the settings files.
Needs Linux, Python 3.8+ and bubblewrap (0.8+ for userns=0).
Optional: GTK 4 + libadwaita 1.5 + PyGObject (GUI), xdg-dbus-proxy (portals), pasta (net_private), systemd-run (limits).
sudo apt install bubblewrap # or your distro's equivalent
sudo install -m755 sbx sbx-gui sbx-selftest sbx-report /usr/local/bin/
sbx doctor # checks everything works
Man page and completions:
sudo install -Dm644 sbx.1 /usr/local/share/man/man1/sbx.1
sudo install -Dm644 completions/sbx.bash /usr/local/share/bash-completion/completions/sbx
sudo install -Dm644 completions/_sbx /usr/local/share/zsh/site-functions/_sbx
sudo install -Dm644 completions/sbx.fish /usr/local/share/fish/vendor_completions.d/sbx.fish
sbx desktop --install-menu # sbx-gui in the app menu
sbx desktop --install-installer # right-click a folder or archive: Open With Other Application, Install in sbx
Ubuntu 24.04+: AppArmor blocks user namespaces. sbx doctor shows the fix.
- System: read-only
- Your home: hidden, replaced by
~/.sbx-homes/NAME /tmp,/run: empty tmpfs- Secrets (
/etc/shadow, SSH host keys, other users): emptied - Environment: cleared, except locale, terminal and desktop variables
- Network: shared unless
net=0ornet_private=1
It starts in its private home. Use full paths, or --here to share the current folder.
sbx [options] PROGRAM [args]
sbx preview ... print the command instead of running it
sbx show NAME settings that apply, and where each came from
sbx list programs you set up
sbx stop NAME
sbx clean NAME delete a private home
sbx reset NAME delete settings files, defaults apply again
sbx rebind NAME accept a moved program as the same one
sbx export [NAME] settings as one text file (-o FILE)
sbx import FILE load an export back
sbx link NAME typing NAME starts it through sbx
sbx open FILE run a downloaded program ("Open with")
sbx install SRC move a program (folder or archive) to ~/Apps/NAME, menu entry through sbx (--link: terminal command)
sbx uninstall NAME remove a program made by sbx install (--trash: its folder goes to the Trash)
Options go before the program name.
sbx install ~/Downloads/anki-26.9.4-linux-x86_64.tar.zst # or the extracted folder; NAME is guessed (anki), or give one
# an app-menu entry starts it through sbx; add --link for a terminal command (typing: anki)
sbx uninstall anki
The program goes to ~/Apps/NAME and is shared with it read-only. Its launcher loses the execute bit, so ./launcher outside sbx fails with "Permission denied" and only sbx can start it (sbx sets the bit for its own run; this works for dynamically linked programs, and static ones keep the bit with a warning). Files the program saves go to its private home. The other files in the folder keep their execute bit, because the program starts them itself inside the sandbox. A folder you install is moved, not copied; an archive is unpacked and left where it is. Nothing in it is run.
| Option | Effect |
|---|---|
--net=none |
no network |
--net-private |
no localhost or local services (needs pasta) |
--private |
erase private home on exit |
--here |
share current folder, read-write |
--whitelist=PATH / --read-only=PATH |
share a path, read-write / read-only |
--name=NAME |
separate home and settings |
--memory=2G --tasks=512 --cpu=200% |
limits |
--gtk-portal=auto|1|0 |
with --portals: tell GTK programs to use the file chooser portal. auto (default) does, except when your desktop's cursor size is 0, which crashes GTK (sbx says so); 1/0 force it. Setting: gtk_portal |
--ignore-config |
ignore settings files |
Everything else: sbx --help, man sbx (includes downloaded and moved programs).
A name is tied to the file that first ran under it. A moved file with the same content keeps its program. Other content under the same file name takes over once the original is gone. Files a program wrote next to its own file move with it. If sbx can't tell, the program waits for sbx rebind NAME. Details: man sbx.
Plain key=value. ~/.config/sbx/default.conf applies to all programs, ~/.config/sbx/apps/NAME.conf to one.
net=0
portals=1
whitelist=~/Projects
memory=2G
A program that reads or creates files in the folder it starts in needs folder=1 (a switch in sbx-gui: "Start in the program's own folder"). It starts in the folder its file sits in and shares that folder read-write. The program must sit in a folder of its own: your home, Downloads, Desktop, Documents and hidden folders are never shared, and sbx warns why. --here is the same for the folder you are in. Without a folder setting, a program that sits in a folder named after it (G-Diffuser/, G-Diffuser-v1.2.3-linux-x64/) gets this automatically, and sbx says so on start. folder=0 turns that off.
Environment variables: setenv=NAME=value sets one for the program, env=NAME passes your own value through (also --setenv=NAME=value). sbx-gui has a list for both on each program's page.
sbx show NAME lists every setting. Flags beat files and can only make things stricter.
Back up or move settings with sbx export -o FILE and sbx import FILE (--force replaces settings that differ); sbx-gui has the same buttons.
sbx-trace is a separate program, not part of this repository. It runs a program under bpftrace and reports which files it opened, looked for or changed, and which attempts failed (refused, read-only, or hidden by the sandbox). It works with sbx: sbx-trace sbx firefox traces a program in the sandbox, and sbx-trace --suggest prints read_only= / whitelist= lines for what was refused.
python3 test_sbx.py # all tests (isolation tests need bubblewrap)
sbx ./sbx-selftest # inside the sandbox: every row should say PASS
sbx ./sbx-report # what the program can reach
Failed runs are logged to ~/.local/state/sbx/sbx.log.
sbx and sbx-gui are generated. Edit src/ and src/gui/, run python3 build.py, commit the result. python3 build.py --check runs in CI.
- Convenience sandbox, not a security boundary against hostile programs. The syscall filter is a blocklist.
- Wayland without security-context support gives the program the full socket (a warning is shown).
wayland_strictis on by default where the compositor supports security contexts, so a failed attempt there gives no Wayland instead of the full socket; where it can't, it is off and sbx-gui greys the switch out. Set it yourself to override. net_private=1is not a firewall: your local network stays reachable.- Read-write shares (
--here,whitelist=) let the program plant files that later run outside the sandbox. Share only what it needs. - 32-bit programs (Wine, Steam) fail. Terminal programs have no
/dev/tty, so password prompts don't work. - One private home per name: use
--namefor separate ones.
GPL-3.0-or-later. See LICENSE.
