agentcabin 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. agentcabin-0.2.0/.github/actions/setup-podman/action.yml +31 -0
  2. agentcabin-0.2.0/.github/workflows/ci.yml +81 -0
  3. agentcabin-0.2.0/.gitignore +20 -0
  4. agentcabin-0.2.0/PKG-INFO +380 -0
  5. agentcabin-0.2.0/README.md +372 -0
  6. agentcabin-0.2.0/README.zh-CN.md +345 -0
  7. agentcabin-0.2.0/pyproject.toml +27 -0
  8. agentcabin-0.2.0/src/agentbox/__init__.py +8 -0
  9. agentcabin-0.2.0/src/agentbox/assets/Dockerfile +76 -0
  10. agentcabin-0.2.0/src/agentbox/assets/base.list +32 -0
  11. agentcabin-0.2.0/src/agentbox/assets/rootfs/etc/ssh/sshd_config.d/10-agentbox.conf +9 -0
  12. agentcabin-0.2.0/src/agentbox/assets/rootfs/usr/local/bin/entrypoint.sh +232 -0
  13. agentcabin-0.2.0/src/agentbox/assets/scripts/add_apt_repos.sh +95 -0
  14. agentcabin-0.2.0/src/agentbox/assets/scripts/apt_update.sh +27 -0
  15. agentcabin-0.2.0/src/agentbox/assets/scripts/create_user.sh +59 -0
  16. agentcabin-0.2.0/src/agentbox/assets/scripts/install_base.sh +36 -0
  17. agentcabin-0.2.0/src/agentbox/assets/scripts/install_firefox.sh +28 -0
  18. agentcabin-0.2.0/src/agentbox/assets/scripts/install_packages.sh +15 -0
  19. agentcabin-0.2.0/src/agentbox/assets/scripts/install_pkg_list.sh +41 -0
  20. agentcabin-0.2.0/src/agentbox/assets/scripts/install_tools.sh +39 -0
  21. agentcabin-0.2.0/src/agentbox/assets/scripts/save_defaults.sh +15 -0
  22. agentcabin-0.2.0/src/agentbox/assets/scripts/set_apt_mirror.sh +30 -0
  23. agentcabin-0.2.0/src/agentbox/assets/vnc/xstartup +16 -0
  24. agentcabin-0.2.0/src/agentbox/cli.py +543 -0
  25. agentcabin-0.2.0/src/agentbox/config.py +681 -0
  26. agentcabin-0.2.0/src/agentbox/errors.py +2 -0
  27. agentcabin-0.2.0/src/agentbox/podman.py +721 -0
  28. agentcabin-0.2.0/src/agentbox/templates/agentbox.toml +449 -0
  29. agentcabin-0.2.0/tests/conftest.py +7 -0
  30. agentcabin-0.2.0/tests/smoke/smoke.sh +257 -0
  31. agentcabin-0.2.0/tests/test_agentbox.py +523 -0
  32. agentcabin-0.2.0/tests/test_apt_repos.py +151 -0
  33. agentcabin-0.2.0/tests/test_auto_ports.py +117 -0
  34. agentcabin-0.2.0/tests/test_cli_commit.py +70 -0
  35. agentcabin-0.2.0/tests/test_cli_up.py +73 -0
  36. agentcabin-0.2.0/tests/test_limits.py +105 -0
  37. agentcabin-0.2.0/uv.lock +332 -0
