Desktop sandboxes

Browser desktops on Linux pods, Windows VMs, and external Mac cloud — one API.

Create a desktop sandbox, wait until running, open viewer.url in a browser. One API covers three substrates: Kubernetes pod, cloud VM, and external Mac.

Quick start (Linux pod)

export SANDBOX_GATEWAY_URL="${SANDBOX_GATEWAY_URL:-http://localhost:8780}"

curl -fsS -H "X-Api-Key: $SANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile":"desktop-ubuntu"}' \
  "$SANDBOX_GATEWAY_URL/sandbox/sandboxes/v1"

Poll GET /sandbox/sandboxes/v1/{id} until status=running, then open viewer.url.

Curated desktop images (Template Builder)

List installable software, bake a content-addressed image, then boot trainers with the same image_ref pin:

# Discover curated apps (chrome, libreoffice, vlc, gimp, vscode, …)
curl -fsS -H "X-Api-Key: $SANDBOX_API_KEY" \
  "$SANDBOX_GATEWAY_URL/sandbox/v1/catalog?kind=desktop_app"

# OSWorld preset bundle (preferred over listing apps manually)
curl -fsS -H "X-Api-Key: $SANDBOX_API_KEY" \
  "$SANDBOX_GATEWAY_URL/sandbox/v1/catalog?kind=desktop_app_bundle"

# OSWorld-style full stack on desktop-ubuntu base
curl -fsS -H "X-Api-Key: $SANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile":"desktop-ubuntu","bundle":"osworld"}' \
  "$SANDBOX_GATEWAY_URL/sandbox/sandboxes/v1/images/build"

Embed the returned image_uri in a CTP task seed as sandbox.image_ref. Platform operators register new apps via GitOps (docs/sandbox/runbooks/add-desktop-app.md in the repo).

Guest compat and episode reset

desktop-ubuntu pods expose an in-pod OSWorld-compatible HTTP API on :5000 (/healthz, /screenshot, /execute, /run_python). It is not a gateway route — probe via POST /sandbox/sandboxes/v1/{id}/exec and curl http://127.0.0.1:5000/…. ide-ubuntu has no guest listener.

Between scored benchmark episodes, destroy the sandbox and recreate with the same image_ref (Daytona reset semantics). Repo runbook: docs/sandbox/runbooks/desktop-episode-reset.md.

Production verify: make verify-desktop-osworld (needs gateway URL + API key).

Profiles and substrates

Profile	Catalog `driver_hint`	Substrate	Viewer	Enabled by default?
`desktop-ubuntu`	`k8s`	GKE pod (TigerVNC + noVNC)	`novnc`	Yes
`ide-ubuntu`	`k8s`	GKE pod (OpenVSCode Server)	`openvscode`	Yes
`desktop-windows`	`ec2-vm`	EC2 VM + Guacamole	`guacamole`	No — enable after verify
`desktop-macos`	`external`	External Mac cloud (`aws-ec2-mac`)	`provider`	No — enable after verify

Routing is automatic: ProfileRoutingBackend reads driver_hint and selects the k8s, VM, or external backend. You always call the same Sandboxes API.

Dig deeper

Page	When you need it
Architecture	L3 vs viewer UI vs substrates
Cloud IDE + agents	`ide-ubuntu`, terminal agents, attach
Providers	AWS EC2 Mac + Windows Guacamole
Provider plugin	Third-party Mac/VM `kind`
Viewer API	Descriptor, auth, evidence
Viewer UI	Embedding the viewer
Operations	Deploy and verify

Non-GUI long-lived workspaces (exec/files, no browser): Long-lived sandboxes.

Platform overview of pods vs VMs: Architecture.