Architecture
Gateway, executors, queue, and substrates — pods, VMs, and external desktops.
How the platform is put together, and how a request moves through it. Use the component picture to see what exists; use the flow diagrams for order and hand-offs.
High-level components
| Band | What it is |
|---|---|
| Clients | Your apps and CLIs — HTTP only |
| Edge | Public gateway: auth, routing, /docs, OpenAPI |
| Executors | Harbor, Agent, CodeEdit, Sandboxes (long-lived + desktop) |
| Elasticity | Pub/Sub job queue + KEDA-scaled Harbor worker fleet |
| Control plane | Catalog (agents, languages, profiles), per-project concurrency quota |
| Substrates | Where isolation runs: pods, VMs, external Mac, optional Daytona |
Substrates (pods and VMs)
Callers never pick a machine type in the HTTP path. The catalog profile
carries a driver_hint; Sandboxes routes with ProfileRoutingBackend.
driver_hint | Substrate | Used by |
|---|---|---|
k8s | GKE / Kubernetes pod (often gVisor for trials; desktop Linux uses a standard runtime) | Harbor default, Agent default, sandboxes-default, desktop-ubuntu |
docker | Local/docker-style exec | CodeEdit default profile |
ec2-vm / gce-vm / vm | Cloud VM (Windows desktop today: EC2 + Guacamole) | desktop-windows |
external | Vendor Mac cloud (not a GKE pod) | desktop-macos → provider aws-ec2-mac |
daytona (request override) | Daytona environment via Harbor CLI | Optional Harbor sandbox field |
Desktop viewer modes follow the substrate:
| Profile | Substrate | viewer.mode |
|---|---|---|
desktop-ubuntu | K8s pod | novnc |
desktop-windows | EC2 VM | guacamole |
desktop-macos | External Mac | provider |
Deep dive: Desktop architecture.
How Harbor and Agent traffic flows
Harbor and Agent are asynchronous: 202 + job_id immediately; work runs on
the shared worker fleet (typically into a pod substrate).
Step by step:
- Gateway authenticates and routes to Harbor or Agent.
- Catalog check (Agent is always strict; Harbor depends on enforcement mode).
- Executor enqueues the job →
202+job_id. - KEDA scales workers from queue depth.
- Worker admits a per-project slot, obtains LLM Gateway credentials if needed (ADR 0020), runs the trial.
- You poll or follow SSE until terminal; artifacts land in object storage.
Over the concurrent cap: async jobs stay queued; sync calls get 429. See
Errors and limits.
How CodeEdit differs
Synchronous — one HTTP call waits for stdout/stderr. Claims a warm pool pod or creates one. Does not use the Harbor/Agent job queue.
How Sandboxes differ
Long-lived sessions (exec/files/checkpoint) and desktop GUIs share
POST /sandbox/sandboxes/v1. The profile decides the substrate:
- Default workspace profile
sandboxes-default→ K8s pod + PVC. - Desktop profiles return a signed
viewer.urlwhenstatus=running. - Browser never sees your API key — only the signed viewer URL.
Guides: Long-lived sandboxes, Desktop sandboxes.
How the developer docs differ
| Surface | Purpose |
|---|---|
/docs | This documentation |
/openapi/sandbox-platform.yaml | Published OpenAPI |
/sandbox/* | Product APIs |
/internal/swagger | Engineer Swagger (when enabled) |
Packages (platform engineers)
Import direction: HTTP shells → executor libraries → control plane → sandbox core → drivers.
| Area | Role |
|---|---|
| HTTP edge | Thin FastAPI services behind the gateway |
| Executor libraries | harbor_service, agent_service, sandboxes_service, … |
| Ports | Job queue, object store, credential plane, sandbox driver |
| Drivers / backends | K8s, ECS, VM desktop, external Mac providers |
L4 products use SandboxClient only.
In-repo: docs/layers/, docs/sandbox/HLD.md, docs/sandbox/desktop/.
Deployment topology
| Environment | Typical substrate mix | Role |
|---|---|---|
| Production / staging | GKE pods + (optional) AWS desktop VPC for Windows/Mac | Live API |
| Local | Docker Compose (make up) | Developer loop |