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.

This is not a second surface bolted onto the side. The AgentBox CLI itself drives every box and fleet operation through this same /api/v1 — create, lifecycle, listing, git, approvals, services, checkpoints, prune and custody all go through the hub, against a local hub and a remote control box alike. "Enable a remote hub" is a base-URL swap, not a different code path. (The one operation still handled outside the API is the direct IO plane — shell, attach, cp, download, code, open — which talks to the box from your machine; see what still needs your laptop. url and screen go through the API on every provider, except --loopback, which by definition means "this machine".)

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 deployed control box (password-protected hub), /api/v1 accepts either the logged-in browser session or a headless API key as the same Authorization: Bearer credential — so the CLI, the menu-bar app, or a script can call the remote hub without a cookie:

# the key is minted + recorded by `agentbox hub setup`/deploy
KEY=$(grep '^AGENTBOX_HUB_API_KEY=' ~/.agentbox/control-plane/control-plane.env | cut -d= -f2)
curl -H "Authorization: Bearer $KEY" https://<your-control-box>/api/v1/boxes

The key (AGENTBOX_HUB_API_KEY) gates only /api/v1, never the UI pages (those still require a login). A wrong or missing key gets the same JSON 401.

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

Checkpoints

Checkpoints are durable per-project assets — a docker image or cloud snapshot the box's create warms from. They outlive the box and live in a store on the hub's machine, keyed by the absolute project root (so on a genuinely remote control box a thin laptop can't list them by its own path — a limitation of path-hash-keyed stores). agentbox prune never touches them.

Fleet

Box git

Box services

Projects

Providers

| Method + path | Description | | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET /providers | Sandbox providers with credential + baked status on this host: { id, label, configured, hasCredentials?, jobId?, reason? }. configured = base image baked (usable for create); hasCredentials = credentials present (docker always); jobId = an in-flight bake, if any. Add ?freshness=1 to also report base-image staleness per provider: baseStatus (fresh | stale | unprepared | unknown) + baseStaleReason when stale — stale means the baked snapshot is out of date and agentbox prepare --provider <id> should be re-run. Docker reports real freshness too (unprepared = the base image hasn't been built yet, stale = the next create will rebuild it) while staying configured: true — its base self-heals at create time, so freshness is a heads-up for UIs to announce the bake, never a gate. Freshness loads provider code and hashes the runtime build context (memoized ~60s for cloud providers), so it's kept off the default fast path; it's populated only on the in-process host topology (omitted on the hosted plane). | | POST /providers/{id}/credentials | Set a provider's credentials (validated against the cloud, then saved to ~/.agentbox/secrets.env). Body is provider-specific string fields: { apiKey } (e2b/daytona), { token } (hetzner), { token, teamId?, projectId? } (vercel). Never echoes secret values. Host-topology only (503 on the hosted plane). | | POST /providers/{id}/prepare | Bake a provider's base image — returns 202 { jobId }. Optional body { force?, agentSettings? } (agentSettings is { "<agent>": { "<key>": string | boolean } }— see agent settings). Progress streams overGET /jobs/{id}/logs(same as create). Prechecks the host (docker daemon; hetznerssh/scp; credentials present) and reuses an in-flight bake for the same provider. Bakes are serialized per provider, so a provider bakes one image at a time while different providers bake in parallel (each remote-docker host is its own lane too). |

Agents

Approvals

Jobs

Custody

Custody holds agent credentials, .env/secret files, and per-box SSH private keys — the highest-value target in the whole API. It follows a two-tier contract: list / PUT / DELETE authorize with the hub API key and their responses are metadata only (paths, hashes, sizes, mtimes — never a value); the byte-read GET /custody/{path} is the only route that returns a value, and it is elevated — on a control box it additionally requires the admin token, so the widely-distributed API key alone can never read a secret.

System

The box view is provider-agnostic: { id, projectId, repo, branch, task, agent, status, createdAt, lastActivity, host, commits, filesTouched, error, displayName, webUrl, vncUrl }, where status is one of running | paused | stopped | creating | error. Boxes still being created (and failed creates) appear as synthetic creating/error entries with a job: id until the real box lands. A failed create can be cleared with POST /boxes/{id}/destroy (dismiss). On the local host topology each box also carries raw host-side fields for native clients (the tray app): state (the raw provider state — absent on synthetic entries, which is how a client tells a failed create from a running box whose agent errored), name, provider, projectRoot, projectIndex, vncEnabled, gitWorktrees, shellCount, and agentStatus — every agent reporting in the box, keyed by agent id, each { state, sessionTitle? } where state is one of working | idle | waiting | end-plan | question | compacting | error | unknown. The older named fields (claudeSessionTitle, codexSessionTitle, opencodeSessionTitle, claudeActivity, codexActivity, opencodeActivity) are still sent, but they are a projection of agentStatus over the three built-in agents — read agentStatus if you want to see any other agent. vncEnabled — not vncUrl — is the "this box has a desktop" bit: vncUrl is only ever set for boxes with a stable URL (docker, hetzner), and is null on daytona/vercel/e2b because their signed preview URLs expire. Gate the affordance on vncEnabled and fetch the URL from GET /boxes/{id}/vnc when the user clicks. Cloud boxes also carry the fields needed to reconstruct or adopt them from the payload alone (all undefined for docker/synthetic rows): sandboxId, originUrl, publicHost, image, webPort, previewUrls, lastAgent, and topology.

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": "..." }

The body takes either a projectId (a registered project on the hub's machine — built from its local checkout) or a repoUrl (an origin the hub clones VPS-side when there is no local checkout, e.g. on a control box). Same route, same 202 { jobId } — the hub picks the build path internally. Optional fields mirror the CLI's agentbox create flags: agent, provider, name, prompt, agentArgs, fromBranch, and an opts object for box-shaping knobs (image, snapshot, size, location, envFiles, carry, …).

A box being built shows up in GET /boxes with status: "creating" right away, then flips to running once the container is up. GET /jobs lists every create job (the unified queue view behind agentbox queue list / hub jobs); GET /jobs/{id} is one job's status (queued/running/done/failed, plus boxId and, on failure, error).

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.