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.
- agentcabin-0.2.0/.github/actions/setup-podman/action.yml +31 -0
- agentcabin-0.2.0/.github/workflows/ci.yml +81 -0
- agentcabin-0.2.0/.gitignore +20 -0
- agentcabin-0.2.0/PKG-INFO +380 -0
- agentcabin-0.2.0/README.md +372 -0
- agentcabin-0.2.0/README.zh-CN.md +345 -0
- agentcabin-0.2.0/pyproject.toml +27 -0
- agentcabin-0.2.0/src/agentbox/__init__.py +8 -0
- agentcabin-0.2.0/src/agentbox/assets/Dockerfile +76 -0
- agentcabin-0.2.0/src/agentbox/assets/base.list +32 -0
- agentcabin-0.2.0/src/agentbox/assets/rootfs/etc/ssh/sshd_config.d/10-agentbox.conf +9 -0
- agentcabin-0.2.0/src/agentbox/assets/rootfs/usr/local/bin/entrypoint.sh +232 -0
- agentcabin-0.2.0/src/agentbox/assets/scripts/add_apt_repos.sh +95 -0
- agentcabin-0.2.0/src/agentbox/assets/scripts/apt_update.sh +27 -0
- agentcabin-0.2.0/src/agentbox/assets/scripts/create_user.sh +59 -0
- agentcabin-0.2.0/src/agentbox/assets/scripts/install_base.sh +36 -0
- agentcabin-0.2.0/src/agentbox/assets/scripts/install_firefox.sh +28 -0
- agentcabin-0.2.0/src/agentbox/assets/scripts/install_packages.sh +15 -0
- agentcabin-0.2.0/src/agentbox/assets/scripts/install_pkg_list.sh +41 -0
- agentcabin-0.2.0/src/agentbox/assets/scripts/install_tools.sh +39 -0
- agentcabin-0.2.0/src/agentbox/assets/scripts/save_defaults.sh +15 -0
- agentcabin-0.2.0/src/agentbox/assets/scripts/set_apt_mirror.sh +30 -0
- agentcabin-0.2.0/src/agentbox/assets/vnc/xstartup +16 -0
- agentcabin-0.2.0/src/agentbox/cli.py +543 -0
- agentcabin-0.2.0/src/agentbox/config.py +681 -0
- agentcabin-0.2.0/src/agentbox/errors.py +2 -0
- agentcabin-0.2.0/src/agentbox/podman.py +721 -0
- agentcabin-0.2.0/src/agentbox/templates/agentbox.toml +449 -0
- agentcabin-0.2.0/tests/conftest.py +7 -0
- agentcabin-0.2.0/tests/smoke/smoke.sh +257 -0
- agentcabin-0.2.0/tests/test_agentbox.py +523 -0
- agentcabin-0.2.0/tests/test_apt_repos.py +151 -0
- agentcabin-0.2.0/tests/test_auto_ports.py +117 -0
- agentcabin-0.2.0/tests/test_cli_commit.py +70 -0
- agentcabin-0.2.0/tests/test_cli_up.py +73 -0
- agentcabin-0.2.0/tests/test_limits.py +105 -0
- 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`.
|