Skip to main content

Control-plane API

This is the alphaswarm_controller surface at manage.alpha-swarm.ai. It is deliberately separate from the public AlphaSwarm API; it owns workload lifecycle, the TerraformRuntime, provider adapters, the asctl unified control-plane surfaces (typed service objects, PromotionRequest gates, the unified deploy front door), and the workload_runs audit ledger.

THE single admin API contract of record​

The consolidated /manage/* surface is the single sanctioned admin API contract for AlphaSwarm infrastructure. Per ADR 026 — Unified infrastructure control plane, "the controller OpenAPI (docs/reference/manage-api/) is the admin API of record" and "the controller's /manage surface remains the single sanctioned mutating path" (reaffirming ADR 022 — Governed deployment control path and ADR 005 — Separated control plane).

The spec below is generated, not hand-written. The source of truth is the FastAPI app in alphaswarm_controller; the controller's scripts/export_manage_openapi.py introspects create_app().openapi(), filters it to the admin surface (/manage/* + /auth/* + /proxy/*), and emits a deterministic, sorted manage-openapi.json. A drift gate (tests/test_manage_openapi_export.py) fails the controller build if the committed spec diverges from the live app, so this reference can never silently fall out of date. The published copy lives at alphaswarm_docs/openapi/manage-openapi.json.

Consumers​

Every AlphaSwarm admin surface is a client of this one contract and its gates — there is no second admin API. Per ADR 026 §Decision.1 and ADR 023 — Ops console RBAC and auth:

  • Admin BFF — the browser backend-for-frontend brokers session auth and proxies operator actions straight through to /manage/*.
  • Ops console — remains observational; every mutation deep-links into a /manage/* capability rather than owning its own write path.
  • UI AdminConsole — the Next.js admin console (superseding the retiring Vite admin SPA) renders and drives the same endpoints.
  • CLI — alphaswarm-controller / asctl operator tooling calls the identical routes and step-up gates.

Because they share one contract, an endpoint added here is available to every consumer at once, and the propose → plan → review → approve → execute → halt/rollback → audit control loop is enforced uniformly.

Embedded mode is parity-only; the sidecar controller is canonical​

The monolith can run the management engine in-process (ALPHASWARM_MANAGEMENT_MODE=embedded, the historical single-image default) or delegate to the standalone controller (ALPHASWARM_MANAGEMENT_MODE=sidecar); see Concept: management engine → Deployment modes. The sidecar alphaswarm_controller is canonical: this generated spec is its surface. The embedded-mode routers are parity-only — they exist so a single-image deployment keeps working, and they import the SAME WorkloadRuntime, but they are not the contract of record. Where the two ever diverge, the sidecar controller wins, per ADR 005 and ADR 022. New admin capabilities are designed against this spec first.

Surface​

The generated contract carries the full consolidated admin surface, including:

  • /manage/deployments/* — list / rollback / preview / promote workload deployments (+ log streaming).
  • /manage/workloads/* — start / stop / scale / restart / exec / tail-logs / apply_config / rotate-secret and the halt kill-switch.
  • /manage/terraform/* — plan / apply / destroy / refresh through TerraformRuntime (AGENTS rules 42, 43).
  • /manage/builds/* — Kaniko/BuildKit in-cluster image builds + artifact promotion.
  • /manage/promotions/* — InfraPromotionRequest intake / approve / execute (the single approval substrate).
  • /manage/deploy/* — the asctl unified deploy front door (typed DeploymentIntent compilation).
  • /manage/service-objects/* — typed asctl service objects.
  • /manage/cells/*, /manage/tenants/* — cell registry + per-tenant provisioning.
  • /manage/topology/* — service URL resolution (AGENTS rule 47).
  • /manage/credentials/* — step-up-gated cloud-CLI temporary credential mint (metadata only; never returns the token).
  • /manage/estate/*, /manage/connections/*, and the observability / streaming / lakehouse / timeseries / data-plane read surfaces.
  • /auth/* — the identity broker (login / callback / refresh / me / stepup / device flow / m2m + agent-identity tokens).
  • /proxy/* — the connection-proxy mesh.

Private M2M and device transports (/internal/session-resources/*, /tunnel/*, /hosted-connections/*, /exec/*) are intentionally excluded from the admin contract.

Audit ledger​

Every workload action writes a workload_runs row BEFORE executing through the provider. See Concept: management engine for the full audit contract.

Authentication​

Same Auth0 / Entra IdP chain as the public API; access is restricted to the admin:cluster scope (engineering org) and the per-org admin:org scope (customer orgs). Cloudflare Access policies in front of manage.alpha-swarm.ai enforce the perimeter at the edge.