Desktop architecture

Desktop profiles share one trainer-facing API. The catalog driver_hint selects the substrate; the viewer mode selects how the browser connects.

Layer split

Piece	Responsibility
Sandboxes L3	Lifecycle, workspace checkpoint, signed `viewer.url`, HTTP/WS proxy, evidence
viewer_ui (L4)	Embeddable GUI; mode adapters (`novnc`, `guacamole`, `provider`)
Substrates	Actual OS + streamer (TigerVNC in pod, Guacamole to VM, vendor Mac stream)

Sandboxes does not ship the product UI — only the proxy and evidence routes.

Profile → substrate → viewer

Profile	`driver_hint`	Substrate	`viewer.mode`	Upstream
`desktop-ubuntu`	`k8s`	Kubernetes pod	`novnc`	websockify `:8080` in pod
`desktop-windows`	`ec2-vm`	Cloud VM	`guacamole`	Guacamole HTML + WebSocket tunnel
`desktop-macos`	`external`	External Mac	`provider`	Provider stream (reference: `aws-ec2-mac`)

ProfileRoutingBackend treats gce-vm, ec2-vm, and vm as the VM backend family.

Request flow

POST /sandbox/sandboxes/v1 with profile=desktop-* (async create for desktop).
Router reads catalog driver_hint → k8s / VM / external backend.
Backend start() provisions the substrate; viewer_endpoint() returns the private stream host:port.
Runtime waits until the stream port accepts TCP (skipped when CLOUD=fake).
GET …/{id} returns the viewer descriptor when status=running.
Browser opens viewer.url → sandboxes proxy → upstream streamer.

The browser never receives your API key — only the signed viewer URL.

Workspace durability

/workspace (or C:\workspace on Windows) is the durable path. On stop, workspace bytes checkpoint to object storage under the tenant/project prefix.

Hexagonal boundaries

Cloud SDKs (boto3, etc.) stay in provider adapters under infrastructure/external_desktop/providers/*. Application and domain layers import ports, not drivers.

Desktop sandboxes
Providers
Platform architecture
In-repo ADR: docs/sandbox/adr/0001-multi-os-desktop-sandboxes.md