Cloud Agent Computer Sessions

Cloud Agents expose their runtime’s desktop through VNC over WebSocket. This lets you view or interact with the computer the agent is using. All harnesses on the same runtime share that desktop.

Create a session

From your backend, request a computer session with the Runta API key:

curl --fail-with-body --silent --show-error -X POST \
  -H "Authorization: Bearer $RUNTA_TOKEN" \
  "$RUNTA_API_URL/v2/agents/$AGENT_ID/computer-sessions" | jq .

There is no request body. The response is 201 with this shape:

{
  "agent_id": "00000000-0000-4000-8000-000000000001",
  "runtime_id": "00000000-0000-4000-8000-000000000001",
  "expires_at": "2026-09-22T12:05:00Z",
  "channels": {
    "vnc": {
      "websocket_url": "wss://vnc-gateway.example/",
      "protocols": ["binary", "vnc-ticket.example-ticket"]
    }
  }
}

The IDs, hostname, expiry, and ticket above are illustrative. Always use the returned websocket_url and the entire protocols array.

Creating a session can enable VNC on the runtime and update its memory resource configuration. The request waits up to roughly 15 seconds for VNC readiness and ticket issuance. An unsupported desktop reports a failed-precondition error; readiness can time out. Treat this endpoint as an operation on the runtime, not merely a read-only URL lookup.

Connect a viewer

The connection uses the browser WebSocket subprotocol mechanism:

function openDesktopSocket(session) {
  const { websocket_url, protocols } = session.channels.vnc;
  const socket = new WebSocket(websocket_url, protocols);
  socket.binaryType = "arraybuffer";
  return socket;
}

This opens the transport; rendering the desktop requires a VNC/RFB client. For example, in an application that has installed @novnc/novnc, pass the same values to its RFB viewer:

import RFB from "@novnc/novnc/core/rfb.js";

export function connectDesktop(container, session) {
  const { websocket_url, protocols } = session.channels.vnc;
  const viewer = new RFB(container, websocket_url, {
    wsProtocols: protocols,
  });
  viewer.scaleViewport = true;
  viewer.resizeSession = true;
  return viewer;
}

Authorize the user in your own backend before returning the session to their browser. The browser only needs the expiring VNC ticket; keep the Runta API key on the backend. Do not put the API key or ticket into a URL, logs, or analytics.

Expiry and reconnecting

expires_at is the ticket’s expiration time, not a promise that a viewer will remain connected until that time. Runtime lifecycle changes or network failures can disconnect it earlier.

Request a new session for a reconnect rather than caching a ticket indefinitely. On disconnect, release the old viewer with viewer.disconnect(). There is no separate public computer-session deletion endpoint; runtime deletion ends access to the computer.

Reference: Create a computer session.