Control plane

July 1, 2026 · View on GitHub

Rename in flight: "control-plane" is being renamed to Control Hub (agentbox hub) — see control-plane-roadmap.md (milestone M1). This backlog stays as the historical record of what shipped under the old name; the code/CLI/config still say control-plane until the M1 rename lands.

Status of the control plane: a portable service that holds the centralized concerns for boxes — git credentials (GitHub-App token leasing), permission state, the box registry/events — so boxes keep pushing / opening PRs while the user's laptop is off. Maintained live during implementation (per project convention).

Plan of record: ~/.claude/plans/design-a-new-approach-synthetic-bee.md.

The pivot (vs the first attempt)

The first attempt ran the relay on a dedicated always-on VPS with a long-lived fine-grained PAT. It worked but (1) billed a never-sleeping VPS for something mostly idle, and (2) pushed by reaching back into the box over the cloud SDK to make + download a git bundle — the part that resists a stateless/serverless deployment.

The current design is one portable control plane — the @agentbox/relay core wrapped as a single Next.js + Postgres app (apps/control-plane). The same code deploys to Vercel (managed) or self-hosts on a VPS (Postgres + next start, via docker-compose). It is stateless per request (all state in Postgres) and does no host execution. Git auth is GitHub-App leasing: it mints 1-hour, single-repo installation tokens and leases them to boxes, which push to GitHub directly — no bundle transfer, no SDK reach-back. That dedicated always-on VPS (with its stored PAT) is removed. The laptop loopback relay (agentbox-relay serve) is unchanged and shares the same core.

Architecture

