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~/.bashrcaliases.
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
roottools run first, then theusertools, 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_USERand$HOME;usertools run as the container user with~/.local/binonPATH. - 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:
- The base system, SSH, VNC, the XFCE desktop and Firefox (fixed, not configurable).
- The container user, with the host's UID so that mounted directories are writable.
[[apt_repos]]are added, thenpackagesare installed withapt.- The
[[tools]]withrun_as = "root", in the order written in the file. - The
[[tools]]withrun_as = "user", in the order written in the file. - 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 runagentcabin 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-cacherebuilds 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 whenagentcabin uprecreates it. Keep them by mounting a host directory ([[mounts]]), by pushing them to your config repository, or by copying them out withagentcabin 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 examplenvim --headless "+Lazy! sync" +qaif 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.
-
The driver. Install the proprietary driver from your distribution (for example
sudo ubuntu-drivers installon Ubuntu) or NVIDIA's installer, and reboot.nvidia-smimust work. -
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.)
-
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.
-
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 setgpusinagentbox.toml, runagentcabin up, and check inside withagentcabin shellandnvidia-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_addresscan be an interface name;uplooks up its IPv4 address (and prints it), so it works when the IP changes.restartdoes not look it up again,updoes. In host mode nothing is listening on the other NICs.0.0.0.0listens on all of them and warns.[[extra_ports]]andcontainer.machave no effect in host mode.- Ports are the host's own, so
ports.sshmust not be one the host already uses (not 22 if the host runs sshd);upchecks, and0picks a free one. - The VNC display
:1must be free on the host. Host networking also shares abstract unix sockets, so an X or VNC server of the host on:1would clash;upchecks for it. container.rdma(InfiniBand or RoCE, ConnectX-5/6/7) passes the/dev/infiniband/uverbs*nodes of the devices (andumad*when you may use them, andrdma_cm) and addsIPC_LOCKand an unlimitedmemlock.upfails 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) needsmode = "host". tools (ibv_devinfo,ibstat,ib_write_bw) are not in the defaultpackages, because most hosts have no RDMA NIC: addrdma-core,ibverbs-utils,rdmacm-utils,perftestandinfiniband-diags(andiperf3,ethtoolfor TCP/IP tests) topackages. 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.