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, 500 internal).

Two more codes also answer 409, and both carry a details object naming the machine the call has to run on: wrong_host (a manager op sent to a hub that is not the machine running the session) and manager_unreachable (a message the answering hub cannot type). Branch on error.code, not on the status:

{
  "error": {
    "code": "wrong_host",
    "message": "manager 4f2a…c1 runs on marcos-mbp, not on control-box; resume it there",
    "details": { "host": "marcos-mbp" }
  }
}

When details.host is your own hostname, retry the identical call against the hub on your machine (agentbox hub target --json --local). A refusal about a workspace rather than one manager — managers/start, managers/sessions — also carries details.hosts, every machine with a checkout of it, because a workspace mapped from several machines has no single right answer; retry when your hostname is in that list.

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

Workspaces

A workspace groups one or more projects, owning a task list and its manager sessions. It is machine-independent: projects are repos, and hosts maps every machine that has a checkout to its folders ({ "<hostname>": { root, projectRoots, seenAt } }), so a hub that never cloned a repo — a control box — still joins the boxes built from it to the right workspace. root on the payload is the reading hub's own folder and is absent when it has none. You rarely register one by hand: detecting a manager session in a folder no workspace contains creates one there. Host state: a hosted hub holds none, so its listing is empty rather than an error.

The client scans, the hub records: the folders are on the caller's machine and the hub never stats them.

GET /projects gains workspaceId on every project a workspace lists, and GET /boxes gains tasks ({ total, done, current }) on every box tasks are assigned to and managerId on every box a manager session created. All are optional: absent means "no data" — never "zero" — and all are absent on a hosted hub. A box created from the web UI or the tray has no managerId. GET /boxes also gains pr ({ repo, number, url?, state }, state one of open, ready, merged, closed) on every box with a known pull request: matched in its workspace timeline by box id, else by the box's branch against the PR's head branch. When several match, an open PR wins over a merged or closed one, then the newest. state is the last GitHub sync's when this hub has one, else the log's.

Tasks

Units of work, ordered by priority (list order is the priority) and assigned to boxes. Many tasks to one box is the normal case: that is how a manager keeps tasks touching the same files on one branch. Assignments are healed on every read — a task assigned at create time moves from the job id to the box id once the worker records it, and a task whose box is gone returns to the backlog with its status untouched.

Managers

A manager is a host agent session that creates and watches boxes — many per workspace, of three kinds. external is a claude or codex session in someone's own terminal: the CLI registers it the first time it runs inside it (POST /managers/detect), and the hub only observes it. pty is one a hub started on an AgentBox pty host on its own machine — one process holding the agent's terminal, with no multiplexer in between, so every client gets the agent's raw bytes and several can attach at once. tmux is the same thing on the older carrier, used where the optional terminal prebuild is missing. A running pty manager carries ptyAttach (an absolute argv, its socket and the protocol version), so an embedding client needs nothing on its own PATH.

A manager runs on one machine; its record lives with the workspace. With a control box configured those are different machines: the session, its tmux server and its transcript are on your PC, while the record, its notes and its timeline are on the box. host is the machine it runs on and hostIsHub says whether the hub that answered IS that machine. Every process op — start, resume, attach, stop, sessions, message — only works there; anywhere else it answers 409 with code wrong_host and details.host, and the client retries against the hub on that machine (its own local hub, when details.host is its own hostname — agentbox hub target --json --local points at it). The PC hub keeps that record current by reporting to POST /managers/{id}/heartbeat, and tells it about a box it built for that manager with POST /managers/{id}/attach-box. Registering, reporting and attaching a box are the only manager writes a hub accepts from another host.

status is derived, never stored: on the machine that runs it, whether the session host answers for a pty manager, the tmux session for a tmux one, and for an external one its pid, else "seen in the last 30 minutes". A claude session that Claude Code hosts in its background daemon (claude --bg, listed by claude agents) is running while the daemon runs it, whatever is attached. On any other hub the row comes from the last heartbeat, and falls back to the last-seen window once three of them are missed. An external session that has ended can be resumed, after which it is hub-run.

Claude's daemon hands the environment of the client that started it to every session it hosts, so a detect's managerId ($AGENTBOX_MANAGER) is believed only for a manager in the same folder that has no session yet or is hub-run and running. For a pty manager it is believed only when the detect also carries runId ($AGENTBOX_MANAGER_RUN), which its session host minted — proof the leaked variable cannot supply. A detect that names the AgentBox tmux session it runs in (tmuxSession) records the manager as run from it, when that session exists on the hub's machine and started in the detect's folder.