cloud box  --(forwarder, https)-->  control plane (Next.js + Postgres)
   |  POST /events (per-box bearer)        |  Store (boxes/events/status/prompts)
   |  POST /rpc git.lease-token            |  GitHub App -> 1h repo-scoped token
   |  GET  /rpc/status/:id (poll)          |  /admin/* (admin bearer, fail-closed)
laptop CLI --(register/answer, admin bearer)
box --(push directly with leased token)--> GitHub

Store seam (packages/relay/src/store/) — every relay handler talks to an async Store. MemoryStore (laptop + tests, wraps the historical in-memory structures), PostgresStore (hosted plane). pg is lazy-imported + bundler- external, so the laptop relay/CLI carry no pg.
Poll-based approvals (permission.ts) — promptMode is block on the laptop (in-process wait, unchanged) and poll on the hosted plane (parks a prompt row; the box polls /rpc/status/:id; the approved action runs there).
GitHub-App leasing (github-app.ts, lease.ts) — git.lease-token gated like push (agentbox/* auto, else approval); repo resolved from the box's REGISTERED originUrl, never box params. In-box git push leases + pushes directly when AGENTBOX_GIT_LEASE=1 (token in the remote URL for the push only, scrubbed after).
Hosted-plane handler (core/handler.ts) — framework-agnostic handleRelayRequest(GenericRequest) -> RelayResponse; the Next.js app (apps/control-plane) is a thin Web-Request adapter over it. Rejects host-local RPCs (cp/download/checkpoint/docker git.push) — no host on the plane.

Phase status

Live validation (2026-06-16)

The plane is deployed and validated on real infrastructure:

Deploy: apps/control-plane on Vercel (madarcos-projects/agentbox-control-plane, Root Directory apps/control-plane, monorepo built via turbo) + Neon Postgres (provisioned non-interactively via vercel integration add neon). Public URL agentbox-control-plane-two.vercel.app.
Verified live: /healthz (tables auto-migrated on Neon), fail-closed admin gate (401/200), register-box + /events persisted to Neon.
Leasing live: git.lease-token minted a real 1-hour GitHub-App installation token for madarco/agentbox-test-repo (App agentbox-control-plane, installed on the repo) with the authed remote URL.
Box-creation loop live (origin-clone, Hetzner): a Hetzner cx23 provisioned via cloud-init cloned agentbox-test-repo into /workspace using a plane-leased token (origin scrubbed back to the bare URL afterward), then was destroyed.
Full worker loop live (queue → worker → box): POST /remote/boxes enqueued a job on Neon (queued); agentbox control-plane worker --once --store <neon> atomically claimed it (claimedBy/startedAt), leased a 1h App token for madarco/agentbox-test-repo, git cloned it locally, scrubbed the remote, ran provider.create() (seeded /workspace with the repo content), and marked the job done with result.boxId + finishedAt. Proves enqueue → atomic claim → lease → clone → provider.create() → completion end to end against the live Vercel+Neon plane. (Run with docker as a no-cost local target; see the Phase 5 docker caveat — the box was destroyed afterward.)
Dashboard live: the token-gated dashboard deployed to the same Vercel plane (/ serves the admin-token form, /healthz + /admin/registry still answer 200/401) — the page and the /[...path] API route coexist in the serverless env.
Hetzner deploy path live (2026-06-16): deployControlPlaneToHetzner ran end to end against real Hetzner — firewall (:22 host-only, :80/:443 open), cx23 VPS, cloud-init (Docker install + public-repo clone), secret .env + Caddy compose overlay scp'd, docker compose pulled postgres+caddy and invoked the app build. It exposed a pre-existing self-host image build bug (Vercel was unaffected — turbo there built deps in order): the apps/control-plane/Dockerfile built the relay before its workspace deps emitted dist/. Fixed to build via turbo run build --filter=@agentbox/control-plane, and added a root .dockerignore (host node_modules was being copied in, breaking native-dep arch). A clean-context docker build now goes 6/6 turbo tasks + next build green. VPS + firewall destroyed after the run. Caveat: a full live green (Caddy + Let's Encrypt cert on <ip>.sslip.io + /healthz) needs the Dockerfile fix on origin first (the VPS clones the public repo at --ref); validated locally pending that push.
Git-backed Vercel deploy live (2026-06-16): control-plane setup --deploy vercel now builds the plane from GitHub via the Vercel REST API (no local upload), so it works from a global npm install. Live-validated: created a Git-connected project (madarco/agentbox, Root Directory apps/control-plane), auto-provisioned Neon, upserted the App env, and a gitSource production build of feat/control-box went READY at https://agentbox-control-plane.vercel.app — /healthz, the fail-closed admin gate, and the new /admin/app/repo-installed endpoint all answer. Ownership constraint: Vercel only connects a repo whose owner has the Vercel GitHub App; non-owners fork + --repo <fork> (Hetzner needs no ownership — it clones the public repo on the VPS). Replaced the old local-folder vercel deploy (monorepo-only, hit the Root-Directory bug).
Vercel deploy made ownership-free + boot-safe (2026-06-16): --deploy vercel is now tiered — if the deployer doesn't own --repo it auto-forks via gh and deploys the fork (github-fork.ts); if Vercel still can't connect (its GitHub App not installed on the account), it falls back to the Deploy Button (vercel.com/new/clone — clone + App install + Postgres in-browser) and then finishes via the API (upsert secrets + redeploy), so there's no manual paste. The control plane also boots with no secrets: lib/plane.ts answers /healthz before building deps (reporting configured:{db,app,admin}) and buildDeps no longer throws on a missing admin token; the handler returns a graceful 503 (not 500) for an unset admin token. Net: a bare deploy is reachable + never 500s, and the bare→set-secrets→redeploy sequence is always valid. (Hetzner stays ownership-free — it clones the public repo on the VPS.)

Security notes

Token blast radius: leased tokens are per-repo, minimal perms (contents+pull_requests write), 1h, never persisted (in-memory cache only). Compromise of one box yields at most a 1h single-repo token; the plane holds only the App private key.
Repo-scope != branch-scope: an installation token can write any branch in the repo. The lease gate auto-allows only agentbox/* (decided with the user); any other branch needs approval. Branch protection on protected branches is the real backstop.
Lease gate == push gate, and the repo is always re-derived from the registered origin, never box params.
Admin auth: the hosted plane gates /admin/* + /remote/* on a constant-time admin-bearer, fail-closed (never loopback).

Verify

Unit: pnpm --filter @agentbox/relay test (Memory conformance, poll-prompt, github-app, control-plane-handler). Postgres conformance: AGENTBOX_TEST_DATABASE_URL=... pnpm --filter @agentbox/relay test postgres-store against a disposable postgres:16.
Self-host: apps/control-plane -> docker compose up --build (or next start) with POSTGRES_URL + AGENTBOX_RELAY_ADMIN_TOKEN; curl /healthz, admin 401/200, register a box, git.lease-token.
Live App round-trip (pending a real GitHub App on a test repo): register a cloud box, push on agentbox/*, confirm via git ls-remote.