Viewer API

Viewer descriptor, auth, stream paths, evidence uploads, and errors for desktop sandboxes.

Contract for desktop-* sandboxes after status=running. Lifecycle APIs use your API key; the browser uses only the signed viewer.url.

Lifecycle

curl -fsS -H "X-Api-Key: $SANDBOX_API_KEY" \
  "$SANDBOX_GATEWAY_URL/sandbox/sandboxes/v1/$SANDBOX_ID"

Viewer descriptor

Returned on GET …/{sandbox_id} when status=running and the stream is reachable:

Field	Type	Description
`url`	string	Gateway path to open the viewer (includes signed token)
`mode`	`novnc` \| `guacamole` \| `provider`	How `viewer_ui` should connect
`embed`	`iframe`	Recommended embed strategy
`input_enabled`	bool	`true` only when `status=running`
`resolution`	`[w, h]`	Canvas size hint (default 1920×1080)
`expires_at`	int	Unix epoch when the signed token in `url` expires

Profile	`mode`	Substrate
`desktop-ubuntu`	`novnc`	K8s pod
`desktop-windows`	`guacamole`	EC2 VM
`desktop-macos`	`provider`	External Mac

Auth

Trainer uses API key (or Keycloak Bearer / team token) for create/poll/destroy/remint.
viewer.url carries a short-lived viewer token (sid, tid, pid, exp).
Remint before expiry and on WebSocket disconnect / viewer Failed / 401: POST /sandbox/sandboxes/v1/{id}/viewer/token — replace iframe src. Day-0 handoff (in-repo): docs/sandbox/GENSTUDIO_DESKTOP_QUICKSTART.md.
GET …/viewer without a viewer token mints; with a token it proxies (does not remint).
Static assets and WebSocket reuse the cookie set on the entry page.
The browser never receives your platform API key.

What “stream” means

Live desktop pixels + input under the viewer URL (proxied WebSocket to websockify/VNC). Not a separate Gen Studio API. Lag is mostly this hop chain; token remint does not fix lag.

Stream paths

Mode	Proxy entry	WebSocket path
`novnc`	`/v1/{id}/viewer/vnc.html`	`/v1/{id}/viewer/websockify`
`guacamole`	same proxy	`/v1/{id}/viewer/websocket-tunnel`
`provider`	same proxy	provider-specific (proxied to `viewer_endpoint`)

Paths are under /sandbox/sandboxes/… on the gateway.

Evidence APIs

Accept viewer token (query or cookie) or API key:

Method	Path	Body
`POST`	`/v1/{id}/viewer/recordings`	`video/webm` or `video/mp4`
`POST`	`/v1/{id}/viewer/screenshots`	`image/png`
`POST`	`/v1/{id}/viewer/actions`	JSON action log
`POST`	`/v1/{id}/viewer/annotations`	ambiguity annotation
`POST`	`/v1/{id}/capture`	server-side screenshot (API key)
`GET`	`/v1/{id}/artifacts`	list stored artifacts

Workspace

Durable files: /workspace (Linux/macOS) or C:\workspace (Windows). Checkpointed on stop to object storage under the tenant/project prefix.

Errors

Status	Meaning
`409`	Sandbox not `running` — no viewer yet
`401`	Invalid or missing viewer token
`503`	Upstream stream not ready
`502`	Proxy cannot reach upstream (pod/VM/Mac)

Viewer API

On this page