A manager: { id, workspaceId, workspaceName, agent, kind, host, hostIsHub, status, resumable, resumeBlockedBy?, cwd, sessionId?, title?, pid?, pidStartedAt?, tmuxSession?, tmuxPane?, attachCommand?, boxIds, boxJobIds, taskCounts, createdAt, lastSeenAt, startedAt?, stoppedAt?, lastExit?, background?, terminalSession? }. attachCommand is present for a running hub-run manager, and for a background session while the hub's attach session for it is up. background ({ id, status?, state?, name? }) marks a claude session running detached in Claude's daemon — no AgentBox tmux session starts in its folder and no claude attach client shows it — which POST /managers/{id}/attach opens. terminalSession names the one unclaimed AgentBox tmux session that started in a running external manager's folder (for example one from before managers were detected): a client may offer to open it, but nothing ties it to the manager for sure. resumable says whether a resume would be accepted at all (a client disables Resume on false), and resumeBlockedBy says why not — running, no-session or unsupported-agent, absent when resumable is true. It says nothing about WHERE: that is host/hostIsHub. title is the session's first user turn when the machine running it can read the agent's store.

| Method + path | Description | | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | | GET /managers | Every manager, running first then most recently seen: { managers }. Filter with ?workspaceId= and ?status=running\|stopped. | | POST /managers/detect | { agent, sessionId, cwd, pid?, host?, managerId?, tmuxPane?, tmuxSession?, boxId? \| boxJobId?, projects?, home? } — register the session a CLI call came from, matched by (agent, sessionId) so repeating it refreshes one record. managerId (the caller's $AGENTBOX_MANAGER) joins it to the hub-run manager it runs inside. When no workspace on host contains cwd, one is created there from the caller's projects scan (same shape as POST /workspaces) — except at /, the caller's home, or any folder above it, which answer 400 (register the project folder with POST /workspaces instead). The folder is never stat'd: it is on the caller's machine. boxId/boxJobId attaches a box the session just made. Returns { manager, workspace }, 201 when either was created. | | GET /managers/{id} | One manager. | | DELETE /managers/{id} | Forget it. Its boxes and tasks are untouched. 409 while it runs, unless ?force=1 (the process, if any, is left alone). | | POST /managers/{id}/stop | End a hub-run manager's session (its pty host runs the kill ladder, or its tmux session is killed); idempotent, and the record is kept for a resume. An external manager is your own process, which the hub never signals: 409 while it runs. For a claude manager whose session runs in Claude's background daemon only the hub's attach session closes: the session keeps running, and the answer adds notice saying so. | | POST /managers/{id}/pin | { pinned } — keep a hub-run session alive with nothing attached to it, or stop doing so. Without a pin, a session a client holds a lease on is stopped once that client stays away past the grace window (manager.leaseGraceSeconds), so quitting the app that opened it ends its terminals while a relaunch inside the window keeps them. Written to the record and pushed to the live session host. 409 for an external manager: the hub never keeps your own terminal process alive. | | POST /managers/{id}/attach | For a manager with background (a detached Claude Code background session): start, or reuse, the tmux session agentbox-manager-<id> running claude attach <background.id> in its folder, and answer the manager with attachCommand. Its kind and session are unchanged, and it stays running after that tmux session ends. 409 without a running background session, or when an AgentBox tmux session in its folder or a claude attach client may already show it; 503 without tmux. | | POST /managers/{id}/resume | Reopen the session in this hub's tmux (claude --resume <id> / codex resume <id>, in the manager's cwd). 409 while the session still runs anywhere, for a manager with no session id, and for an agent whose sessions cannot be resumed; 409 wrong_host when host is not this machine (its transcript is not here); 503 without tmux. | | POST /managers/{id}/heartbeat | { status, sessionId?, title?, turn?, prompt?, lastExit?, background?, terminalSession?, tmuxSession? } — what the machine running the manager sees right now, sent every 30 s and after each start, resume, stop or attach. Drives that manager's row here until three intervals pass with no heartbeat. 409 wrong_host for a record whose host is this hub's own: there the process is readable, and a report nothing can check must not override it. | | | POST /managers/{id}/attach-box | { boxId } or { boxJobId } — the hub that BUILT a box says which manager it belongs to. Usually that hub is this one and nothing travels; with a control box configured and hub.mode=local the box is built on the user's own machine while the record lives here. Appends one id to the manager's list and can neither move nor remove anything, which is why — unlike every other patch — it is accepted from another host. | | POST /managers/{id}/notes | { text, kind? } (note | replan | plan) — record why the manager did something on the workspace timeline, stamped with its current turn and that turn's prompt when its transcript is on the hub's disk. 201 with the event. | | POST /managers/{id}/message | { text, prNumber?, repo? } — type a message into the manager's session and submit it: a running hub-run manager's tmux session, a running external manager's tmux pane (recorded at detect, on the hub's machine only), or a stopped manager resumed in the hub's tmux with the text as its prompt. Answers { delivered: session \| pane \| resumed, manager, event }. A running external manager outside tmux is 409 with code manager_unreachable: offer the text to paste instead. So is a manager on another machine, with details.host naming it — retry there. prNumber ties the message to a PR, so its merge shows approvedByYou; add repo (owner/name) when the workspace spans several repos, since a bare number is matched only when one repo in the log has it. | | GET /workspaces/{id}/managers | The workspace's managers: { managers }. | | POST /workspaces/{id}/managers/register | { id?, agent, kind: "tmux", host, cwd, tmuxSession, sessionId?, argv? } — record a manager session another machine just opened, where the workspace lives. With an id that manager moves onto the new session (manager.resumed); without one a manager is minted (manager.started). This and the heartbeat are the only manager writes accepted from another host. argv is recorded, never executed here. | | POST /workspaces/{id}/managers/start | { agent, sessionId?, restart? } — start a manager in the workspace folder, in a tmux session this hub owns. 409 wrong_host when the workspace has no folder on this machine. agent is one this hub knows (GET /agents, plugin agents included) that is installed here and has a session to attach to — a service agent such as openclaw is a daemon, so it is refused. There is deliberately no free-form argv: this runs on the hub host, not in a box, and sessionId is constrained to an id shape for the same reason. sessionId resumes a session (claude and codex only); one a manager already holds resumes that manager (409 while it runs, unless restart and it is hub-run). 503 without tmux. | | GET /workspaces/{id}/managers/sessions | Sessions in that folder a manager could resume, read from the agent's own store (?agent=, default claude): { agent, supported, sessions: [{ id, title, updatedAt }] }. supported: false is not an error — that agent's session format is not one the hub can resume. 409 wrong_host when the workspace has no folder on this machine: the sessions are files in it. |

