WebSocket Overview

Real-time communication with workspaces

Endpoint

GET /workspaces/{id}/ws

Upgrades to a WebSocket connection for real-time, bidirectional communication with a running workspace.

Authentication

Authenticate using one of:

Method	Details
Protocol header	Pass the token in the Sec-WebSocket-Protocol header as Bearer, YOUR_TOKEN
Query parameter	Append ?token=YOUR_TOKEN to the WebSocket URL

# Protocol header
wscat -c wss://api.runaether.dev/workspaces/ws-123/ws \
  -s "Bearer, YOUR_TOKEN"

# Query parameter
wscat -c "wss://api.runaether.dev/workspaces/ws-123/ws?token=YOUR_TOKEN"

Message Format

All messages are JSON with a channel field that identifies the target subsystem. Five channels are multiplexed over a single connection:

Channel	Purpose
terminal	PTY terminal sessions
files	File system operations and watching
agent	AI agent interaction and streaming
ports	Port discovery and preview URLs
config	Workspace configuration

{
  "channel": "terminal",
  "type": "input",
  "sessionId": "cli-123",
  "data": "ls -la\n"
}

Every message must include channel and type. Additional fields depend on the specific message type.

Connection Keepalive

Parameter	Value
Ping interval	45 seconds
Pong timeout	120 seconds
Write timeout	30 seconds
Max message size	1 MB

The server sends WebSocket ping frames at 45-second intervals. If no pong is received within 120 seconds, the connection is closed.

Connection Lifecycle

1. Connect — Client sends an HTTP upgrade request with authentication credentials.
2. Authenticate — Server validates the token and upgrades the connection.
3. Channels active — All five channels are immediately available for messaging.
4. Keepalive — Server sends periodic pings; client responds with pongs.
5. Close — Either side can close the connection gracefully.

Reconnection

Conversation history and workspace state are persisted, so reconnecting to the same workspace resumes where you left off.

On disconnect:

• Terminal sessions remain running in the background.
• Agent conversation history is replayed automatically.
• File watcher events that occurred during disconnection are not replayed, but the current file state is always available via list and read operations.