WebSocket channels
The agent exposes two WebSocket endpoints:
| Path | Purpose |
|---|---|
ws://localhost:3005/ws/ | Event stream (session state changes, agent heartbeat, tunnel events) |
ws://localhost:3005/terminal/ | Bidirectional terminal I/O (for browser terminals via ttyd-style proxying) |
Auth
Pass the agent API key as a query param or via a subprotocol:
ws://localhost:3005/ws/?api_key=<agentApiKey>
Or use the standard x-agent-api-key header (if your WS client supports custom headers — most browsers don't).
Event channel (/ws/)
Subscribe per-profile:
ws://localhost:3005/ws/?profile=default&api_key=<key>
You'll receive JSON messages. Shape varies by event type. Subscribe-on-connect — no client message needed.
Terminal channel (/terminal/)
Used for live terminal I/O. Each connection is bound to a session ID:
ws://localhost:3005/terminal/?session=<id>&api_key=<key>
Sends raw bytes (xterm-style). Resize via in-band escape sequences.
Backend subscriptions
For events from the BACKEND (cross-agent, multi-user), use the GraphQL subscription endpoint via the workspaces gateway (see GraphQL API).