Skip to main content
podbox

Define once. Run anywhere.
No host daemon_

You write a TOML file. podbox turns it into an image and a set of systemd units, and from then on systemd does the rest. Nothing of podbox keeps running on your machine.

Version v0.8.2CI passingLicense MITPlatform Linux, rootless
Get StartedRead DocumentationGitHub
bash
1# Grab the binary & verify
2curl -fsSL https://bethropolis.github.io/podbox/install.sh | sh
bash
1# Install as a mise tool (Linux only)
2mise use -g github:bethropolis/podbox
bash
1# Homebrew (Linux only)
2brew install bethropolis/homebrew-tap/podbox
bash
1# Arch Linux, via AUR (binary, fast)
2paru -S podbox-bin
3 
4# ...or build from source
5paru -S podbox
bash
1# From crates.io (supports prebuilt images only)
2cargo install podbox-cli

Note: the crates.io build supports prebuilt images only (image_ref in your config, or podbox create ghcr.io/bethropolis/podbox:<tag>). Custom image builds need a full source build from the workspace.

bash
1# Source install (builds CLI & guest daemon)
2git clone https://github.com/bethropolis/podbox
3cd podbox && scripts/install.sh   # installs to ~/.local/bin
first run
1# Spin up a prebuilt Fedora container and hop in
2podbox create fedora
3podbox enter fedora
* That's a prebuilt environment with no config file neededRead the Getting Started guide
what you get

A container you can rebuild from a file

Your home directory stays out of it unless you ask. Everything else is written down first.

One TOML file

Image, packages, mounts and runtime in a single file you can commit. No flags to retype.

systemd runs it

Autostart, restart and socket activation come from systemd. No podbox daemon runs on your machine.

Your screen and sound

GUI apps and games work, with GPU acceleration. Wayland, PipeWire and graphics are handled for you.

Filtered D-Bus

The session bus is not handed over whole. Only the interfaces you allow reach the host.

Apps without a shared home

Export a desktop entry to your launcher or a tool to your PATH, with no home directory shared.

Fast starts

Packages are baked into the image at build time, so containers start in milliseconds.

comparison

podbox, Distrobox, or raw podman

Distrobox shares your home and gets out of the way. podbox shares nothing until you write it down.

Comparison of podbox, Distrobox/Toolbox, and raw Podman capabilities
WhatpodboxDistroboxRaw podman
Your filesIsolated by defaultWhole $HOME mountedManual -v flags
ConfigOne TOML fileCommand-line flagsFlags every run
Lifecyclesystemd unitsWrapper scriptsYou start it
Desktop busFiltered proxyWhole session busWhole session bus
Screen, sound, GPUShared, GPU optionalShared by defaultManual device flags
Alerts, clipboardWorks, no shared busVia the shared busNot supported
Host commandsOpt-in and filtereddistrobox-host-execNot supported
Built-in packagesBaked into the imageReinstalled each buildn/a
ReproducibleYes, from the filePartly, image onlyNo
RuntimesPodman onlyPodman, DockerAny

Both projects are reasonable. Distrobox optimises for feeling like the host; podbox optimises for reproducing the same environment from a file.

how it works

How it works

Click any box to see what that part does.

definition.tomlDeclarative configpodbox buildPure codegen, no daemonOCI ImagePackages baked inQuadlet units.container .socket .build+ companion servicessystemd --userOwns the lifecycle
Compiler & SynthesisVerified Spec

podbox build / Pure Codegen Engine

A purely declarative compiler with no persistent background daemon. Parses the TOML, embeds the guest daemon binary into the container build context, writes a multi-stage Containerfile, and generates standard systemd Quadlet unit files.

Key Architecture Guarantees
  • ›Pure function: TOML -> Containerfile + Quadlet units
  • ›Zero memory overhead when idle; terminates upon build completion
  • ›Supports prebuilt registry tags or custom multi-package baking
Explore full architecture documentation
try it

Build your container

Flip a switch, see the podbox.toml and the .container unit it produces. Studio has everything else.

The basics
Name

Used for the container, its folder and its systemd unit.

Base image
Packages to install

Baked into the image, separated by commas.

What the container can use
Graphics
GPU access
Your config
Open in Studio
# podbox.toml for dev-box
[image]
name = "dev-box"
base = "fedora:44"
 
[image.packages]
install = ["neovim", "ripgrep", "git", "fish"]
 
[container]
name = "dev-box"
home = "~/containers/dev-box"
 
[integration]
wayland = true
audio = true
gpu = "auto"
dbus = true
 
[integration.xdg_dirs]
projects = { enabled = true, read_write = true }
 
[lifecycle]
quadlet = true
on_stop = "keep"
every day

The commands you will actually use

Build the image

# Build current directory's podbox.toml
podbox build .
 
# Or build from a specific config
podbox build ~/configs/fedora.toml

Get in, or run one command

# Start container (if stopped) and enter shell
podbox enter fedora
 
# Or run a command directly inside without entering
podbox exec fedora -- cargo check

Put an app on your desktop

# Export desktop application (.desktop file)
podbox export app code
 
# Export CLI tool to ~/.local/bin on host
podbox export bin rg

See what it is doing

# Check systemd user service status
systemctl --user status podbox-fedora.service
 
# View container logs via journald
journalctl --user -u podbox-fedora.service -f
requirements

Before you start

What you'll need

  • ✓Podman 5.5 or newer (5.6+ for SSH agent passthrough)
  • ✓A systemd user session
  • ✓Linux with a Wayland compositor (X11 apps work via Xwayland)
  • optionalxdg-dbus-proxy, for filtered D-Bus access

Something not working?

Run podbox doctor first. It catches most setup problems on its own, and the troubleshooting guide goes deeper.

bash
podbox doctor