Metadata-Version: 2.5
Name: agentcabin
Version: 0.2.0
Summary: Build and run SSH + VNC desktop containers for AI coding agents with rootless podman
Requires-Python: >=3.11
Requires-Dist: typer>=0.12
Description-Content-Type: text/markdown

# agentcabin

[中文](README.zh-CN.md)

`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.

```bash
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.

```toml
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:

```toml
[[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:

   ```bash
   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:

   ```bash
   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:

   ```bash
   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:

   ```bash
   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:

```toml
[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).

```bash
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

```bash
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`.