Timeline

What happened in a workspace, from an append-only log every mutation writes to — task, manager, box, push and pull-request events — plus the rows that are true right now.

An event is { id, at, type, actor, managerId?, turn?, prompt?, boxId?, boxName?, agent?, branch?, base?, projectId?, taskIds?, task?, pr?, text?, noteKind?, boxRunning?, additions?, deletions?, key? }. actor is human, manager, box, hub or github. type is one of task.created | status | assigned | unassigned | removed, manager.joined | started | resumed | stopped | note | message, box.created | ready | failed | started | stopped | destroyed | branch, git.push, and pr.opened | ready | merged | closed. base on box.created is the branch the box forked from: the create's fromBranch, else the branch the project's checkout was on (absent on a detached HEAD). box.branch is written when a git/checkout or git/branch moves the box onto another branch, with branch the branch it is now on and base the one it left; a checkout with args (paths) or one that leaves HEAD detached writes none. box.ready carries base only when the create named a fromBranch. A git.push carries additions/deletions from the old tip to the new one, or from the merge base with the default branch for a first push. They are read from the host repo when the hub holds that folder, and measured inside the box when it does not — a control box has no checkout of anything. taskIds is captured when the event is written, and pr is { repo, number, title, url, base, head, additions?, deletions?, checks?, mergeState?, autoMerge?, mergedBy? }.

An item is an event, or type: plan (count, taskIds, turn, prompt) when a manager created 3 or more tasks in one turn within 10 minutes. A pr.merged preceded by a message about that PR carries approvedByYou. live rows are task.in_progress — a box working a task, with filesChanged, additions and deletions of its uncommitted diff while it runs (left off a read when the box takes over 3 s to answer) — and pr.ready, with awaiting and, once a message about it was sent, approved. After a hub restart, a ready PR stays out of live and summary.awaiting until a GitHub sync of the workspace confirms it.

