System overview
Edge, control plane, data plane and the metering pipeline — how a request becomes a running agent action and an invoice line.
The platform is three layers with one hard rule between them: the control plane decides, the data plane executes, and the control plane is never on the data path of a running agent action.
Once a session is running, the agent's exec stream, browser traffic and desktop frames flow
between the client and the data plane directly. If the entire control plane went down, running
sessions would keep working; only creating, mutating and billing new ones would stop. That property
is the reason the split exists.
The whole system
Layer responsibilities
Edge
Anycast TLS termination, WAF, DDoS absorption, and routing of each request to the nearest region that can serve it. Control calls go to the nearest control-plane cell; data calls go to the region that holds the session, since a session is pinned to the region it was created in.
The edge also serves *.run.workspaces.build, the per-session exposed-port domain, which maps a
hostname to a session and port without going through the API.
Control plane
Stateful, authoritative, and off the hot path. Every service here is regionally replicated with a globally consistent metadata store for anything that must be unique across regions — organization identity, API keys, templates, invoices.
| Service | Owns |
|---|---|
api-gateway | Authentication, authorization, rate limits, idempotency, request logging |
identity | Organizations, projects, members, roles, API keys, end-user tokens |
admission | Quota checks, spend caps, concurrency ceilings — the right to create |
placer | Where a session runs: region, zone, host, pool |
session-mgr | The session state machine and the reconciler that drives reality toward it |
policy | Compiling and distributing egress, CLI, tool and secret policy |
image-svc | Template registry, build pipeline, regional layer distribution |
pool-mgr | Warm pool target sizes and refill, per tier, template, size and zone |
metering | Usage event ingest, dedupe, minute aggregation |
billing | Rating, rollups, credits, invoices, dunning |
audit | Append-only, tamper-evident record of every privileged action |
webhooks | Signed delivery with retry and replay |
Detail: control plane.
Data plane
Where agent actions actually execute. Regional, horizontally scaled, and designed to keep running when the control plane is unreachable.
| Component | Owns |
|---|---|
session-gateway | Client-facing streams: exec SSE, PTY, CDP, desktop WebRTC |
wbnode | The per-host daemon: start, supervise, meter, tear down every runtime |
| Tier runtimes | Tool executors, gVisor sandboxes, microVMs, full VMs |
egress-proxy | The mandatory outbound chokepoint, where network policy is enforced |
| Storage | NVMe scratch, networked volumes, snapshot object store |
edge-router | Inbound routing for exposed session ports |
Detail: data plane.
Request lifecycle, end to end
A POST /sessions for a tier 2 session, step by step.
provisioning state while the data plane is still starting. Each row links to its detail page.Callers that do not want to poll have two alternatives to waiting for running: await the
session.running webhook, or simply start streaming. The gateway holds an exec request open until
the session is ready, so the round trip spent confirming readiness is avoidable entirely.
Failure isolation
| What fails | What stops | What keeps working |
|---|---|---|
| One host | Sessions on it (evicted, webhook sent) | Everything else; pool refills elsewhere |
| One zone | New placements in that zone | Other zones; existing sessions elsewhere |
placer | New session creation | Every running session, every exec |
metering | Usage visibility is delayed | Execution; events buffer at the node for 24 h |
billing | Invoicing, spend-cap enforcement | Execution; caps fail open with alerting |
| Whole control plane | Create, mutate, bill | Running sessions, exec, streams, egress |
| Whole region | That region entirely | Other regions; sessions do not fail over by design |
A session is a live machine with live state. Transparent cross-region migration would mean moving memory and disk across a WAN while the agent runs, which is neither fast nor safe. Instead a session dies with its region, the failure is surfaced through the API and a webhook, and the caller decides whether to recreate it — from a snapshot if one exists.
Design principles
The control plane may be slow; the data plane may not. Anything that must happen per agent action lives in the data plane. Anything that happens per session lives in the control plane.
Everything is reconciled, nothing is commanded. session-mgr writes desired state. A reconciler
drives actual state toward it and is safe to re-run. There is no imperative "create this VM" RPC
whose loss leaks a VM.
Metering is at the source. Usage is emitted by the component that owns the resource — wbnode
for compute, egress-proxy for bandwidth, storage for capacity. No service estimates another
service's usage.
Policy is compiled once, enforced continuously. The control plane turns a policy into a concrete artifact at admission. The data plane enforces that artifact without calling back.
Tier is a placement class. Tiers do not merely differ in configuration; they land on different host pools with different oversubscription ratios, kernels and network topologies.
Where to go next
- Control plane — services, stores, consistency model
- Data plane — node agent, runtimes, gateway
- Scheduler and warm pools — how start latency is held
- Session lifecycle — states, transitions, timeouts
- Observability — what is measured and what customers see