Internal APIs

Reference. Interfaces between agentbox's own components. They aren't meant for direct use, but they're documented so they can be audited.

Launcher ($AGENTBOX_DATA/run/launcher.sock, HTTP over a unix socket)

Method & path	Body / query	Effect
POST /agents	{tid, model, cmd[], env{}, venv?, timeout_s}	Validate, chown the workspace to the agent uid, start the agent sandbox
POST /checks	{tid, command, venv?, timeout_s}	Same, as a check sandbox without a socket
POST /repo/snapshot	{tid, path, ref?}	Git helper: find the repo for path (walks up, handles worktrees), copy ref (default HEAD) into the task's shadow dir. Returns {repo, sha}.
POST /repo/deliver	{tid, path, branch}	Git helper: fetch agent/<id> from the shadow into the repo
POST /repo/delete-branch	{path, branch}	Git helper: delete an agent/<id> branch (nothing else)
GET /agents/{tid}	?wait=1 blocks until exit	{state, exit_code, oom_killed, stdout, stderr}
DELETE /agents/{tid}		Remove the container; hand the workspace back to the agentbox uid
POST /backends/{model}/start		Start this vLLM model; stop idle other vLLM containers; 409 if busy
POST /backends/vllm/stop		Stop all vLLM backends; 409 if any vLLM agent is running
GET /status		agentbox-labelled containers

Validation:

• tid must match ^[0-9a-z][0-9a-z-]{0,63}$;
• paths are derived from tid and checked component by component with lstat: a symlink anywhere is refused, and the chown helper re-checks the device and inode it actually mounted;
• repo and venv paths must be normalized absolute paths inside their allowlists; git helpers mount them with the Mounts API, which never creates a missing path, and check ownership before acting;
• the workspace must be owned by the agentbox uid;
• agent cmd[0] must be claude;
• only allowlisted env keys pass through;
• venvs must contain bin/python and live under a venv root.

Per-task gateway (sockets/<tid>/llm.sock, inside each agent at /run/gw/llm.sock)

• POST /v1/messages, POST /v1/messages/count_tokens (estimated locally); anything else returns 404.
• Auth: Authorization: Bearer <task token> or x-api-key; otherwise 401.
• model is rewritten to the task's model. Server-side tools, mcp_servers, container and context_management are removed. Only anthropic-version is forwarded.
• Usage is metered from responses. When the budget is exhausted the gateway returns 403 permission_error, which Claude Code doesn't retry.
• Destinations:
  • Ollama: 127.0.0.1:11434/v1/messages;
  • vLLM: 127.0.0.1:<port>/v1/messages;
  • remote models: llm-bridge.

llm-bridge (127.0.0.1:8790, HTTP)

Method & path	Notes
POST /v1/messages	Body model = agentbox model id. openai: translated to /chat/completions; anthropic: passed through to /v1/messages
GET /check/{model}	{ok, error?}: key configured? upstream reachable?
GET /health	Unauthenticated; lists external models

Auth on every request except /health: Authorization: Bearer <AGENTBOX_BRIDGE_TOKEN>. Requests are sanitized again before they leave. Provider keys are injected here: as Authorization: Bearer for openai and x-api-key for anthropic.