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.
- agentboxer-1.0.1/LICENSE +21 -0
- agentboxer-1.0.1/PKG-INFO +279 -0
- agentboxer-1.0.1/README.md +254 -0
- agentboxer-1.0.1/pyproject.toml +45 -0
- agentboxer-1.0.1/setup.cfg +4 -0
- agentboxer-1.0.1/src/agentbox/__init__.py +1 -0
- agentboxer-1.0.1/src/agentbox/__main__.py +3 -0
- agentboxer-1.0.1/src/agentbox/cli.py +296 -0
- agentboxer-1.0.1/src/agentbox/config.py +127 -0
- agentboxer-1.0.1/src/agentbox/share/devcontainer.base.json +22 -0
- agentboxer-1.0.1/src/agentbox/share/post-create.sh +14 -0
- agentboxer-1.0.1/src/agentboxer.egg-info/PKG-INFO +279 -0
- agentboxer-1.0.1/src/agentboxer.egg-info/SOURCES.txt +15 -0
- agentboxer-1.0.1/src/agentboxer.egg-info/dependency_links.txt +1 -0
- agentboxer-1.0.1/src/agentboxer.egg-info/entry_points.txt +2 -0
- agentboxer-1.0.1/src/agentboxer.egg-info/top_level.txt +1 -0
- agentboxer-1.0.1/tests/test_config.py +222 -0
agentboxer-1.0.1/LICENSE
ADDED
|
@@ -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 @@
|
|
|
1
|
+
__version__ = "0.1.0"
|