Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.runaether.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
Endpoint

GET /workspaces/{id}/ws
Upgrades to a WebSocket connection for real-time, bidirectional communication with a running workspace.

​
Authentication

Authenticate using one of:
MethodDetails
Protocol headerPass the token in the Sec-WebSocket-Protocol header as Bearer, YOUR_TOKEN
Query parameterAppend ?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:
ChannelPurpose
terminalPTY terminal sessions
filesFile system operations and watching
agentAI agent interaction and streaming
portsPort discovery and preview URLs
configWorkspace 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

ParameterValue
Ping interval45 seconds
Pong timeout120 seconds
Write timeout30 seconds
Max message size1 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.