WebSocket Connection

How to establish and manage WebSocket connections to a session.

Connecting


GET /sessions/:id/ws?role=worker&token=WORKER_TOKEN
GET /sessions/:id/ws?role=client&token=CLIENT_TOKEN
GET /sessions/:id/ws?role=debug&token=WORKER_TOKEN

Roles

Role	Token	Description
`worker`	Worker token	The backend driving the browser automation
`client`	Client token	The mobile SDK with the webview
`debug`	Worker token	Read-only viewer that receives all messages

Note: the debug role authenticates with the worker token, not a separate debug token.

Handshake

After connecting, send a hello message:

Worker: { "type": "worker.hello" }
Client: { "type": "client.hello" }

The server responds with server.hello containing the current session state.

If the session is already in a terminal state (complete, failed, or expired), the server.hello response includes the terminal phase but no state transitions occur.

Message validation

All messages must be valid JSON with a type field. The server closes the connection with code 4000 if:

The message is not valid JSON
The type field is missing or not a string

Reconnection

If a connection drops, the client or worker can reconnect using the same token. The session actor tracks connection state independently from session phase. Buffered messages are delivered on reconnection.

Debug connections

Debug connections receive all messages wrapped in envelopes:


{
  "direction": "worker_to_server",
  "message": { ... },
  "ts": "2025-01-01T00:00:00Z"
}

Next steps

Messages — Full message reference
State Machine — Session phase transitions