devbox

Warning: this project is still experimental. It has only been tested on CachyOS and MacOS so far. Other Linux distros, and Windows environments are still untested. Use it at your own risk.

devbox gives you an isolated Podman-backed workspace for agent-driven development. You create a box from a repo, open a shell inside it, and work there without mounting your home directory directly into the container.

Inside the container, the shell starts in /workspace and the imported or cloned repo lives under /workspace/<repo-name>.

Install

Prerequisite: Podman must be installed and working.

On macOS, Podman runs through a Podman machine VM, so you need:

podman machine init
podman machine start

macOS support is expected through Podman machine, but is not tested yet.

uv tool install --from . devbox

Use

devbox build-image
devbox create --name mybox --from-path /path/to/repo
devbox shell mybox --network open

For other commands:

devbox help

Config

devbox creates ~/.config/devbox/config.toml automatically on first use. Edit it if you want to configure agent API keys.

create does not build the image for you. Build or refresh it explicitly with:

devbox build-image

If you change the image or runtime behavior, existing boxes are unsupported. Delete the old box and create a new one after rebuilding the image.

Agent tooling

The container image ships with Claude Code, Codex, and pi pre-installed. Each box gets its own ~/.claude, ~/.codex, and ~/.pi directories.

devbox reuses your host auth automatically:

• If ~/.codex/auth.json exists on the host, it is mounted read-only into the box.
• If ~/.claude/.credentials.json exists on the host, it is mounted read-only into the box.
• If Codex auth is found, devbox also bootstraps pi to use the openai-codex provider so it works out of the box.

Security model

• The box uses rootless Podman.
• Your real home directory, ssh config, and git config are not mounted.
• The container runs with dropped capabilities, no-new-privileges, a read-only root filesystem, private cgroup namespace, and limited writable paths.
• This is a hardened dev container, not a VM. If your threat model requires stronger isolation, consider running inside a VM instead.

Tracking human-reviewed commits

When using agent-assisted development, you can tag the last commit that had a human review:

git tag -f last-human-review HEAD
git push origin last-human-review -f

To see what the agent changed since your last review:

git log last-human-review..HEAD
git diff last-human-review..HEAD

Contributing

Issues and PRs are welcome.

If you test devbox other setups, please report what worked and what did not.