agentboxer 1.0.1__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.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Kevin Veen-Birkenbach
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,279 @@
1
+ Metadata-Version: 2.4
2
+ Name: agentboxer
3
+ Version: 1.0.1
4
+ Summary: Run coding agents in a per-project dev container sandbox.
5
+ Author-email: Kevin Veen-Birkenbach <kevin@veen.world>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/kevinveenbirkenbach/agentbox
8
+ Project-URL: Source, https://github.com/kevinveenbirkenbach/agentbox
9
+ Project-URL: Issues, https://github.com/kevinveenbirkenbach/agentbox/issues
10
+ Keywords: devcontainer,sandbox,agent,docker,claude-code
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Environment :: Console
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Operating System :: POSIX :: Linux
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Topic :: Software Development :: Build Tools
21
+ Requires-Python: >=3.10
22
+ Description-Content-Type: text/markdown
23
+ License-File: LICENSE
24
+ Dynamic: license-file
25
+
26
+ # agentbox
27
+
28
+ Run coding agents in a per-project dev container sandbox.
29
+
30
+ The agent gets a container with its own Docker daemon and nothing of the host but the project directory: no host Docker socket, no host home, no sibling repositories. One command per project, no per-project boilerplate.
31
+
32
+ Homepage: https://github.com/kevinveenbirkenbach/agentbox
33
+
34
+ ## How it fits together
35
+
36
+ ```mermaid
37
+ flowchart LR
38
+ subgraph host["Host"]
39
+ editor["Code - OSS / VSCodium<br/>open-remote-ssh"]
40
+ cli["agentbox CLI"]
41
+ state["~/.config/agentbox<br/>aliases + keys + ssh.d/*.conf"]
42
+ dockerd["host docker daemon"]
43
+ repo[("project directory")]
44
+ end
45
+
46
+ subgraph layers["Configuration layers"]
47
+ base["1 base<br/>share/devcontainer.base.json"]
48
+ project["2 project<br/>.devcontainer/devcontainer.json"]
49
+ override["3 local<br/>.devcontainer/agentbox.local.json"]
50
+ merged["effective devcontainer.json"]
51
+ end
52
+
53
+ subgraph box["agentbox container"]
54
+ sshd["sshd on 2222"]
55
+ exthost["remote extension host<br/>agent extension"]
56
+ agent["agent CLI<br/>claude / codex / ..."]
57
+ dind["own docker daemon"]
58
+ workspace["/workspaces/PROJECT"]
59
+ nested["containers the agent starts"]
60
+ end
61
+
62
+ base --> merged
63
+ project --> merged
64
+ override --> merged
65
+ cli -- "deep merge" --> merged
66
+ merged -- "override config" --> devcli["npx @devcontainers/cli"]
67
+ cli --> devcli
68
+ devcli -- "build and start" --> dockerd
69
+ dockerd -- "creates" --> box
70
+ cli -- "ssh key, host entry" --> state
71
+ cli -- "agentbox run / shell" --> agent
72
+ editor -- "reads" --> state
73
+ editor -- "ssh 127.0.0.1 on a free port" --> sshd
74
+ sshd --> exthost
75
+ exthost <-- "~/.claude/ide + localhost" --> agent
76
+ agent --> workspace
77
+ agent --> dind
78
+ dind --> nested
79
+ repo -- "bind mount" --> workspace
80
+ ```
81
+
82
+ What the picture says:
83
+
84
+ - The agent only ever reaches `/workspaces/PROJECT`, which is the bind-mounted project directory. No host home, no sibling repositories.
85
+ - The container talks to its **own** Docker daemon. The host daemon is used once, by the CLI, to create the sandbox — the agent never gets a handle on it.
86
+ - The agent extension runs in the container, next to the agent CLI, because the two communicate over `~/.claude/ide` plus localhost. An extension host on the host side cannot reach either.
87
+ - The three configuration layers are merged on the host and handed to the devcontainer CLI as one file; nothing has to be edited by hand.
88
+
89
+ ## Install
90
+
91
+ ```bash
92
+ pipx install agentboxer
93
+ ```
94
+
95
+ The distribution is named `agentboxer` because `agentbox` is taken on PyPI and `agentbox-cli` collides with an existing project once PyPI strips the separators; the command it installs is `agentbox`.
96
+
97
+ Independent of PyPI, from a checkout:
98
+
99
+ ```bash
100
+ make install
101
+ ```
102
+
103
+ The package itself has no Python dependencies, but it drives three host binaries and refuses to start without them:
104
+
105
+ | Binary | Used for |
106
+ |---|---|
107
+ | `docker` | building and running the sandbox |
108
+ | `npx` (Node.js) | fetching the [devcontainer CLI](https://github.com/devcontainers/cli) |
109
+ | `ssh-keygen` | the per-project key |
110
+
111
+ ## Quickstart
112
+
113
+ ```bash
114
+ cd ~/Repositories/some-project
115
+ agentbox up
116
+ agentbox run claude
117
+ ```
118
+
119
+ `agentbox up` builds and starts the sandbox, publishes its SSH port on a free `127.0.0.1` port, installs a per-project key, and writes an SSH host entry named after the project directory.
120
+
121
+ ## Commands
122
+
123
+ | Command | What it does |
124
+ |---|---|
125
+ | `agentbox up [--rebuild]` | Build and start the sandbox for the current directory |
126
+ | `agentbox run <cmd…>` | Run a command inside the sandbox, e.g. `agentbox run claude` |
127
+ | `agentbox shell` | Open a shell inside the sandbox |
128
+ | `agentbox code` | Open Code - OSS / VSCodium / VS Code on the sandbox |
129
+ | `agentbox down` | Remove the sandbox container |
130
+ | `agentbox init` | Write a project-owned `.devcontainer/devcontainer.json` |
131
+
132
+ All commands accept `--workspace <dir>` and otherwise act on the current directory.
133
+
134
+ ## One box per repository
135
+
136
+ Boxes run side by side and share nothing. Each project gets its own container, SSH port, key, host entry and agent home volume:
137
+
138
+ | Resource | Keyed by |
139
+ |---|---|
140
+ | Container | label `devcontainer.local_folder=<absolute path>` |
141
+ | SSH port | published by Docker on a free `127.0.0.1` port |
142
+ | Key, host entry | `~/.config/agentbox/keys/<alias>/`, `~/.config/agentbox/ssh.d/<alias>.conf` |
143
+ | Agent home (logins, history) | volume `agentbox-home-<alias>` |
144
+
145
+ The alias is the project directory name. Two repositories with the same directory name — `~/work/web` and `~/client/web` — would otherwise collide in all of the above, so the first one to claim `web` keeps it and the next gets a path digest appended: `web-0ac1b2`. Claims live in `~/.config/agentbox/aliases/` and are sticky, so an alias never changes under a running box.
146
+
147
+ Removing a box: `agentbox down`, plus `docker volume rm agentbox-home-<alias>` if its agent state should go too.
148
+
149
+ ## Configuration layers
150
+
151
+ Later layers win; each is optional.
152
+
153
+ | Layer | File | Versioned |
154
+ |---|---|---|
155
+ | 1. agentbox default | `src/agentbox/share/devcontainer.base.json` | in this repo |
156
+ | 2. Project | `<project>/.devcontainer/devcontainer.json` | in the project |
157
+ | 3. Local override | `<project>/.devcontainer/agentbox.local.json` | no, gitignore it |
158
+
159
+ Layer 3 is deep-merged over whatever layer sits below it; dictionaries merge, lists and scalars are replaced. The merged result is handed to the devcontainer CLI via `--override-config`, so nothing needs to be edited by hand.
160
+
161
+ Example — this project needs Codex instead of Claude and a Python toolchain, but only on this machine:
162
+
163
+ ```json
164
+ {
165
+ "containerEnv": { "AGENTBOX_AGENTS": "@openai/codex" },
166
+ "features": { "ghcr.io/devcontainers/features/python:1": {} }
167
+ }
168
+ ```
169
+
170
+ Agents are npm packages listed in `AGENTBOX_AGENTS`, installed on first start.
171
+
172
+ ## Editor
173
+
174
+ The agent extension must run inside the container, otherwise it cannot reach the agent CLI. That happens automatically once the editor window itself is remote.
175
+
176
+ 1. Install `jeanp413.open-remote-ssh` from Open VSX (the proprietary Dev Containers extension is not needed and is unavailable on Open VSX).
177
+ 2. Add this line once to `~/.ssh/config`:
178
+
179
+ ```
180
+ Include ~/.config/agentbox/ssh.d/*.conf
181
+ ```
182
+
183
+ 3. `agentbox code`, or connect manually to the host entry named after the project and open `/workspaces/<project>`.
184
+
185
+ Ports change on every rebuild; `agentbox up` rewrites the host entry each time, so the alias stays valid.
186
+
187
+ ## Projects that already have a devcontainer.json
188
+
189
+ `agentbox up` uses the project's own config unchanged. To install the agents from there, add the feature in this repository:
190
+
191
+ ```json
192
+ "features": { "ghcr.io/kevinveenbirkenbach/agentbox/agentbox:0": { "agents": "@anthropic-ai/claude-code" } }
193
+ ```
194
+
195
+ The feature source lives in `features/agentbox/`; publish it with `devcontainer features publish`.
196
+
197
+ ## Limitations
198
+
199
+ - The project directory is bind-mounted, so build artifacts inside it (`.venv/`, `node_modules/`) are shared with the host and can collide between host and container toolchains. Mount them as volumes in layer 3 if that bites.
200
+ - Containers started *inside* the sandbox run in its nested Docker daemon; their published ports are not reachable from the host.
201
+ - Network access is not restricted yet — the sandbox isolates the filesystem and the Docker daemon, not the internet.
202
+ - The agent CLIs themselves are proprietary; only the sandbox around them is open source.
203
+
204
+ ## Other agents
205
+
206
+ `AGENTBOX_AGENTS` is a space separated list of npm packages installed on first start. Override it per project in `.devcontainer/agentbox.local.json`:
207
+
208
+ ```json
209
+ {
210
+ "containerEnv": {
211
+ "AGENTBOX_AGENTS": "@anthropic-ai/claude-code @openai/codex @google/gemini-cli"
212
+ }
213
+ }
214
+ ```
215
+
216
+ Then `agentbox up --rebuild` and `agentbox run codex`. Agents that are not npm packages (pipx tools, plain binaries) have no install path yet. The Pi agent (`@oh-my-pi/pi-coding-agent`, binary `omp`) needs bun rather than node.
217
+
218
+ ## Local LLMs
219
+
220
+ The sandbox has its own network namespace, so an Ollama or LM Studio server running on the **host** is not reachable from inside by default. Punch one hole into `.devcontainer/agentbox.local.json`:
221
+
222
+ ```json
223
+ {
224
+ "runArgs": ["--add-host=host.docker.internal:host-gateway"],
225
+ "containerEnv": {
226
+ "OLLAMA_BASE_URL": "http://host.docker.internal:11434",
227
+ "OLLAMA_HOST": "http://host.docker.internal:11434"
228
+ }
229
+ }
230
+ ```
231
+
232
+ What each agent does with that, verified in the e2e suite below:
233
+
234
+ | Agent | Ollama | LM Studio | Invocation |
235
+ |---|---|---|---|
236
+ | codex | yes | yes | `codex exec -c model_provider=x -c model_providers.x.base_url=<url>/v1 -c model_providers.x.wire_api=responses -c model_providers.x.requires_openai_auth=false -m <model>` |
237
+ | pi (`omp`) | yes | catalog discovery works | `omp --model ollama/<model>` with `OLLAMA_BASE_URL` set, or `omp --model lm-studio/<model>` |
238
+ | Claude Code | via proxy | via proxy | Anthropic protocol only — needs a translator (e.g. LiteLLM) behind `ANTHROPIC_BASE_URL` |
239
+
240
+ Three constraints found the hard way, each encoded in the e2e suite:
241
+
242
+ - codex accepts only `wire_api = "responses"`; the chat-completions wire was removed. Both servers implement that endpoint.
243
+ - `codex --oss` insists on a daemon at `localhost:11434` and ignores `OLLAMA_HOST`, so a remote endpoint needs an explicit provider.
244
+ - Agent CLIs need a model that supports tool calling. `smollm2:135m` answers plain chat requests but fails every agent.
245
+
246
+ ## Tests
247
+
248
+ Everything at once — unit tests plus the end-to-end suite:
249
+
250
+ ```bash
251
+ make test
252
+ ```
253
+
254
+ Unit tests alone, no containers:
255
+
256
+ ```bash
257
+ make test-unit
258
+ ```
259
+
260
+ End-to-end against real local LLMs, fully isolated in compose — Ollama, LM Studio in headless server mode, and a runner carrying codex and pi. No host network, no API keys, no accounts:
261
+
262
+ ```bash
263
+ make test-e2e # tears the stack down afterwards
264
+ bash tests/e2e/run.sh --keep # leaves it up for debugging
265
+ ```
266
+
267
+ Models are pulled once into named volumes: `qwen2.5:0.5b` for Ollama, and for LM Studio the Hugging Face repository pinned in `tests/e2e/.env` — its CLI resolves search terms only against staff picks, so the source is a full URL rather than a name. Twelve checks then assert reachability, the native and OpenAI-compatible endpoints, and that codex and pi actually answer from a local model.
268
+
269
+ The runner shares the LM Studio container's network namespace, so LM Studio sits on `localhost:1234` exactly as the agent CLIs expect while Ollama stays reachable by service name.
270
+
271
+ Everything runs in CI on every push and pull request, and again before a release.
272
+
273
+ ## License
274
+
275
+ MIT — see [LICENSE](LICENSE).
276
+
277
+ ## Author
278
+
279
+ Kevin Veen-Birkenbach <kevin@veen.world>
@@ -0,0 +1,254 @@
1
+ # agentbox
2
+
3
+ Run coding agents in a per-project dev container sandbox.
4
+
5
+ The agent gets a container with its own Docker daemon and nothing of the host but the project directory: no host Docker socket, no host home, no sibling repositories. One command per project, no per-project boilerplate.
6
+
7
+ Homepage: https://github.com/kevinveenbirkenbach/agentbox
8
+
9
+ ## How it fits together
10
+
11
+ ```mermaid
12
+ flowchart LR
13
+ subgraph host["Host"]
14
+ editor["Code - OSS / VSCodium<br/>open-remote-ssh"]
15
+ cli["agentbox CLI"]
16
+ state["~/.config/agentbox<br/>aliases + keys + ssh.d/*.conf"]
17
+ dockerd["host docker daemon"]
18
+ repo[("project directory")]
19
+ end
20
+
21
+ subgraph layers["Configuration layers"]
22
+ base["1 base<br/>share/devcontainer.base.json"]
23
+ project["2 project<br/>.devcontainer/devcontainer.json"]
24
+ override["3 local<br/>.devcontainer/agentbox.local.json"]
25
+ merged["effective devcontainer.json"]
26
+ end
27
+
28
+ subgraph box["agentbox container"]
29
+ sshd["sshd on 2222"]
30
+ exthost["remote extension host<br/>agent extension"]
31
+ agent["agent CLI<br/>claude / codex / ..."]
32
+ dind["own docker daemon"]
33
+ workspace["/workspaces/PROJECT"]
34
+ nested["containers the agent starts"]
35
+ end
36
+
37
+ base --> merged
38
+ project --> merged
39
+ override --> merged
40
+ cli -- "deep merge" --> merged
41
+ merged -- "override config" --> devcli["npx @devcontainers/cli"]
42
+ cli --> devcli
43
+ devcli -- "build and start" --> dockerd
44
+ dockerd -- "creates" --> box
45
+ cli -- "ssh key, host entry" --> state
46
+ cli -- "agentbox run / shell" --> agent
47
+ editor -- "reads" --> state
48
+ editor -- "ssh 127.0.0.1 on a free port" --> sshd
49
+ sshd --> exthost
50
+ exthost <-- "~/.claude/ide + localhost" --> agent
51
+ agent --> workspace
52
+ agent --> dind
53
+ dind --> nested
54
+ repo -- "bind mount" --> workspace
55
+ ```
56
+
57
+ What the picture says:
58
+
59
+ - The agent only ever reaches `/workspaces/PROJECT`, which is the bind-mounted project directory. No host home, no sibling repositories.
60
+ - The container talks to its **own** Docker daemon. The host daemon is used once, by the CLI, to create the sandbox — the agent never gets a handle on it.
61
+ - The agent extension runs in the container, next to the agent CLI, because the two communicate over `~/.claude/ide` plus localhost. An extension host on the host side cannot reach either.
62
+ - The three configuration layers are merged on the host and handed to the devcontainer CLI as one file; nothing has to be edited by hand.
63
+
64
+ ## Install
65
+
66
+ ```bash
67
+ pipx install agentboxer
68
+ ```
69
+
70
+ The distribution is named `agentboxer` because `agentbox` is taken on PyPI and `agentbox-cli` collides with an existing project once PyPI strips the separators; the command it installs is `agentbox`.
71
+
72
+ Independent of PyPI, from a checkout:
73
+
74
+ ```bash
75
+ make install
76
+ ```
77
+
78
+ The package itself has no Python dependencies, but it drives three host binaries and refuses to start without them:
79
+
80
+ | Binary | Used for |
81
+ |---|---|
82
+ | `docker` | building and running the sandbox |
83
+ | `npx` (Node.js) | fetching the [devcontainer CLI](https://github.com/devcontainers/cli) |
84
+ | `ssh-keygen` | the per-project key |
85
+
86
+ ## Quickstart
87
+
88
+ ```bash
89
+ cd ~/Repositories/some-project
90
+ agentbox up
91
+ agentbox run claude
92
+ ```
93
+
94
+ `agentbox up` builds and starts the sandbox, publishes its SSH port on a free `127.0.0.1` port, installs a per-project key, and writes an SSH host entry named after the project directory.
95
+
96
+ ## Commands
97
+
98
+ | Command | What it does |
99
+ |---|---|
100
+ | `agentbox up [--rebuild]` | Build and start the sandbox for the current directory |
101
+ | `agentbox run <cmd…>` | Run a command inside the sandbox, e.g. `agentbox run claude` |
102
+ | `agentbox shell` | Open a shell inside the sandbox |
103
+ | `agentbox code` | Open Code - OSS / VSCodium / VS Code on the sandbox |
104
+ | `agentbox down` | Remove the sandbox container |
105
+ | `agentbox init` | Write a project-owned `.devcontainer/devcontainer.json` |
106
+
107
+ All commands accept `--workspace <dir>` and otherwise act on the current directory.
108
+
109
+ ## One box per repository
110
+
111
+ Boxes run side by side and share nothing. Each project gets its own container, SSH port, key, host entry and agent home volume:
112
+
113
+ | Resource | Keyed by |
114
+ |---|---|
115
+ | Container | label `devcontainer.local_folder=<absolute path>` |
116
+ | SSH port | published by Docker on a free `127.0.0.1` port |
117
+ | Key, host entry | `~/.config/agentbox/keys/<alias>/`, `~/.config/agentbox/ssh.d/<alias>.conf` |
118
+ | Agent home (logins, history) | volume `agentbox-home-<alias>` |
119
+
120
+ The alias is the project directory name. Two repositories with the same directory name — `~/work/web` and `~/client/web` — would otherwise collide in all of the above, so the first one to claim `web` keeps it and the next gets a path digest appended: `web-0ac1b2`. Claims live in `~/.config/agentbox/aliases/` and are sticky, so an alias never changes under a running box.
121
+
122
+ Removing a box: `agentbox down`, plus `docker volume rm agentbox-home-<alias>` if its agent state should go too.
123
+
124
+ ## Configuration layers
125
+
126
+ Later layers win; each is optional.
127
+
128
+ | Layer | File | Versioned |
129
+ |---|---|---|
130
+ | 1. agentbox default | `src/agentbox/share/devcontainer.base.json` | in this repo |
131
+ | 2. Project | `<project>/.devcontainer/devcontainer.json` | in the project |
132
+ | 3. Local override | `<project>/.devcontainer/agentbox.local.json` | no, gitignore it |
133
+
134
+ Layer 3 is deep-merged over whatever layer sits below it; dictionaries merge, lists and scalars are replaced. The merged result is handed to the devcontainer CLI via `--override-config`, so nothing needs to be edited by hand.
135
+
136
+ Example — this project needs Codex instead of Claude and a Python toolchain, but only on this machine:
137
+
138
+ ```json
139
+ {
140
+ "containerEnv": { "AGENTBOX_AGENTS": "@openai/codex" },
141
+ "features": { "ghcr.io/devcontainers/features/python:1": {} }
142
+ }
143
+ ```
144
+
145
+ Agents are npm packages listed in `AGENTBOX_AGENTS`, installed on first start.
146
+
147
+ ## Editor
148
+
149
+ The agent extension must run inside the container, otherwise it cannot reach the agent CLI. That happens automatically once the editor window itself is remote.
150
+
151
+ 1. Install `jeanp413.open-remote-ssh` from Open VSX (the proprietary Dev Containers extension is not needed and is unavailable on Open VSX).
152
+ 2. Add this line once to `~/.ssh/config`:
153
+
154
+ ```
155
+ Include ~/.config/agentbox/ssh.d/*.conf
156
+ ```
157
+
158
+ 3. `agentbox code`, or connect manually to the host entry named after the project and open `/workspaces/<project>`.
159
+
160
+ Ports change on every rebuild; `agentbox up` rewrites the host entry each time, so the alias stays valid.
161
+
162
+ ## Projects that already have a devcontainer.json
163
+
164
+ `agentbox up` uses the project's own config unchanged. To install the agents from there, add the feature in this repository:
165
+
166
+ ```json
167
+ "features": { "ghcr.io/kevinveenbirkenbach/agentbox/agentbox:0": { "agents": "@anthropic-ai/claude-code" } }
168
+ ```
169
+
170
+ The feature source lives in `features/agentbox/`; publish it with `devcontainer features publish`.
171
+
172
+ ## Limitations
173
+
174
+ - The project directory is bind-mounted, so build artifacts inside it (`.venv/`, `node_modules/`) are shared with the host and can collide between host and container toolchains. Mount them as volumes in layer 3 if that bites.
175
+ - Containers started *inside* the sandbox run in its nested Docker daemon; their published ports are not reachable from the host.
176
+ - Network access is not restricted yet — the sandbox isolates the filesystem and the Docker daemon, not the internet.
177
+ - The agent CLIs themselves are proprietary; only the sandbox around them is open source.
178
+
179
+ ## Other agents
180
+
181
+ `AGENTBOX_AGENTS` is a space separated list of npm packages installed on first start. Override it per project in `.devcontainer/agentbox.local.json`:
182
+
183
+ ```json
184
+ {
185
+ "containerEnv": {
186
+ "AGENTBOX_AGENTS": "@anthropic-ai/claude-code @openai/codex @google/gemini-cli"
187
+ }
188
+ }
189
+ ```
190
+
191
+ Then `agentbox up --rebuild` and `agentbox run codex`. Agents that are not npm packages (pipx tools, plain binaries) have no install path yet. The Pi agent (`@oh-my-pi/pi-coding-agent`, binary `omp`) needs bun rather than node.
192
+
193
+ ## Local LLMs
194
+
195
+ The sandbox has its own network namespace, so an Ollama or LM Studio server running on the **host** is not reachable from inside by default. Punch one hole into `.devcontainer/agentbox.local.json`:
196
+
197
+ ```json
198
+ {
199
+ "runArgs": ["--add-host=host.docker.internal:host-gateway"],
200
+ "containerEnv": {
201
+ "OLLAMA_BASE_URL": "http://host.docker.internal:11434",
202
+ "OLLAMA_HOST": "http://host.docker.internal:11434"
203
+ }
204
+ }
205
+ ```
206
+
207
+ What each agent does with that, verified in the e2e suite below:
208
+
209
+ | Agent | Ollama | LM Studio | Invocation |
210
+ |---|---|---|---|
211
+ | codex | yes | yes | `codex exec -c model_provider=x -c model_providers.x.base_url=<url>/v1 -c model_providers.x.wire_api=responses -c model_providers.x.requires_openai_auth=false -m <model>` |
212
+ | pi (`omp`) | yes | catalog discovery works | `omp --model ollama/<model>` with `OLLAMA_BASE_URL` set, or `omp --model lm-studio/<model>` |
213
+ | Claude Code | via proxy | via proxy | Anthropic protocol only — needs a translator (e.g. LiteLLM) behind `ANTHROPIC_BASE_URL` |
214
+
215
+ Three constraints found the hard way, each encoded in the e2e suite:
216
+
217
+ - codex accepts only `wire_api = "responses"`; the chat-completions wire was removed. Both servers implement that endpoint.
218
+ - `codex --oss` insists on a daemon at `localhost:11434` and ignores `OLLAMA_HOST`, so a remote endpoint needs an explicit provider.
219
+ - Agent CLIs need a model that supports tool calling. `smollm2:135m` answers plain chat requests but fails every agent.
220
+
221
+ ## Tests
222
+
223
+ Everything at once — unit tests plus the end-to-end suite:
224
+
225
+ ```bash
226
+ make test
227
+ ```
228
+
229
+ Unit tests alone, no containers:
230
+
231
+ ```bash
232
+ make test-unit
233
+ ```
234
+
235
+ End-to-end against real local LLMs, fully isolated in compose — Ollama, LM Studio in headless server mode, and a runner carrying codex and pi. No host network, no API keys, no accounts:
236
+
237
+ ```bash
238
+ make test-e2e # tears the stack down afterwards
239
+ bash tests/e2e/run.sh --keep # leaves it up for debugging
240
+ ```
241
+
242
+ Models are pulled once into named volumes: `qwen2.5:0.5b` for Ollama, and for LM Studio the Hugging Face repository pinned in `tests/e2e/.env` — its CLI resolves search terms only against staff picks, so the source is a full URL rather than a name. Twelve checks then assert reachability, the native and OpenAI-compatible endpoints, and that codex and pi actually answer from a local model.
243
+
244
+ The runner shares the LM Studio container's network namespace, so LM Studio sits on `localhost:1234` exactly as the agent CLIs expect while Ollama stays reachable by service name.
245
+
246
+ Everything runs in CI on every push and pull request, and again before a release.
247
+
248
+ ## License
249
+
250
+ MIT — see [LICENSE](LICENSE).
251
+
252
+ ## Author
253
+
254
+ Kevin Veen-Birkenbach <kevin@veen.world>
@@ -0,0 +1,45 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "agentboxer"
7
+ version = "1.0.1"
8
+ description = "Run coding agents in a per-project dev container sandbox."
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ authors = [{ name = "Kevin Veen-Birkenbach", email = "kevin@veen.world" }]
12
+ license = "MIT"
13
+ license-files = ["LICENSE"]
14
+ keywords = ["devcontainer", "sandbox", "agent", "docker", "claude-code"]
15
+ classifiers = [
16
+ "Development Status :: 3 - Alpha",
17
+ "Environment :: Console",
18
+ "Intended Audience :: Developers",
19
+ "Operating System :: POSIX :: Linux",
20
+ "Programming Language :: Python :: 3",
21
+ "Programming Language :: Python :: 3.10",
22
+ "Programming Language :: Python :: 3.11",
23
+ "Programming Language :: Python :: 3.12",
24
+ "Programming Language :: Python :: 3.13",
25
+ "Topic :: Software Development :: Build Tools",
26
+ ]
27
+
28
+ dependencies = []
29
+
30
+ [project.urls]
31
+ Homepage = "https://github.com/kevinveenbirkenbach/agentbox"
32
+ Source = "https://github.com/kevinveenbirkenbach/agentbox"
33
+ Issues = "https://github.com/kevinveenbirkenbach/agentbox/issues"
34
+
35
+ [project.scripts]
36
+ agentbox = "agentbox.cli:main"
37
+
38
+ [tool.setuptools]
39
+ package-dir = {"" = "src"}
40
+
41
+ [tool.setuptools.package-data]
42
+ agentbox = ["share/*"]
43
+
44
+ [tool.setuptools.packages.find]
45
+ where = ["src"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1 @@
1
+ __version__ = "0.1.0"
@@ -0,0 +1,3 @@
1
+ from .cli import main
2
+
3
+ raise SystemExit(main())