podbox-cli

A declarative container environment manager for Linux, built on Podman and systemd Quadlet. Define an environment as a single TOML file; podbox turns it into an OCI image and the systemd units that own its lifecycle. No podbox daemon runs in the background.

Think distrobox, but the environment is a file you can commit to git instead of a sequence of flags you ran once and forgot.

GUI-capable dev containers with Wayland, D-Bus, clipboard, notifications, and host-command integration, all routed through a small guest interceptor.

Install

cargo install podbox-cli

The crates.io build works with prebuilt images — any image that already ships the podman guest, whether that's your own (podbox create ghcr.io/you/img:<tag>) or the official ones built from the images/ directory (podbox create cachy). Only fresh builds from a bare base ([image] base) require a workspace build to embed the guest.

Quick start

podbox create cachy          # prebuilt environment, ready in seconds
podbox enter cachy           # hop in
podbox export app firefox    # pull apps and binaries out to the host

Requirements

• Podman ≥ 5.5
• A systemd user session
• Linux with a Wayland compositor

Run podbox doctor to check your setup, and podbox --help for the full command list.

See the source repository for the getting-started guide, configuration reference, and troubleshooting.