docs(hub): document the /api/v1 end state + complete the OpenAPI (thin CLI Step 14)

[madarco]

What

Step 14 (final) of the one-path plan: make the docs and the OpenAPI spec describe the consolidated end state accurately — including the deliberate exceptions, not an overstated "everything goes through /api/v1".

OpenAPI (apps/hub/app/(dashboard)/api/v1/lib/openapi.ts)

Documented the 8 routes that shipped without an entry: GET /boxes/:id/agent, POST /boxes/:id/checkpoint, GET /boxes/:id/logs, POST /boxes/:id/rename, GET|DELETE /checkpoints, POST /prune, GET /jobs, POST /jobs/:id/login-code. Added Checkpoints/Fleet tags + response schemas (CheckpointCreateResult/CheckpointListing/CheckpointRemoveResult/PruneResult/JobListItem/AgentState), enriched Job (error/provider/name/agent/createdAt/login) and Box (the Step-3 adoption fields: sandboxId/originUrl/publicHost/image/webPort/previewUrls/lastAgent/topology/shellCount). rename/open/open-targets/hosts were already present.

New guard test apps/hub/test/openapi-coverage.test.ts diffs the App-Router route files against the document both ways (fails on an undocumented route AND a documented path with no route file) — the "verification checklist" the openapi.ts header always claimed but never had.

Docs

• api.mdx — the 9 endpoints + Checkpoints/Fleet groups, plus the accurate "one path, IO plane excepted" framing.
• deployed-hub.mdx — a new "What still needs your laptop" section (direct IO plane; local adoption; secrets.env on both machines; the launcher-foreground-create exception; a no-TTL parked-approval callout), and corrected the stale ls merge / on hub / orphan description to the single-/api/v1/boxes listing.
• configuration.mdx — documented git.pushMode (was missing).
• architecture.md — new "End state: one path through /api/v1" subsection with the four deliberate exceptions.
• create-and-checkpoints.md / cloud-providers.md / hub-testing.md — routing notes (create/checkpoint/prune moved behind the API), custody/adoption §4b, "why both modes".
• CLAUDE.md — fixed the stale claim: /api/events accepts Bearer (same gate as /api/v1 in proxy.ts); the cookie is an additional same-origin credential, not a replacement.
• cli.mdx left as-is — already accurate and appropriately qualified.

Why

The plan is titled "one path" and the temptation is to declare it fully achieved. It is very close, but four things are deliberately not on /api/v1, and the docs now say so plainly: the direct IO plane (shell/attach/cp/download/code/open/url/screen) stays laptop-side — so local adoption stays and secrets.env stays on both machines; the three agent launchers' local foreground create still builds inline (route-create.ts survives); one custody /admin byte-read fallback is allowlisted; the localhost hub binds 0.0.0.0 so the custody byte-read is loopback peer-gated; and parked approvals have no TTL.

Tray — documented follow-up

../agentbox-tray is a host-side sibling repo and is not reachable from inside this AgentBox (/workspace's parent has no agentbox-tray). Per the step brief, the tray change is left as a documented follow-up (recorded in the plan doc): its Swift Box model (HubAPIBoxSource) should decode the enriched Step-3 fields now present on GET /api/v1/boxes. The hub API contract it speaks is otherwise unchanged.

How verified (e2e)

• Built the standalone hub, restarted it, and the served GET /api/v1/openapi.json lists all 37 routes with a perfect bijection to the route files (0 missing, 0 stale) — the acceptance diff, run against the running server, not eyeballed.
• GET /api/v1/docs renders (Scalar loads the spec).
• pnpm --filter @agentbox/web build green (docs compile).
• pnpm --filter @agentbox/hub test (122) + typecheck green; prettier + eslint clean on the touched files.

https://claude.ai/code/session_01P5tWZxdr38EUaF9tXFUFXB

---

Note

Low Risk
Documentation, OpenAPI metadata, and a coverage test only—no application logic changes in the diff.

Overview
Documents the thin-CLI “one path through /api/v1” end state and brings the hand-authored OpenAPI spec in line with what actually ships, without changing hub runtime behavior.

The openapi.ts update adds the eight routes that were missing from the spec (rename, agent state, logs, per-box checkpoint, global checkpoints, prune, job list, login-code), new Checkpoints / Fleet tags and response schemas, and richer Box / Job fields for adoption and create jobs. apps/hub/test/openapi-coverage.test.ts diffs App Router route.ts files against documented paths in both directions so new routes can’t land undocumented and stale paths fail CI.

Public and internal docs (api.mdx, deployed-hub.mdx, architecture.md, create-and-checkpoints.md, cloud-providers.md, hub-testing.md, etc.) now state that box/fleet ops go through /api/v1, call out what still runs on the laptop (direct IO, adoption, secrets.env, launcher foreground create, custody/approval caveats), and fix outdated control-box listing/auth wording. CLAUDE.md corrects hub auth: /api/events accepts Bearer like /api/v1; the cookie is an extra same-origin credential. configuration.mdx adds git.pushMode and is mostly table/formatting cleanup.

The macOS tray sibling repo is explicitly left as a follow-up (decode enriched Box fields from GET /api/v1/boxes).

^{Reviewed by Cursor Bugbot for commit 3c1786e. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agentbox-web	Ready	Preview	Jul 30, 2026 7:21pm

[madarco]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 3c1786e. Configure here.}