Desktop & computer use - BMA Developer Docs

Machines started from BMA’s desktop templates run a Linux desktop. 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.

Watch a session’s desktop (Managed Agents API)

GET /v1/sessions/{id}/desktop/stream?desktop_session_id=dsn_…&origin=… (BMA extension) mints a single-use, origin-bound watch ticket that expires in 15–120 seconds, so a browser never holds your API key:

{
  "type": "bma.desktop_stream",
  "session_id": "ses_...",
  "desktop_session_id": "dsn_...",
  "machine_id": "mch_...",
  "url": "wss://api.staging.bma.beeos.ai/api/desktop/watch?...",
  "ticket": "ct_...",
  "subprotocol": "bma.desktop.v1",
  "expires_at": "2026-01-01T00:00:30Z",
  "permissions": ["desktop.watch"]
}

The browser opens url with Sec-WebSocket-Protocol: bma.desktop.v1, bma.ticket.<ticket> from the same Origin. The URL never contains the ticket. bma-sdk wraps the call as getSessionDesktopStream / GetSessionDesktopStream / get_session_desktop_stream.

Desktop sessions and control (native API)

Endpoint (under `/machines/{machineID}`)	Purpose
`POST /desktop-sessions`	Start a desktop session (one live session per machine)
`POST /desktop-sessions/{id}/control/acquire`, `renew`, `release`, `handback`	Take control from the agent (the agent pauses), keep the lease, release, or hand back
`POST /desktop-sessions/{id}/screenshot`	Capture the display
`POST /desktop-sessions/{id}/actions`	Pointer, keyboard and text input, fenced by the control epoch
`GET /desktop-sessions/{id}/signal` (WebSocket)	Live view: WebRTC signaling when the network allows it, RFB over the WebSocket otherwise
`POST /desktop-sessions/{id}/agent/observe`, `agent/actions`, `agent/actions/{pendingID}/confirm`, `agent/resume`	The agent side of computer use: observe the screen, submit actions (optionally held for confirmation), resume after a takeover

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 work the same way: POST /machines/{machineID}/terminal-sessions, then a connection ticket and a WebSocket attach with resumable output.

Status

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