Skip to main content
The Runtime Cloud API uses WebSockets for three real-time channels: terminal access, prompt streaming, and collaboration presence. All three follow the same authentication pattern: exchange a short-lived token via REST, then connect over wss://.

​
Channels

​
Token exchange flow

WebSocket endpoints do not accept API keys directly. Instead, you exchange your API key for a short-lived WebSocket token:
1

Request a token

Call the Token Exchange endpoint with the desired capability:
The response contains a short-lived JWT:
2

Connect via WebSocket

Pass the token as a query parameter when opening the WebSocket:
3

Exchange messages

Once connected, send and receive messages according to the channel’s protocol. Each channel page documents its message format.

​
Connection lifecycle

  1. Connect - Open a WebSocket to the channel URL with a valid token.
  2. Authenticate - The server validates the token on connection. Invalid or expired tokens result in an immediate close with code 4001.
  3. Message flow - Send and receive messages per the channel protocol.
  4. Disconnect - Either side can close the connection. The server closes idle connections after a timeout (varies by channel).

​
Reconnection

Tokens are short-lived (typically 5 minutes). If the connection drops or the token expires:
  1. Request a new token via the Token Exchange endpoint.
  2. Reconnect with the fresh token.
Implement exponential backoff for reconnection attempts to avoid flooding the server during outages.

​
Error codes