REST API

The hub serves a small, versioned REST API under /api/v1 on the same port as the hub UI and relay (http://127.0.0.1:8787 locally). It's for programmatic callers — IDE integrations, scripts, macOS apps, etc. — and is the way to drive AgentBox when the hub runs on a separate host (a control plane), where there's no local CLI to shell out to.

Base URL and versioning

http://127.0.0.1:8787/api/v1

Every path is prefixed with /api/v1. The version is in the path so future breaking changes can ship as /api/v2 without disturbing existing clients.

Auth

Every endpoint except /health, /openapi.json, and /docs requires the hub token as a Bearer credential:

TOKEN=$(cat ~/.agentbox/hub/token)
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8787/api/v1/boxes

The token is the same per-machine secret the hub prints on boot (and stores at ~/.agentbox/hub/token, mode 0600). Requests without a valid token get a JSON 401 — never a redirect, so non-browser clients work cleanly. On a shared (password-protected) hub, /api/v1 accepts the logged-in session; dedicated API keys arrive with the hosted deployment.

Response shape

Success responses return the resource or collection directly. Errors are always:

{ "error": { "code": "not_found", "message": "box not found: abc123" } }

with an HTTP status that matches the code (400 invalid_request, 401 unauthorized, 404 not_found, 409 conflict, 503 backend_unavailable).

Endpoints

Endpoints are grouped by topic — the same sections you'll see in the sidebar of the interactive reference at GET /docs.

System

Boxes

Box git

Box services

Projects

Providers

Approvals

Jobs

The box view is provider-agnostic: { id, projectId, repo, branch, task, agent, status, createdAt, lastActivity, host, commits, filesTouched, error }, where status is one of running | paused | stopped | creating | error.

Creating a box

Creation is asynchronous — it enqueues a build job and returns immediately:

# Register the folder once (skip if it's already a project):
curl -X POST -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"path":"/abs/path/to/repo"}' \
  http://127.0.0.1:8787/api/v1/projects

# Create a box for it (grab the projectId from GET /projects):
curl -X POST -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"projectId":"<id>","agent":"claude","name":"feature-x"}' \
  http://127.0.0.1:8787/api/v1/boxes
# -> 202 { "jobId": "..." }

A box being built shows up in GET /boxes with status: "creating" right away, then flips to running once the container is up.

Streaming logs (SSE)

GET /jobs/{id}/logs is a Server-Sent Events stream: an open event, then a log event per line, then a terminal end event with the final status.

curl -N -H "Authorization: Bearer $TOKEN" \
  http://127.0.0.1:8787/api/v1/jobs/<jobId>/logs

event: open
data: {"id":"<jobId>"}

event: log
data: "... building image ..."

event: end
data: {"status":"done"}

Installing providers & baking images

Before a cloud provider can host boxes it needs two things on the host: its credentials and its baked base image. Both are drivable over the API (the hub settings UI uses exactly these calls), so you never have to drop to a terminal:

# 1. Save credentials (validated against the cloud, then written to secrets.env):
curl -X POST -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"apiKey":"e2b_..."}' \
  http://127.0.0.1:8787/api/v1/providers/e2b/credentials
# -> 200 { "ok": true }   (a rejected token -> 400 with the reason)

# 2. Bake the base image (async — stream the build like a create job):
curl -X POST -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{}' http://127.0.0.1:8787/api/v1/providers/e2b/prepare
# -> 202 { "jobId": "..." }
curl -N -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8787/api/v1/jobs/<jobId>/logs

Once the bake finishes, GET /providers reports the provider as configured: true and it becomes a valid provider for POST /boxes. Docker needs no credentials; its base self-heals, so a bake there is optional (a force rebuild).

Exploring the API

GET /api/v1/docs renders the full spec (an interactive reference), and GET /api/v1/openapi.json returns the raw OpenAPI 3.1 document you can feed to a client generator or an IDE's HTTP client.