How agentbox Works

Explanation. This page describes the moving parts and why each exists. For steps, see the how-to guides; for exact settings, see Reference.

The idea

Frontier models are good at deciding what to change. Open-weight models on a local GPU are free per token and keep code on your machine, but they are slower and fail in predictable ways. agentbox puts the two together:

• the planner (Claude Code with Opus or Fable) investigates and writes a precise spec;
• the executor (Claude Code driving a local model) does the hands-on work;
• the planner then reviews and verifies the result before anything is merged.

The executor runs code it wrote, in a repository that may contain untrusted text such as issues, comments and dependencies. So agentbox treats it as untrusted, and builds the whole system around one rule:

The executor gets exactly one way out: a socket to a model, and nothing else.

The components

Component	Runs as	Network	Why it exists
agentbox (MCP server)	your uid, no capabilities, read-only rootfs	host (127.0.0.1)	Talks MCP to the planner. Prepares scratch clones, runs one gateway per task, and collects results through a trusted shadow git dir. It parses model output, so it holds no privileges and has none of your repos mounted.
agentbox-launcher	your uid + the docker group	none	The only component with the Docker socket, which is root-equivalent. It exposes a tiny API ("run this task with this model") and builds every container spec itself, so whoever calls it can't choose how a container runs. It never sees model output.
agent sandbox	uid 64000 (doesn't exist on the host)	none	Claude Code plus the executor model, on one scratch clone. See [[Sandbox specification
git helper	your uid, no capabilities, read-only root	none	Started by the launcher for each repo operation. It mounts just the one repo you passed (read-only to copy HEAD in, read-write to deliver agent/<id>), refuses anything that isn't a git repo owned by you, and exits in seconds.
check sandbox	uid 64000	none	Same sandbox, with no socket at all. run_checks uses it to run tests on the returned branch, so agent-written code never runs on your host.
Ollama	your uid, read-only	host (127.0.0.1:11434)	Always-on model server; pulls models on first use.
vLLM backends	per image	host (127.0.0.1:port)	High-throughput model servers, started and stopped on demand by the launcher.
llm-bridge	your uid, read-only	host (127.0.0.1:8790)	The only component with provider API keys. It translates to OpenAI Chat Completions or passes through to Anthropic. See [[Remote models

How the pieces fit

1. The planner calls delegate_task over MCP (HTTP on 127.0.0.1, bearer token), passing its current folder as repo_path.
2. agentbox makes sure the model is being served. It has a git helper copy that folder's HEAD into a private scratch clone, starts a per-task gateway on a unix socket, and asks the launcher to start a sandbox.
3. Inside the sandbox, Claude Code talks to "the Anthropic API" on its own loopback. A tiny relay forwards that to the socket, and the gateway forwards it to the model. See How a network-less agent reaches a model.
4. When the agent exits, agentbox commits the changed files through a shadow git dir the agent never saw. A git helper then writes branch agent/<id> into your repo. See Collecting results safely.
5. The planner reads the diff, then calls run_checks to run the tests on that branch in a fresh sandbox, and merges or re-delegates.

The full sequence is in Life of a delegation. The security reasoning is in Security model.