Desktop & computer use

Machines started from BMA’s desktop templates run a full desktop; the operating system it runs is determined by the machine’s template or provider. People can watch it, take control from the agent, and hand it back; they can also attach a terminal. Everything runs over the daemon’s outbound connection.

Desktop sessions and tickets

A desktop session lives on a machine that provides a desktop. Create it with the machine id; it allows one live session per machine. Then your backend mints a single-use, origin-bound watch ticket that expires in 15–120 seconds, so a browser never holds your API key:

curl -sS -X POST "$BMA_BASE_URL/v1/desktop_sessions" \
  -H "x-api-key: $BMA_API_KEY" -H "x-bma-project-id: $BMA_PROJECT_ID" -H "content-type: application/json" \
  -d '{"machine_id": "mch_...", "read_only": true}'

curl -sS -X POST "$BMA_BASE_URL/v1/desktop_sessions/$DESKTOP_SESSION_ID/tickets" \
  -H "x-api-key: $BMA_API_KEY" -H "x-bma-project-id: $BMA_PROJECT_ID" -H "content-type: application/json" \
  -d '{"origin": "https://app.example.com", "ttl_seconds": 60}'

The ticket response is a ticket object:

{
  "type": "ticket",
  "purpose": "watch",
  "id": "...",
  "ticket": "ct_...",
  "ws_url": "wss://.../...",
  "subprotocol": "bma.desktop.v1",
  "expires_at": "2026-01-01T00:00:30Z",
  "permissions": ["desktop.watch"],
  "machine_id": "mch_...",
  "desktop_session_id": "dsn_..."
}

The browser opens ws_url with Sec-WebSocket-Protocol: bma.desktop.v1, bma.ticket.<ticket> from the same Origin. The URL never contains the ticket, and the ticket works once. When it expires or is used, mint a new one.

Control

Endpoint (under `/v1/desktop_sessions/{id}`)	Purpose
`POST /acquire_control`, `/renew_control`, `/release_control`, `/handback_control`	Take control from the agent (the agent pauses), keep the lease, release, or hand back
`POST /screenshot`	Capture the display
`POST /actions`	Pointer, keyboard and text input, fenced by the control epoch
`POST /resume_agent`, `POST /pending_actions/{pending_id}/confirm`	The agent side of computer use: resume after a takeover, confirm an action the agent holds for approval
`POST /close`	End the desktop session

Control is enforced by the server: while a person holds control, the agent’s desktop actions are rejected. After a release or hand-back the agent re-observes the screen before continuing.

Terminal sessions

Terminal sessions work the same way: POST /v1/terminal_sessions with {"machine_id": "mch_..."} (optional shell, cwd, cols, rows), then POST /v1/terminal_sessions/{id}/tickets for a single-use connect ticket and a WebSocket attach with resumable output; POST /v1/terminal_sessions/{id}/close ends it. See Anthropic SDKs for a runnable example.

Status

Capability	Status
Desktop watch (RFB over WebSocket), human control, screenshot, actions	Available
Agent computer use (observe / act / confirm)	Available
WebRTC live view	Available: depends on the client network reaching the TURN relay
Terminal attach	Available
Browser SDK helpers for terminal and desktop	Not provided: use the `/v1` extension endpoints and the WebSocket protocol directly

Get started

Concepts

Executor & brains

Desktop sessions and tickets

Control

Terminal sessions

Status

​Desktop sessions and tickets

​Control

​Terminal sessions

​Status

Desktop sessions and tickets

Control

Terminal sessions

Status