agent-box-tool

---

Why agent-box?

AI coding agents are useful, but running them directly on your workstation gives them the same files, credentials, tools and processes that you have. agent-box runs Claude Code and Codex CLI inside a rootless Podman container while keeping the workflow close to local development:

• Workspace isolation — only the project root and the mounts you ask for are exposed.
• One box per project — Claude, Codex and agent-box shell share the same container.
• Same paths as the host — /home/you/code/project is /home/you/code/project inside the box too.
• Persistent agent state — logins, settings and history stay in your host's ~/.claude and ~/.codex.
• Detachable sessions — sessions run under tmux and survive a closed terminal or a dropped SSH connection.
• Nothing exposed by accident — every credential, host directory and optional capability is a switch you turn on.

[!IMPORTANT] A workspace box is one trust boundary. Claude, Codex, shells, hooks and daemons inside the same box share the same Unix user and PID namespace.

Requirements

• Linux
• Python 3.11 or newer (standard library only)
• Rootless Podman 5.0 or newer — agent-box does not fall back to Docker
• Git
• Optional: gh, to pass a GitHub token into the box

agent-box checks all of this before starting a box and prints the command that fixes anything missing. Details: Installation.

Installation

# 1. Install from PyPI.
uv tool install agent-box-tool
uv tool update-shell   # if the installer reports PATH setup is needed

# 2. Reopen the shell if PATH changed, then configure integrations.
agent-box config

The distribution is agent-box-tool; the command stays agent-box. pipx, public Git and editable installs are also supported.

3. Log in with claude and codex on the host; agent-box reuses those logins.
4. Start a session in your project. The workspace image is built automatically the first time, which takes a few minutes once.

cd ~/code/my-project
agent-box claude          # or: agent-box codex

Shell completion, updating and uninstalling are covered in Installation.

Quick start

agent-box                 # the default agent (Claude unless you choose Codex)
agent-box shell           # a shell in this project's box
agent-box attach          # reattach a detached session (detach with Ctrl-\ d)
agent-box stop            # end the box and every session in it
agent-box --host codex    # run the host's CLI directly, without a container
agent-box doctor          # check the box and its integrations

Options before the agent apply to one launch, for example agent-box --mount ~/specs:ro --env DATABASE_URL claude. See Usage for all of them.

How it works

flowchart LR
    Host["Host workspace"] --> Launcher["agent-box"]
    Launcher --> Box["Rootless Podman workspace box"]

    Box --> Claude["Claude Code"]
    Box --> Codex["Codex CLI"]
    Box --> Shell["Shell"]

    Claude --> Tmux["tmux sessions"]
    Codex --> Tmux
    Shell --> Tmux

    State["~/.claude / ~/.codex"] -. host-backed state .-> Box
    Project["Project root\nsame absolute path"] -. explicit bind mount .-> Box

Workspace box. The first command in a project creates its box; later commands join it. A different project gets a different box, and a box with no workload left exits and is removed. The box mounts the Git top level of the current directory and your agent state; any other host path, credential or device only when you enable it.

Host mode. --host runs your installed claude or codex directly, with your own environment and credentials. Tracker, workflow and model routing behave the same. Extra workspace mounts remain container-only. The optional isolated browser uses a separate Podman container in either mode.

Configuration. Built-in defaults, then your global ~/.config/agent-box/config.json, then the repository's .agent-box.json. agent-box config edits settings and applies integrations. The first host launch after a package update refreshes configured integrations automatically; unchanged launches leave them alone. See compatibility and upgrades.

Documentation

The full index, including design records for contributors, is in docs/.

License

MIT — see LICENSE.