Define once. Run anywhere. No daemon.
# Install via pre-built binary
curl -fsSL https://bethropolis.github.io/podbox/install.sh | sh
podbox create fedora # pulls, enables, starts
podbox enter fedora # you're inAlso available from source: git clone https://github.com/bethropolis/podbox && cd podbox && scripts/install.sh.
See the Getting Started Guide for both prebuilt and custom build workflows.
Most desktop container tools make a trade-off: full integration means mounting your entire home directory into the container. podbox doesn't. You declare exactly what the container can see — directories, devices, and services — and nothing else is shared.
| podbox | Distrobox / Toolbox | Raw podman run |
|
|---|---|---|---|
| Home directory | Isolated volume, opt-in sharing | Full $HOME mounted by default |
Manual -v flags |
| Config | Declarative TOML, version-controllable | Imperative CLI flags | Shell flags per run |
| Lifecycle | systemd Quadlet units | Shell shims | Manual |
| D-Bus | Filtered via xdg-dbus-proxy |
Unfiltered session bus | Unfiltered |
| Wayland / audio | Opt-out (on by default) | Always on | Manual |
| GPU | auto / nvidia / off |
--nvidia flag |
Manual device flags |
| Notifications | Guest interceptor → host | Via shared D-Bus | Not supported |
| Clipboard | Guest interceptor → host | Via shared home | Not supported |
| Host commands | host-exec interceptor |
distrobox-host-exec |
Not supported |
| SSH agent | Socket forward (opt-in) | Auto-mounted | Not supported |
| Baked images | Yes — packages in image, not runtime | No — packages reinstalled on rebuild | N/A |
| Reproducibility | Full — TOML → image → unit | Partial — image only | None |
| Runtime | Podman only | Podman / Docker / lilipod | Any OCI runtime |
podbox is not a distrobox replacement. Distrobox optimises for maximum host integration and is excellent at that. podbox optimises for declared, reproducible environments where you control exactly what is shared.
A single TOML definition is your single source of truth. podbox build processes it into OCI images and systemd Quadlet units — no manual Containerfile or systemd editing.
Config files are loaded from ~/.config/podbox/<name>.toml, ./.podbox.toml, your active context (podbox use <name>), or built-in profiles. See the config reference for all keys.
Prebuilt (quick):
podbox create cachy # Arch-based, gaming-ready
podbox create fedora --name dev # Fedora, custom nameCustom build (from a base image):
podbox init fedora:44 --name myenv # scaffold a non-prebuilt config
podbox create myenv # build, enable, startOne-shot with any OCI image:
podbox create ubuntu:24.04 --name dev # pulls, configures, enables, starts
podbox create ghcr.io/user/img --name myenvInteractive wizard (both paths):
podbox init -i # pick "Custom" or a profileActive context — set once, then bare commands work:
podbox use myenv # "Active context set to 'myenv'"
podbox status # targets myenv
podbox logs # targets myenv
podbox exec -- htop # runs inside myenvRun things:
podbox enter myenv # interactive shell
podbox exec -- htop # run a command
podbox run firefox # GUI app, detachedExport to your host:
podbox export app firefox # "Firefox (cachy)" in your launcher
podbox export bin rg # ripgrep available in any terminalOnline (pre-built binary):
curl -fsSL https://bethropolis.github.io/podbox/install.sh | shLocal source build:
scripts/install.sh # ~/.local/bin
scripts/install.sh --system # /usr/local (sudo)Supports linux/x86_64. Uninstall with scripts/uninstall.sh.
- Podman >= 5.5 (SSH agent requires >= 5.6)
- systemd (user session)
- Linux with Wayland (X11 apps run via Xwayland)
- Kernel:
kernel.unprivileged_userns_clone=1, subuid/subgid configured xdg-dbus-proxy(for filtered D-Bus access)
Run podbox doctor first — it checks the most common issues automatically and explains what to fix.
For detailed guides on specific issues (container won't start, D-Bus proxy, Wayland socket errors, interceptors, UID mapping, SSH agent forwarding, build failures, shell hangs), see the Troubleshooting Guide.
Most commands accept an optional [<name>] — defaults to active context, then -C, then PODBOX_CONTAINER, then interactive picker.
| Command | Description |
|---|---|
podbox create <profile|image> |
Init → build → enable → start in one command |
podbox create <image> --name <n> |
Pull + create config + enable + start in one step |
podbox init |
List available profiles |
podbox init <image> |
Scaffold a custom config from a base image |
podbox init -i |
Interactive wizard (custom or profile) |
podbox init --profile <name> |
Scaffold from a prebuilt profile |
podbox list |
List podbox-managed containers |
podbox build [--rebuild] |
Build or rebuild the container image |
podbox enable |
Install Quadlet systemd files |
podbox disable |
Remove Quadlet files |
podbox start / podbox stop |
Start / stop the container |
podbox enter <name> |
Enter a named container (auto-starts) |
podbox shell |
Open interactive shell (auto-detect) |
podbox exec -- <cmd> |
Execute a command interactively |
podbox run <app> |
Run a GUI app detached |
podbox status |
Show container state |
podbox logs |
Show container logs |
podbox diff |
Compare installed packages against config |
podbox pull <name> |
Pull a prebuilt image without building |
podbox doctor [--fix] |
Run diagnostic checks, optionally auto-fix |
podbox use [<name>] [--clear] |
Manage active context |
podbox find-definition [<name>] |
Print path to the matching config TOML |
podbox export app <name> |
Export .desktop file to host launcher |
podbox export bin <name> |
Export bin shim to ~/.local/bin |
podbox export clean |
Remove all exported shims and .desktop files |
podbox remove [--all] |
Remove the container (and home volume with --all) |
podbox translate-path --to-container <path> |
Translate host path to container path |
podbox translate-path --to-host <path> |
Translate container path to host path |
podbox completions <shell> |
Generate shell completions |
All commands support --dry-run to preview without executing.
PODBOX_CONTAINER— set inside the container to the active container namePODBOX_VERSION— the running launcher versionPODBOX_HOST_VERSION— set inside the container at build time; checked at guest daemon startup
| Doc | Description |
|---|---|
| Getting Started Guide | Prebuilt and custom workflows |
| Configuration Reference | All TOML keys, defaults, examples |
| Baked-in Base Packages | Auto-installed packages, locale, timezone, sudo |
| Architecture Overview | How podbox works end-to-end |
| Desktop Integration | Exporting apps and binaries |
| Container Integration | Guest daemon and interceptors |
| D-Bus Proxy | Filtered D-Bus access via xdg-dbus-proxy |
| Quadlet Reference | Generated systemd units |
| Host-Guest Protocol | Wire format and message types |
| Troubleshooting Guide | Common issues and fixes |
See Contributing.
MIT