Items and live rows that name a branch carry branchUrl, the branch on the web (https://github.com/acme/storefront-web/tree/feat/checkout-copy, each segment URL-encoded). A PR row's branch is its pr.head. The repo comes from pr.url, else a repo the GitHub sync resolved, else the row's project or box as the last sync cached it; without one of those the field is absent. A read never runs gh for it, so a row can gain the link on the read after the first sync.

Lanes. Every item and live row carries lane: { id, kind, from?, into?, branch?, open? }, for drawing the timeline as a branch graph. id is box:<boxId> for a box's rows (a box.created joins its box through its create job), branch:<head> for a pull request no box is known to own, and trunk for everything else: tasks without a box, managers, notes, plans. from is on a lane's oldest row: the box lane that last carried its base (a PR lane uses pr.base), else trunk. into is on pr.merged: the box lane carrying pr.base, else trunk; the row itself stays on its own lane. branch is on a lane's first row and wherever its branch changes. open is on live rows and on a lane's newest item when the lane goes on: its box has a live row, or still exists and is running or has not merged its work. Lanes are assigned over the whole log before before and limit apply, so a lane keeps its id on every page, and a page that does not reach a lane's fork has no from for it.

Who did it. The CLI sends X-AgentBox-Session: <agent>:<sessionId> from inside a Claude Code or Codex session; the hub resolves it to a registered manager and stamps its managerId, turn and that turn's prompt. Without the header (the tray, the web UI, a script) the actor is human, and so is a manager of another workspace: on a box or manager route the session is resolved in that box's or manager's own workspace. Alongside it the CLI sends X-AgentBox-Session-Turn: <turn>[;<prompt>] (the prompt percent-encoded), read from the transcript on ITS machine — a control box holds the manager record but not the transcript. It is used only when the resolved manager's session is on another host; where the hub can read the transcript it does, and ignores the header. note (up to 2000 characters) on a task add, update, assign or reorder body records a manager.note next to the change.

Pull requests come from two places that share one dedupe key: the in-box gh shim after an exit-0 gh pr create or gh pr merge, and a GitHub sync — gh pr list on the GitHub repos the workspace's projects name — that a read starts in the background when the last one is over a minute old. Every gh call it makes addresses the repo by name and runs in no folder, so a hub with no checkout syncs exactly like one that has them; a project with no repoUrl has nothing to poll. It keeps PRs on a branch the workspace worked on, or opened by the gh user. github is ok, syncing or unavailable (no gh, not logged in, or no GitHub repo); rows a sync adds fire the usual /api/events change.

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, persistent (an always-on box — never auto-paused, never idle-lapsed, skipped by prune, restarted by the relay's boot reconcile; see persistent boxes. POST /boxes/{id}/destroy has no guard on it, unlike agentbox destroy -y, so a client that offers destroy should confirm on this field), 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, …).

Questions a create has to ask first

Some creates need a human decision before anything is provisioned: whether to copy the host files a project's carry: block names, or whether to seed a service agent with a host login. POST /projects/{id}/create-preflight returns those questions; you render them, and send the answers back with the create.

curl -X POST -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"agent":"claude","provider":"docker"}' \
  http://127.0.0.1:8787/api/v1/projects/<id>/create-preflight
# -> { "prompts": [ { "id": "carry:98310458c334", "topic": "carry", "kind": "select",
#                     "title": "Copy 15 host entries into the box?",
#                     "choices": [ ... ], "detail": { "type": "file-table", ... },
#                     "required": true, "fallback": { "value": "cancel", ... } } ],
#      "unavailable": [] }

curl -X POST -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"projectId":"<id>","agent":"claude","opts":{"promptAnswers":[
        {"id":"carry:98310458c334","value":"approve"}]}}' \
  http://127.0.0.1:8787/api/v1/boxes

Once a project's carry: list is approved it stops being asked at all — the approval is remembered host-side (see carry), so the preflight returns no carry prompt until the list changes. Send carryAsk: true to show it again for a granted list; answering Skip or Cancel on the create that follows withdraws the standing approval.

A client that already holds the answer can skip the two-step conversation and post the decision instead of an answer list: opts.carryYes approves the block, opts.carrySkip declines it. Both are per-run and leave no standing grant, which makes them the API twins of the CLI's --carry-yes and --carry skip — and the way a scripted create gets through with no terminal to prompt at.

A PromptRequest has two halves. The generic one — kind (confirm / select / text), title, body, choices — is enough to render and answer any prompt, including a topic your client has never seen, so the hub can add a question without breaking you. detail is the optional half a client may draw richly (file-table, credential); every variant carries a plain summary, so render that for one you do not recognise.

The list comes from running the real gates, so it can never differ from what the create asks. Skipping the endpoint is allowed — every prompt has a fallback — except for one marked required (carry:, whose silent answer would move host secrets): a create that leaves that unanswered is refused, not defaulted. Ids are content-addressed over the question, so an answer collected before the project's agentbox.yaml changed no longer matches and is refused too.

unavailable names each gate this hub cannot run and why. A control box has no local checkout, so it can read neither your agentbox.yaml nor your host logins; it says so rather than returning an empty list that looks like "nothing to ask".

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.