Skip to main content

agentcabin

中文

agentcabin builds and runs a container for AI coding agents with rootless podman: an Ubuntu desktop reachable over SSH and VNC, with Firefox, Claude Code, Codex, Neovim, tmux, herdr and the usual command-line tools (KiCad is one comment away). Everything is described by one TOML file, in the same layout as the one casperbox-dev init writes.

uv tool install .             # in a clone of this repository; `uv tool upgrade agentcabin` later
agentcabin init                 # writes ./agentbox.toml
$EDITOR agentbox.toml         # optional: packages, tools, ports, GPUs, mounts
agentcabin up                   # builds the image the first time (long), then starts the container
agentcabin shell                # a shell in the container
ssh -p 2222 agent@localhost   # or SSH (password: agent); VNC: localhost:5901 (password: agentbox)

Requirements on the host: rootless podman (>= 4.4), pasta (the passt package) and uv (to install the tool). For GPUs also nvidia-container-toolkit.

Commands

All commands except list, init and ps read ./agentbox.toml; pass -c FILE to use another one (also before the command: agentcabin -c FILE up).

Command What it does
agentcabin list List the tested base OS images (any apt-based image works).
agentcabin init [FILE] [--os IMAGE] [-f] Write the default config (mode 0600, it holds passwords).
agentcabin build [--no-cache] Build the image.
agentcabin up [-y] Build the image if it is missing or outdated, then create and start the container. Asks before replacing an existing one.
agentcabin down Stop and remove the container.
agentcabin restart Restart the container, keeping its data. Config changes need up.
agentcabin shell A login shell in the container as the container user.
agentcabin cp SRC DEST Copy between host and container; :PATH is in the container (agentcabin cp a.txt :~/Projects/).
agentcabin status Image state, limits, GPUs, ports and mounts of the container.
agentcabin logs [-f] Container logs.
agentcabin commit [IMAGE] [-o FILE] Save the container as an image, optionally to a tar file.
agentcabin config The resolved config and the exact podman build / podman run commands.
agentcabin ps All containers created by agentcabin, with their config files.

The image is rebuilt by up whenever anything it is built from changes: the base OS, packages, [[apt_repos]], [[tools]], [build], the user, or agentcabin's own build files.