@@ -0,0 +1,31 @@
1
+ name: Set up rootless podman and agentcabin
2
+ description: Install pasta and sshpass, configure rootless podman for CI, install agentcabin with uv
3
+
4
+ runs:
5
+ using: composite
6
+ steps:
7
+ - name: Install pasta (passt) and sshpass
8
+ shell: bash
9
+ run: |
10
+ sudo apt-get update
11
+ sudo apt-get install -y --no-install-recommends passt sshpass
12
+
13
+ - name: Configure rootless podman
14
+ shell: bash
15
+ run: |
16
+ # Ubuntu 24.04+ restricts unprivileged user namespaces with AppArmor
17
+ sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
18
+ # CI jobs have no systemd user session: use cgroupfs and file-based events
19
+ mkdir -p ~/.config/containers
20
+ printf '[engine]\ncgroup_manager = "cgroupfs"\nevents_logger = "file"\n' > ~/.config/containers/containers.conf
21
+ podman system migrate
22
+ podman info --format 'podman {{.Version.Version}}, rootless={{.Host.Security.Rootless}}, cgroup={{.Host.CgroupManager}}'
23
+ pasta --version | head -1
24
+
25
+ - uses: astral-sh/setup-uv@v6
26
+
27
+ - name: Install agentcabin
28
+ shell: bash
29
+ run: |
30
+ uv tool install .
31
+ echo "$(uv tool dir --bin)" >> "$GITHUB_PATH"
@@ -0,0 +1,81 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main, dev]
6
+ pull_request:
7
+ branches: [main, dev]
8
+ workflow_dispatch:
9
+
10
+ concurrency:
11
+ group: ${{ github.workflow }}-${{ github.ref }}
12
+ cancel-in-progress: true
13
+
14
+ permissions:
15
+ contents: read
16
+
17
+ jobs:
18
+ # ---------------------------------------------------------------------------
19
+ # Python code and shell scripts: lint + unit tests (podman is mocked)
20
+ # ---------------------------------------------------------------------------
21
+ lint:
22
+ name: Lint (ruff, shellcheck)
23
+ runs-on: ubuntu-26.04
24
+ steps:
25
+ - uses: actions/checkout@v4
26
+ - uses: astral-sh/setup-uv@v6
27
+ - name: ruff
28
+ run: uvx ruff check src tests
29
+ - name: shellcheck
30
+ run: |
31
+ uvx --from shellcheck-py shellcheck \
32
+ src/agentbox/assets/scripts/*.sh \
33
+ src/agentbox/assets/rootfs/usr/local/bin/entrypoint.sh \
34
+ tests/smoke/*.sh
35
+
36
+ unit-tests:
37
+ name: Unit tests (Python ${{ matrix.python }})
38
+ runs-on: ubuntu-26.04
39
+ strategy:
40
+ fail-fast: false
41
+ matrix:
42
+ python: ["3.11", "3.12", "3.13", "3.14"]
43
+ steps:
44
+ - uses: actions/checkout@v4
45
+ - uses: astral-sh/setup-uv@v6
46
+ with:
47
+ python-version: ${{ matrix.python }}
48
+ - run: uv sync --locked
49
+ - run: uv run pytest -v
50
+ - name: CLI starts, and the default config can be generated
51
+ run: |
52
+ uv run agentcabin --version
53
+ uv run agentcabin list
54
+ cd "$(mktemp -d)" && uv run --project "$GITHUB_WORKSPACE" agentcabin init && uv run --project "$GITHUB_WORKSPACE" agentcabin config
55
+
56
+ # ---------------------------------------------------------------------------
57
+ # The container: build the image from the default config and start it with real rootless
58
+ # podman, then check that SSH and VNC are up and that the software is installed
59
+ # (tests/smoke/smoke.sh)
60
+ # ---------------------------------------------------------------------------
61
+ container:
62
+ name: Container (${{ matrix.os }})
63
+ needs: [lint, unit-tests]
64
+ runs-on: ubuntu-26.04
65
+ timeout-minutes: 90
66
+ strategy:
67
+ fail-fast: false
68
+ matrix:
69
+ os: ["ubuntu:24.04", "ubuntu:26.04"]
70
+ steps:
71
+ - name: Free disk space (the image is large)
72
+ run: |
73
+ sudo rm -rf /usr/share/dotnet /usr/local/lib/android /opt/ghc /opt/hostedtoolcache/CodeQL
74
+ df -h /
75
+ - uses: actions/checkout@v4
76
+ - uses: ./.github/actions/setup-podman
77
+ - name: Smoke test
78
+ # GitHub's Azure Ubuntu mirror: fast from the runners, and tests build.apt_mirror
79
+ env:
80
+ SMOKE_APT_MIRROR: http://azure.archive.ubuntu.com/ubuntu
81
+ run: tests/smoke/smoke.sh --os "${{ matrix.os }}"
@@ -0,0 +1,20 @@
1
+ # agentbox.toml holds the container's passwords; agentbox init writes it with mode 0600.
2
+ /agentbox.toml
3
+ # Several instances: agentbox-*.toml
4
+ /agentbox-*.toml
5
+
6
+ # Workspace and Claude Code / Codex login tokens, sessions and settings (the host side of the
7
+ # [[mounts]] in the default config). Never commit these.
8
+ data/
9
+ agents/
10
+
11
+ # Python
12
+ .venv/
13
+ __pycache__/
14
+ dist/
15
+ *.egg-info/
16
+ .pytest_cache/
17
+ .ruff_cache/
18
+
19
+ # macOS Finder metadata, created in any directory it browses.
20
+ .DS_Store
@@ -0,0 +1,380 @@
1
+ Metadata-Version: 2.5
2
+ Name: agentcabin
3
+ Version: 0.2.0
4
+ Summary: Build and run SSH + VNC desktop containers for AI coding agents with rootless podman
5
+ Requires-Python: >=3.11
6
+ Requires-Dist: typer>=0.12
7
+ Description-Content-Type: text/markdown
8
+
9
+ # agentcabin
10
+
11
+ [中文](README.zh-CN.md)
12
+
13
+ `agentcabin` builds and runs a container for AI coding agents with **rootless podman**: an Ubuntu
14
+ desktop reachable over **SSH** and **VNC**, with **Firefox**, **Claude Code**, **Codex**, Neovim, tmux,
15
+ herdr and the usual command-line tools (KiCad is one comment away). Everything is described by one TOML file, in the same
16
+ layout as the one `casperbox-dev init` writes.
17
+
18
+ ```bash
19
+ uv tool install . # in a clone of this repository; `uv tool upgrade agentcabin` later
20
+ agentcabin init # writes ./agentbox.toml
21
+ $EDITOR agentbox.toml # optional: packages, tools, ports, GPUs, mounts
22
+ agentcabin up # builds the image the first time (long), then starts the container
23
+ agentcabin shell # a shell in the container
24
+ ssh -p 2222 agent@localhost # or SSH (password: agent); VNC: localhost:5901 (password: agentbox)
25
+ ```
26
+
27
+ Requirements on the host: rootless `podman` (>= 4.4), `pasta` (the `passt` package) and `uv` (to install
28
+ the tool). For GPUs also `nvidia-container-toolkit`.
29
+
30
+ ## Commands
31
+
32
+ All commands except `list`, `init` and `ps` read `./agentbox.toml`; pass `-c FILE` to use another one
33
+ (also before the command: `agentcabin -c FILE up`).
34
+
35
+ | Command | What it does |
36
+ | --- | --- |
37
+ | `agentcabin list` | List the tested base OS images (any apt-based image works). |
38
+ | `agentcabin init [FILE] [--os IMAGE] [-f]` | Write the default config (mode 0600, it holds passwords). |
39
+ | `agentcabin build [--no-cache]` | Build the image. |
40
+ | `agentcabin up [-y]` | Build the image if it is missing or outdated, then create and start the container. Asks before replacing an existing one. |
41
+ | `agentcabin down` | Stop and remove the container. |
42
+ | `agentcabin restart` | Restart the container, keeping its data. Config changes need `up`. |
43
+ | `agentcabin shell` | A login shell in the container as the container user. |
44
+ | `agentcabin cp SRC DEST` | Copy between host and container; `:PATH` is in the container (`agentcabin cp a.txt :~/Projects/`). |
45
+ | `agentcabin status` | Image state, limits, GPUs, ports and mounts of the container. |
46
+ | `agentcabin logs [-f]` | Container logs. |
47
+ | `agentcabin commit [IMAGE] [-o FILE]` | Save the container as an image, optionally to a tar file. |
48
+ | `agentcabin config` | The resolved config and the exact `podman build` / `podman run` commands. |
49
+ | `agentcabin ps` | All containers created by agentcabin, with their config files. |
50
+
51
+ The image is rebuilt by `up` whenever anything it is built from changes: the base OS, `packages`,
52
+ `[[apt_repos]]`, `[[tools]]`, `[build]`, the user, or agentcabin's own build files.
53
+
54
+ ## What is in the container
55
+
56
+ - **Always** (not configurable): `openssh-server`, TigerVNC, the XFCE desktop, Firefox (from Mozilla's
57
+ apt repository, not the snap), sudo, curl, rsync. **sshd and the VNC server start with the
58
+ container** (`:1`, port 5901) and are restarted if they stop.
59
+ - **From the default config**, all of it removable or editable: the apt packages (git, gh, tmux,
60
+ ripgrep, fzf, bat, eza, build tools, network tools, fonts, ...) and these `[[tools]]`:
61
+ Node.js, uv, Neovim, lazygit, Starship, Maple Mono, Claude Code and Codex (npm, per user),
62
+ the claude-hud plugin, the Codex config, herdr, the dotfiles (Neovim, tmux, Starship, dircolors) and
63
+ the `~/.bashrc` aliases.
64
+
65
+ PID 1 is `entrypoint.sh` (no systemd). It sets the passwords, copies the image's default Claude
66
+ Code / Codex config into `~/.claude` and `~/.codex`, and starts and watches sshd and the VNC server.
67
+
68
+ ## The config file
69
+
70
+ `agentcabin init` writes a commented file; this is its layout, with the settings you are likely to change
71
+ first and the image contents last. The parts that `casperbox-dev` also has behave the same; the additions are
72
+ marked.
73
+
74
+ ```toml
75
+ os = "ubuntu:26.04" # base image, name:tag (apt-based)
76
+
77
+ [container] # what you change most comes first ...
78
+ name = "agentbox-ubuntu-26.04"; user = "agent"; password = "agent"; vnc_password = "agentbox"
79
+ mac = ""; shm_size = "2g"; tz = "UTC"
80
+ gpus = "" # ADDED: "0", "0,1" or "all"
81
+ rdma = "" # ADDED: "all" or "mlx5_0,mlx5_1"
82
+ memory = ""; cpus = 0; cpuset = ""
83
+
84
+ [network] mode = "pasta" # ADDED: or "host"
85
+ [ports] bind_address = "127.0.0.1"; ssh = 2222; vnc = 5901 # 0 = pick a free port; bind_address may be a NIC name
86
+ [vnc] geometry = "1920x1080"
87
+
88
+ [[mounts]] # host directories; ADDED: create = true
89
+ host = "./data"; container = "~/Projects"; mode = "rw"; create = true
90
+
91
+ [[extra_ports]]
92
+ host = 8888; container = 8888; protocol = "tcp"
93
+
94
+ [build] # ... what goes into the image comes last
95
+ apt_mirror = ""
96
+ packages = ["git", "tmux", ...] # extra apt packages (casperbox-dev has this key at the top level)
97
+
98
+ [[apt_repos]] # third-party apt repositories
99
+ name = "github-cli"; key = "https://..."; url = "https://..."; suite = "stable"; components = ["main"]
100
+
101
+ [[tools]] # ADDED: tools that are not apt packages
102
+ name = "node"; version = "24.21.0"; run_as = "root" # or "user"
103
+ script = '''...'''
104
+ ```
105
+
106
+ `packages` is a top-level key in `casperbox-dev`'s layout, and TOML requires top-level keys before the
107
+ first table, so it could not be moved to the end there. agentcabin therefore also accepts `packages` in
108
+ `[build]`, where `agentcabin init` puts it; the top-level form still works (set one of the two, not both).
109
+
110
+ Relative host paths are relative to the config file. Defaults differ from `casperbox-dev` in three
111
+ values only: the user is `agent`, the ports are 2222/5901 and `bind_address` is `127.0.0.1` (a
112
+ password SSH server and an unencrypted VNC server should not listen on the network by default).
113
+
114
+ ### `[[tools]]`
115
+
116
+ Each block installs one tool with a bash script during the build:
117
+
118
+ - `name` (required, unique), `script` (required), `version` (optional, passed as `$VERSION`),
119
+ `run_as` = `"root"` (default) or `"user"`.
120
+ - All `root` tools run first, then the `user` tools, each group in the order written. A tool can
121
+ rely on the ones above it (Claude Code needs Node.js). A failing script stops the build.
122
+ - A script sees `$VERSION`, `$DEB_ARCH` (`amd64` / `arm64`), `$CONTAINER_USER` and `$HOME`; `user`
123
+ tools run as the container user with `~/.local/bin` on `PATH`.
124
+ - Write scripts in `'''...'''` so backslashes and `$` stay as written.
125
+ - 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
126
+ not apply.
127
+
128
+ ### How the software gets installed and configured
129
+
130
+ Everything below happens while the **image is built** (`agentcabin build`, or `agentcabin up` when the image
131
+ is missing or out of date), not when the container starts. The build runs these steps in order:
132
+
133
+ 1. The base system, SSH, VNC, the XFCE desktop and Firefox (fixed, not configurable).
134
+ 2. The container user, with the host's UID so that mounted directories are writable.
135
+ 3. `[[apt_repos]]` are added, then `packages` are installed with `apt`.
136
+ 4. The `[[tools]]` with `run_as = "root"`, in the order written in the file.
137
+ 5. The `[[tools]]` with `run_as = "user"`, in the order written in the file.
138
+ 6. A copy of the Claude Code and Codex config the tools created is kept as the image's defaults.
139
+
140
+ A *program* and its *configuration* are separate tools. Take Neovim:
141
+
142
+ | Tool | `run_as` | What it does |
143
+ | --- | --- | --- |
144
+ | `neovim` | root | Downloads the release tarball to `/opt/nvim` and links `nvim` and `vi` into `/usr/local/bin`. This installs the program only. |
145
+ | `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. |
146
+ | `shell-config` | user | Appends the `vim=nvim` alias, `PATH` and the Starship prompt to `~/.bashrc`. |
147
+
148
+ The `dotfiles` script is in your `agentbox.toml` (the original is
149
+ `src/agentbox/templates/agentbox.toml`); open it to change the repository URL:
150
+
151
+ ```toml
152
+ [[tools]]
153
+ name = "dotfiles"
154
+ run_as = "user"
155
+ script = '''
156
+ install -d "$HOME/.config"
157
+ if git clone --depth 1 https://github.com/wlsky90/wneovim-config.git "$HOME/.config/nvim"; then
158
+ echo "neovim config installed"
159
+ else
160
+ echo "WARNING: could not clone the neovim config; skipping it" >&2 # not fatal
161
+ rm -rf "$HOME/.config/nvim"
162
+ fi
163
+ ...
164
+ '''
165
+ ```
166
+
167
+ All default tools:
168
+
169
+ | Tool | `run_as` | What it does |
170
+ | --- | --- | --- |
171
+ | `node`, `uv`, `neovim`, `lazygit`, `starship` | root | Programs installed under `/usr/local` or `/opt`. |
172
+ | `maple-mono` | root | The Maple Mono Nerd Font for the desktop. |
173
+ | `command-names` | root | Links `fd` and `bat` (Debian calls them `fdfind` and `batcat`). |
174
+ | `ghostty-terminfo` | root | Makes `xterm-ghostty` known when the OS's `ncurses-term` allows it; skipped otherwise. |
175
+ | `claude-code-codex` | user | Claude Code and Codex with npm, into `~/.local` (so `npm update -g` needs no sudo). |
176
+ | `claude-hud` | user | The claude-hud plugin and its config, written into `~/.claude`. |
177
+ | `codex-config` | user | Downloads `~/.codex/config.toml`. |
178
+ | `herdr` | user | The terminal agent multiplexer, in `~/.local/bin`. |
179
+ | `dotfiles` | user | Neovim, tmux, Starship and dircolors configuration (see above). |
180
+ | `shell-config` | user | The `~/.bashrc` additions: aliases, `PATH`, `CLAUDE_CONFIG_DIR`, the prompt. |
181
+
182
+ #### What this means in practice
183
+
184
+ - **The configuration is part of the image.** Starting a container downloads nothing, so it starts fast
185
+ and works offline. The configuration is a snapshot of the repository at build time.
186
+ - **Updating the configuration.** In a running container the clone is a normal git repository:
187
+ `cd ~/.config/nvim && git pull`. To change the image instead, edit the script (or run
188
+ `agentcabin build --no-cache`): when a script has not changed, podman reuses the cached result of the
189
+ last build and does not clone again, and `--no-cache` rebuilds the whole image, which is slow.
190
+ - **Recreating the container resets `~/.config`.** It is not mounted by default, so changes made in
191
+ the container are lost when `agentcabin up` recreates it. Keep them by mounting a host directory
192
+ (`[[mounts]]`), by pushing them to your config repository, or by copying them out with `agentcabin cp`.
193
+ - **A failing step stops the build**, except the Neovim clone above, which only warns. Clone URLs
194
+ must be reachable from where the image is built; a private repository needs credentials the build
195
+ does not have.
196
+ - **Neovim plugins are not installed by the build.** The script only downloads the configuration;
197
+ the plugin manager of your config installs the plugins the first time you start `nvim` (that
198
+ depends on your repository, which agentcabin does not look at). To have them in the image, add a
199
+ line to the script, for example `nvim --headless "+Lazy! sync" +qa` if you use lazy.nvim.
200
+
201
+ #### Claude Code and Codex configuration
202
+
203
+ `claude-hud` and `codex-config` write into `~/.claude` and `~/.codex` during the build. The default
204
+ config mounts host directories (`./agents/claude`, `./agents/codex`, ...) over those paths, and a
205
+ mount hides what the image has there. So the build keeps a copy of both directories in
206
+ `/usr/local/share/agentbox/defaults`, and the container's entrypoint copies it into the mounted
207
+ directories at every start, **skipping files that already exist**. The result:
208
+
209
+ - The first start fills the empty host directories with the image's defaults (the statusline, the
210
+ claude-hud config, `~/.codex/config.toml`).
211
+ - Your own files in `agents/claude` (`settings.json`, `CLAUDE.md`, `commands/`, ...) are never
212
+ overwritten. Put your configuration there on the host and it is used by every container that
213
+ mounts the directory.
214
+ - If a newer image has other defaults, existing files are not updated; delete the file to get the
215
+ new default.
216
+
217
+ To have your own Claude Code or Codex setup in the image, add a `[[tools]]` block with
218
+ `run_as = "user"` that writes it (for example a `curl` or `git clone` into `$HOME/.claude`), after
219
+ `claude-code-codex`.
220
+
221
+ ### GPUs
222
+
223
+ `container.gpus = "0"`, `"0,1"` or `"all"` passes NVIDIA GPUs into the container, with `--ulimit nofile=65535`.
224
+ Set `shm_size` (e.g. `"32g"`) for data loaders. `up` checks that `nvidia-ctk` exists and that every device
225
+ is in the CDI list, and prints the commands below if not.
226
+
227
+ The GPUs are fixed when the container is **created**. To change them, edit `gpus` and run
228
+ `agentcabin up`: it asks, removes the old container and creates a new one (no rebuild). Only the
229
+ mounted directories survive; see below.
230
+
231
+ #### What the host needs (CDI)
232
+
233
+ agentcabin gives the GPUs to podman as **CDI** (Container Device Interface) devices, `nvidia.com/gpu=N`.
234
+ A CDI *spec* file, normally `/etc/cdi/nvidia.yaml`, describes the devices; the NVIDIA Container
235
+ Toolkit generates it. podman reads it and puts the `/dev/nvidia*` device nodes and the driver's
236
+ libraries (`libcuda`, `nvidia-smi`, ...) into the container. On the host you need:
237
+
238
+ | What | Why | Check |
239
+ | --- | --- | --- |
240
+ | 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 |
241
+ | **`nvidia-container-toolkit`** | Provides `nvidia-ctk`, which writes the CDI spec | `nvidia-ctk --version` |
242
+ | **podman >= 4.1** (agentcabin itself needs >= 4.4) | CDI support | `podman --version` |
243
+ | A **CDI spec** | Names the devices (`nvidia.com/gpu=0`, `=1`, ..., `=all`) | `nvidia-ctk cdi list` |
244
+
245
+ Not needed: the CUDA toolkit on the host (CUDA libraries for your programs come from the container, e.g.
246
+ pip or conda packages such as PyTorch), Docker, the legacy `nvidia-container-runtime` hook, or root to
247
+ run the container. Root is only needed once, to install the packages and write the spec.
248
+
249
+ 1. **The driver.** Install the proprietary driver from your distribution (for example
250
+ `sudo ubuntu-drivers install` on Ubuntu) or NVIDIA's installer, and reboot. `nvidia-smi` must work.
251
+ 2. **The toolkit.** On Debian / Ubuntu:
252
+
253
+ ```bash
254
+ curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \
255
+ | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
256
+ curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \
257
+ | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \
258
+ | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
259
+ sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
260
+ ```
261
+
262
+ On Fedora / RHEL:
263
+
264
+ ```bash
265
+ curl -s -L https://nvidia.github.io/libnvidia-container/stable/rpm/nvidia-container-toolkit.repo \
266
+ | sudo tee /etc/yum.repos.d/nvidia-container-toolkit.repo
267
+ sudo dnf install -y nvidia-container-toolkit
268
+ ```
269
+
270
+ (NVIDIA's installation guide for the Container Toolkit has the current instructions for other systems.)
271
+ 3. **The CDI spec.** Generate it and check it:
272
+
273
+ ```bash
274
+ sudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.yaml
275
+ nvidia-ctk cdi list # nvidia.com/gpu=0 ... nvidia.com/gpu=all
276
+ ls -l /etc/cdi/nvidia.yaml # must be readable by the user who runs agentcabin
277
+ ```
278
+
279
+ **Generate it again after every driver upgrade** and whenever GPUs are added or removed: the spec
280
+ names the exact library files of the installed driver.
281
+ 4. **Try it with podman alone**, before agentcabin:
282
+
283
+ ```bash
284
+ podman run --rm --device nvidia.com/gpu=all docker.io/library/ubuntu:24.04 nvidia-smi -L
285
+ ```
286
+
287
+ If that lists your GPUs, `container.gpus = "all"` works. Then set `gpus` in `agentbox.toml`,
288
+ run `agentcabin up`, and check inside with `agentcabin shell` and `nvidia-smi`.
289
+
290
+ | Symptom | Likely cause and fix |
291
+ | --- | --- |
292
+ | `nvidia-ctk is not installed` | Install `nvidia-container-toolkit` (step 2). |
293
+ | `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`. |
294
+ | `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. |
295
+ | `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. |
296
+ | `/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. |
297
+
298
+ ### Fast NICs: host network and RDMA
299
+
300
+ By default the container has its own network (`network.mode = "pasta"`, a user-space stack of a few
301
+ Gbit/s) and only the SSH, VNC and extra ports are published. To use a 100G NIC at full speed, for
302
+ `iperf3` or RDMA tests, while managing the container over a slower NIC:
303
+
304
+ ```toml
305
+ [network]
306
+ mode = "host" # the container shares the host's network: every NIC, at full speed
307
+
308
+ [ports]
309
+ bind_address = "eno1" # the management NIC: an IP, or an interface name
310
+ ssh = 2222 # SSH and VNC listen on these host ports, on eno1's address only
311
+ vnc = 5901
312
+
313
+ [container]
314
+ rdma = "all" # or "mlx5_0,mlx5_1"; see `ibv_devices` on the host
315
+ ```
316
+
317
+ - **`bind_address`** can be an interface name; `up` looks up its IPv4 address (and prints it), so it
318
+ works when the IP changes. `restart` does not look it up again, `up` does.
319
+ In host mode nothing is listening on the other NICs. `0.0.0.0` listens on all of them and
320
+ warns. `[[extra_ports]]` and `container.mac` have no effect in host mode.
321
+ - **Ports** are the host's own, so `ports.ssh` must not be one the host already uses (not 22 if the
322
+ host runs sshd); `up` checks, and `0` picks a free one.
323
+ - **The VNC display `:1` must be free on the host.** Host networking also shares abstract unix
324
+ sockets, so an X or VNC server of the host on `:1` would clash; `up` checks for it.
325
+ - **`container.rdma`** (InfiniBand or RoCE, ConnectX-5/6/7) passes the `/dev/infiniband/uverbs*` nodes
326
+ of the devices (and `umad*` when you may use them, and `rdma_cm`) and adds `IPC_LOCK` and an
327
+ unlimited `memlock`. `up` fails with instructions if your hard memlock limit is not unlimited
328
+ (`/etc/security/limits.d`, then log in again). Verbs programs (NCCL, `ib_write_bw`) work in either
329
+ network mode; `rdma_cm` (`ib_write_bw -R`, IP-based MPI) needs `mode = "host"`.
330
+ 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.
331
+ The link layer (InfiniBand or Ethernet/RoCE) is a property of the NIC and needs no setting here.
332
+ - **Check it** inside the container: `ibv_devinfo`, `ibstat`, `ib_write_bw` (server on one machine,
333
+ `ib_write_bw <server>` on the other), `iperf3 -c <server> -P 8`.
334
+
335
+ ### Mounts, Claude Code and Codex state
336
+
337
+ The default config mounts `./data` at `~/Projects` and `./agents/{claude,claude-personal,claude-team,codex}`
338
+ at `~/.claude`, `~/.claude-personal`, `~/.claude-team` and `~/.codex`, so logins, sessions and
339
+ settings outlive the container. `create = true` makes `up` create a missing host directory (mode
340
+ 0700). On first start the container copies the image's default config into the empty mounts;
341
+ files that exist are never overwritten. `CLAUDE_CONFIG_DIR` is set in `~/.bashrc` so `.claude.json`
342
+ lives inside the mounted directory too.
343
+
344
+ Everything else in the container (apt packages installed by hand, `~/.config`, ...) is lost when
345
+ `up` recreates it; `agentcabin cp` or `agentcabin commit` save what you need first.
346
+
347
+ ### Several containers on one host
348
+
349
+ Give each its own config file and run `agentcabin -c FILE ...`. In each: a different `container.name`,
350
+ `ports.ssh` / `ports.vnc` (or `0` for automatic ports) and host directories in `[[mounts]]`.
351
+ Containers carry the path of their config file as a label, so a config can only change or remove the
352
+ container it created (`agentcabin ps` shows the mapping).
353
+
354
+ ```bash
355
+ agentcabin init cpu.toml && agentcabin init gpu.toml # edit name, ports, mounts; gpus = "0" in gpu.toml
356
+ agentcabin -c cpu.toml up && agentcabin -c gpu.toml up
357
+ ```
358
+
359
+ ## Migrating from the compose version
360
+
361
+ `compose.yml`, `scripts/compose`, `scripts/agent-shell` and `scripts/cscp` were replaced by
362
+ `agentcabin`. `scripts/compose up` is `agentcabin up`, `scripts/agent-shell --cli` is `agentcabin shell`
363
+ and `scripts/cscp` is `agentcabin cp`. `.env` settings map to the config file: `CONTAINER_NAME` ->
364
+ `container.name`, `SSH_PORT` / `VNC_PORT` -> `ports`, `GPU` -> `container.gpus`, `DATA_DIR` and
365
+ `AGENTS_DIR` -> `[[mounts]]`. Access over SSH now uses the password (`container.password`) instead of
366
+ `ssh/authorized_keys`; add a key from the host with `ssh-copy-id -p 2222 agent@localhost`.
367
+
368
+ ## Development
369
+
370
+ ```bash
371
+ uv sync
372
+ uv run pytest # unit tests; podman is mocked
373
+ uvx ruff check src tests
374
+ uvx --from shellcheck-py shellcheck src/agentbox/assets/scripts/*.sh \
375
+ src/agentbox/assets/rootfs/usr/local/bin/entrypoint.sh
376
+ uv run agentcabin --help
377
+ ```
378
+
379
+ Dockerfile `RUN` lines must stay POSIX `/bin/sh` (podman builds OCI images, which ignore `SHELL`);
380
+ anything that needs bash goes into a script run with `bash script.sh`.