What is in the container

  • Always (not configurable): openssh-server, TigerVNC, the XFCE desktop, Firefox (from Mozilla's apt repository, not the snap), sudo, curl, rsync. sshd and the VNC server start with the container (:1, port 5901) and are restarted if they stop.
  • From the default config, all of it removable or editable: the apt packages (git, gh, tmux, ripgrep, fzf, bat, eza, build tools, network tools, fonts, ...) and these [[tools]]: Node.js, uv, Neovim, lazygit, Starship, Maple Mono, Claude Code and Codex (npm, per user), the claude-hud plugin, the Codex config, herdr, the dotfiles (Neovim, tmux, Starship, dircolors) and the ~/.bashrc aliases.

PID 1 is entrypoint.sh (no systemd). It sets the passwords, copies the image's default Claude Code / Codex config into ~/.claude and ~/.codex, and starts and watches sshd and the VNC server.

The config file

agentcabin init writes a commented file; this is its layout, with the settings you are likely to change first and the image contents last. The parts that casperbox-dev also has behave the same; the additions are marked.

os = "ubuntu:26.04"                 # base image, name:tag (apt-based)

[container]                         # what you change most comes first ...
name = "agentbox-ubuntu-26.04"; user = "agent"; password = "agent"; vnc_password = "agentbox"
mac = ""; shm_size = "2g"; tz = "UTC"
gpus = ""                           # ADDED: "0", "0,1" or "all"
rdma = ""                           # ADDED: "all" or "mlx5_0,mlx5_1"
memory = ""; cpus = 0; cpuset = ""

[network]  mode = "pasta"                                          # ADDED: or "host"
[ports]    bind_address = "127.0.0.1"; ssh = 2222; vnc = 5901      # 0 = pick a free port; bind_address may be a NIC name
[vnc]      geometry = "1920x1080"

[[mounts]]                          # host directories; ADDED: create = true
host = "./data"; container = "~/Projects"; mode = "rw"; create = true

[[extra_ports]]
host = 8888; container = 8888; protocol = "tcp"

[build]                             # ... what goes into the image comes last
apt_mirror = ""
packages = ["git", "tmux", ...]     # extra apt packages (casperbox-dev has this key at the top level)

[[apt_repos]]                       # third-party apt repositories
name = "github-cli"; key = "https://..."; url = "https://..."; suite = "stable"; components = ["main"]

[[tools]]                           # ADDED: tools that are not apt packages
name = "node"; version = "24.21.0"; run_as = "root"   # or "user"
script = '''...'''

packages is a top-level key in casperbox-dev's layout, and TOML requires top-level keys before the first table, so it could not be moved to the end there. agentcabin therefore also accepts packages in [build], where agentcabin init puts it; the top-level form still works (set one of the two, not both).

Relative host paths are relative to the config file. Defaults differ from casperbox-dev in three values only: the user is agent, the ports are 2222/5901 and bind_address is 127.0.0.1 (a password SSH server and an unencrypted VNC server should not listen on the network by default).

[[tools]]

Each block installs one tool with a bash script during the build:

  • name (required, unique), script (required), version (optional, passed as $VERSION), run_as = "root" (default) or "user".
  • All root tools run first, then the user tools, each group in the order written. A tool can rely on the ones above it (Claude Code needs Node.js). A failing script stops the build.
  • A script sees $VERSION, $DEB_ARCH (amd64 / arm64), $CONTAINER_USER and $HOME; user tools run as the container user with ~/.local/bin on PATH.
  • Write scripts in '''...''' so backslashes and $ stay as written.
  • The default tools are written for Ubuntu (the commented-out KiCad block uses a PPA; uncomment it to install KiCad). On another OS remove the ones that do not apply.

How the software gets installed and configured

Everything below happens while the image is built (agentcabin build, or agentcabin up when the image is missing or out of date), not when the container starts. The build runs these steps in order:

  1. The base system, SSH, VNC, the XFCE desktop and Firefox (fixed, not configurable).
  2. The container user, with the host's UID so that mounted directories are writable.
  3. [[apt_repos]] are added, then packages are installed with apt.
  4. The [[tools]] with run_as = "root", in the order written in the file.
  5. The [[tools]] with run_as = "user", in the order written in the file.
  6. A copy of the Claude Code and Codex config the tools created is kept as the image's defaults.

A program and its configuration are separate tools. Take Neovim:

Tool run_as What it does
neovim root Downloads the release tarball to /opt/nvim and links nvim and vi into /usr/local/bin. This installs the program only.
dotfiles user git clone --depth 1 of the Neovim config repository into ~/.config/nvim (and the same for tmux, plus Starship and dircolors files). This is where the configuration is downloaded.
shell-config user Appends the vim=nvim alias, PATH and the Starship prompt to ~/.bashrc.

The dotfiles script is in your agentbox.toml (the original is src/agentbox/templates/agentbox.toml); open it to change the repository URL:

[[tools]]
name = "dotfiles"
run_as = "user"
script = '''
install -d "$HOME/.config"
if git clone --depth 1 https://github.com/wlsky90/wneovim-config.git "$HOME/.config/nvim"; then
    echo "neovim config installed"
else
    echo "WARNING: could not clone the neovim config; skipping it" >&2   # not fatal
    rm -rf "$HOME/.config/nvim"
fi
...
'''

All default tools:

Tool run_as What it does
node, uv, neovim, lazygit, starship root Programs installed under /usr/local or /opt.
maple-mono root The Maple Mono Nerd Font for the desktop.
command-names root Links fd and bat (Debian calls them fdfind and batcat).
ghostty-terminfo root Makes xterm-ghostty known when the OS's ncurses-term allows it; skipped otherwise.
claude-code-codex user Claude Code and Codex with npm, into ~/.local (so npm update -g needs no sudo).
claude-hud user The claude-hud plugin and its config, written into ~/.claude.
codex-config user Downloads ~/.codex/config.toml.
herdr user The terminal agent multiplexer, in ~/.local/bin.
dotfiles user Neovim, tmux, Starship and dircolors configuration (see above).
shell-config user The ~/.bashrc additions: aliases, PATH, CLAUDE_CONFIG_DIR, the prompt.

What this means in practice

  • The configuration is part of the image. Starting a container downloads nothing, so it starts fast and works offline. The configuration is a snapshot of the repository at build time.
  • Updating the configuration. In a running container the clone is a normal git repository: cd ~/.config/nvim && git pull. To change the image instead, edit the script (or run agentcabin build --no-cache): when a script has not changed, podman reuses the cached result of the last build and does not clone again, and --no-cache rebuilds the whole image, which is slow.
  • Recreating the container resets ~/.config. It is not mounted by default, so changes made in the container are lost when agentcabin up recreates it. Keep them by mounting a host directory ([[mounts]]), by pushing them to your config repository, or by copying them out with agentcabin cp.
  • A failing step stops the build, except the Neovim clone above, which only warns. Clone URLs must be reachable from where the image is built; a private repository needs credentials the build does not have.
  • Neovim plugins are not installed by the build. The script only downloads the configuration; the plugin manager of your config installs the plugins the first time you start nvim (that depends on your repository, which agentcabin does not look at). To have them in the image, add a line to the script, for example nvim --headless "+Lazy! sync" +qa if you use lazy.nvim.

Claude Code and Codex configuration

claude-hud and codex-config write into ~/.claude and ~/.codex during the build. The default config mounts host directories (./agents/claude, ./agents/codex, ...) over those paths, and a mount hides what the image has there. So the build keeps a copy of both directories in /usr/local/share/agentbox/defaults, and the container's entrypoint copies it into the mounted directories at every start, skipping files that already exist. The result:

  • The first start fills the empty host directories with the image's defaults (the statusline, the claude-hud config, ~/.codex/config.toml).
  • Your own files in agents/claude (settings.json, CLAUDE.md, commands/, ...) are never overwritten. Put your configuration there on the host and it is used by every container that mounts the directory.
  • If a newer image has other defaults, existing files are not updated; delete the file to get the new default.

To have your own Claude Code or Codex setup in the image, add a [[tools]] block with run_as = "user" that writes it (for example a curl or git clone into $HOME/.claude), after claude-code-codex.

GPUs

container.gpus = "0", "0,1" or "all" passes NVIDIA GPUs into the container, with --ulimit nofile=65535. Set shm_size (e.g. "32g") for data loaders. up checks that nvidia-ctk exists and that every device is in the CDI list, and prints the commands below if not.

The GPUs are fixed when the container is created. To change them, edit gpus and run agentcabin up: it asks, removes the old container and creates a new one (no rebuild). Only the mounted directories survive; see below.

What the host needs (CDI)

agentcabin gives the GPUs to podman as CDI (Container Device Interface) devices, nvidia.com/gpu=N. A CDI spec file, normally /etc/cdi/nvidia.yaml, describes the devices; the NVIDIA Container Toolkit generates it. podman reads it and puts the /dev/nvidia* device nodes and the driver's libraries (libcuda, nvidia-smi, ...) into the container. On the host you need:

What Why Check
The NVIDIA driver (the kernel module and its user-space libraries) The container reuses the host's driver, it has none of its own nvidia-smi lists the GPUs
nvidia-container-toolkit Provides nvidia-ctk, which writes the CDI spec nvidia-ctk --version
podman >= 4.1 (agentcabin itself needs >= 4.4) CDI support podman --version
A CDI spec Names the devices (nvidia.com/gpu=0, =1, ..., =all) nvidia-ctk cdi list

Not needed: the CUDA toolkit on the host (CUDA libraries for your programs come from the container, e.g. pip or conda packages such as PyTorch), Docker, the legacy nvidia-container-runtime hook, or root to run the container. Root is only needed once, to install the packages and write the spec.

  1. The driver. Install the proprietary driver from your distribution (for example sudo ubuntu-drivers install on Ubuntu) or NVIDIA's installer, and reboot. nvidia-smi must work.

  2. The toolkit. On Debian / Ubuntu:

    curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \
      | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
    curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \
      | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \
      | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
    sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
    

    On Fedora / RHEL:

    curl -s -L https://nvidia.github.io/libnvidia-container/stable/rpm/nvidia-container-toolkit.repo \
      | sudo tee /etc/yum.repos.d/nvidia-container-toolkit.repo
    sudo dnf install -y nvidia-container-toolkit
    

    (NVIDIA's installation guide for the Container Toolkit has the current instructions for other systems.)

  3. The CDI spec. Generate it and check it:

    sudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.yaml
    nvidia-ctk cdi list            # nvidia.com/gpu=0 ... nvidia.com/gpu=all
    ls -l /etc/cdi/nvidia.yaml     # must be readable by the user who runs agentcabin
    

    Generate it again after every driver upgrade and whenever GPUs are added or removed: the spec names the exact library files of the installed driver.

  4. Try it with podman alone, before agentcabin:

    podman run --rm --device nvidia.com/gpu=all docker.io/library/ubuntu:24.04 nvidia-smi -L
    

    If that lists your GPUs, container.gpus = "all" works. Then set gpus in agentbox.toml, run agentcabin up, and check inside with agentcabin shell and nvidia-smi.

Symptom Likely cause and fix
nvidia-ctk is not installed Install nvidia-container-toolkit (step 2).
CDI device(s) not found: nvidia.com/gpu=N No spec yet, or an index that does not exist: run step 3 and compare with nvidia-ctk cdi list.
unresolvable CDI devices from podman podman does not find the spec (not in /etc/cdi or /var/run/cdi), or it is unreadable for your user.
nvidia-smi fails in the container after a driver upgrade (e.g. "Failed to initialize NVML", library version mismatch) The spec or the running kernel module is from the old driver: reboot if needed, regenerate the spec (step 3), then agentcabin up to recreate the container.
/dev/nvidia-uvm is missing on the host The module is not loaded until something uses CUDA: sudo nvidia-modprobe -u -c=0, then regenerate the spec.

Fast NICs: host network and RDMA

By default the container has its own network (network.mode = "pasta", a user-space stack of a few Gbit/s) and only the SSH, VNC and extra ports are published. To use a 100G NIC at full speed, for iperf3 or RDMA tests, while managing the container over a slower NIC:

[network]
mode = "host"              # the container shares the host's network: every NIC, at full speed

[ports]
bind_address = "eno1"      # the management NIC: an IP, or an interface name
ssh = 2222                 # SSH and VNC listen on these host ports, on eno1's address only
vnc = 5901

[container]
rdma = "all"               # or "mlx5_0,mlx5_1"; see `ibv_devices` on the host
  • bind_address can be an interface name; up looks up its IPv4 address (and prints it), so it works when the IP changes. restart does not look it up again, up does. In host mode nothing is listening on the other NICs. 0.0.0.0 listens on all of them and warns. [[extra_ports]] and container.mac have no effect in host mode.
  • Ports are the host's own, so ports.ssh must not be one the host already uses (not 22 if the host runs sshd); up checks, and 0 picks a free one.
  • The VNC display :1 must be free on the host. Host networking also shares abstract unix sockets, so an X or VNC server of the host on :1 would clash; up checks for it.
  • container.rdma (InfiniBand or RoCE, ConnectX-5/6/7) passes the /dev/infiniband/uverbs* nodes of the devices (and umad* when you may use them, and rdma_cm) and adds IPC_LOCK and an unlimited memlock. up fails with instructions if your hard memlock limit is not unlimited (/etc/security/limits.d, then log in again). Verbs programs (NCCL, ib_write_bw) work in either network mode; rdma_cm (ib_write_bw -R, IP-based MPI) needs mode = "host". tools (ibv_devinfo, ibstat, ib_write_bw) are not in the default packages, because most hosts have no RDMA NIC: add rdma-core, ibverbs-utils, rdmacm-utils, perftest and infiniband-diags (and iperf3, ethtool for TCP/IP tests) to packages. The comment "Using an RDMA NIC" in the generated config lists every step. The link layer (InfiniBand or Ethernet/RoCE) is a property of the NIC and needs no setting here.
  • Check it inside the container: ibv_devinfo, ibstat, ib_write_bw (server on one machine, ib_write_bw <server> on the other), iperf3 -c <server> -P 8.

Mounts, Claude Code and Codex state

The default config mounts ./data at ~/Projects and ./agents/{claude,claude-personal,claude-team,codex} at ~/.claude, ~/.claude-personal, ~/.claude-team and ~/.codex, so logins, sessions and settings outlive the container. create = true makes up create a missing host directory (mode 0700). On first start the container copies the image's default config into the empty mounts; files that exist are never overwritten. CLAUDE_CONFIG_DIR is set in ~/.bashrc so .claude.json lives inside the mounted directory too.

Everything else in the container (apt packages installed by hand, ~/.config, ...) is lost when up recreates it; agentcabin cp or agentcabin commit save what you need first.

Several containers on one host

Give each its own config file and run agentcabin -c FILE .... In each: a different container.name, ports.ssh / ports.vnc (or 0 for automatic ports) and host directories in [[mounts]]. Containers carry the path of their config file as a label, so a config can only change or remove the container it created (agentcabin ps shows the mapping).

agentcabin init cpu.toml && agentcabin init gpu.toml     # edit name, ports, mounts; gpus = "0" in gpu.toml
agentcabin -c cpu.toml up && agentcabin -c gpu.toml up

Migrating from the compose version

compose.yml, scripts/compose, scripts/agent-shell and scripts/cscp were replaced by agentcabin. scripts/compose up is agentcabin up, scripts/agent-shell --cli is agentcabin shell and scripts/cscp is agentcabin cp. .env settings map to the config file: CONTAINER_NAME -> container.name, SSH_PORT / VNC_PORT -> ports, GPU -> container.gpus, DATA_DIR and AGENTS_DIR -> [[mounts]]. Access over SSH now uses the password (container.password) instead of ssh/authorized_keys; add a key from the host with ssh-copy-id -p 2222 agent@localhost.

Development

uv sync
uv run pytest                  # unit tests; podman is mocked
uvx ruff check src tests
uvx --from shellcheck-py shellcheck src/agentbox/assets/scripts/*.sh \
  src/agentbox/assets/rootfs/usr/local/bin/entrypoint.sh
uv run agentcabin --help

Dockerfile RUN lines must stay POSIX /bin/sh (podman builds OCI images, which ignore SHELL); anything that needs bash goes into a script run with bash script.sh.

Metadata

Release files for agentcabin 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agentcabin 0.2.0
File Size Uploaded Provenance Actions
agentcabin-0.2.0.tar.gz 94.5 kB Without provenance Details for agentcabin-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agentcabin 0.2.0
File Interpreter ABI Platform Actions
agentcabin-0.2.0-py3-none-any.whl Python 3 none any Details for agentcabin-0.2.0-py3-none-any.whl

Total release size: 154.0 kB

Release files / agentcabin-0.2.0.tar.gz

Download URL agentcabin-0.2.0.tar.gz
Size 94.5 kB
Tags Source
SHA-256 checksum
How to use checksums
d3b693e2c7404e6c8154a5705fe15e2ab103f09b9737893a9f8d63008e2bf9b8
BLAKE2b-256 checksum
How to use checksums
dd608152dad92580055521554b0d8d61de95634203b680b9c803fa3c5fabc402
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / agentcabin-0.2.0-py3-none-any.whl

Download URL agentcabin-0.2.0-py3-none-any.whl
Size 59.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d335117fa36f051b441d6a71f68ee8eb24c0da98e39e094b9adf654fe7e51fe4
BLAKE2b-256 checksum
How to use checksums
6ae3a3f5a922e0422a2ecc045cec4e5004ba062ab9bbf134c24a18e65c36cdb5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for agentcabin 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page