WebSocket Overview

A running workspace exposes one realtime connection: a multiplexed WebSocket that carries terminal I/O, file operations, live agent events, port changes, and git diffs over a single socket. The web app and the aether CLI both speak this same protocol.

Endpoint

GET /workspaces/{id}/ws

{id} is the workspace ID. This endpoint sits on the non-versioned router — it is not under /v1 like the rest of the public API. The API authenticates the request, verifies you own the workspace, requires the workspace to be in the Ready display state, then reverse-proxies raw text frames to the workspace VM. Every other documented surface is REST under /v1; this is the only WebSocket.

Connecting

Open the socket through the connect handshake rather than guessing the URL. Call POST /v1/workspaces/{id}/connect first — it returns a state-discriminated result. Connect never boots the VM unless you ask it to. Omitting start attaches only: a workspace that is not already usable answers 409 instead of being started, so merely viewing or polling a workspace can never bring one up (or undo a suspend). Booting is an explicit act — ?start=true&task_id=..., where task_id attributes the runtime to a task.

Request a connection

Call POST /v1/workspaces/{id}/connect. Add start=true&task_id=... only if you intend to boot a stopped workspace — send it once, on the request that expresses that intent.

Poll while connecting

While the VM boots, the response is state: "connecting" with retry_after_ms (1000). Wait that long and call again without start. The first accepted response has already created whatever start it was going to; repeating start=true can authorize a second one.A transitional 409 is different: it was refused, so nothing was started and an unspent start=true may be re-sent on the retry.

Open the socket

Once the response is state: "running", it includes transport.websocket_path (/workspaces/{id}/ws) and a preview_token. Connect to websocket_path, passing your token (see below).

When connect refuses

A 409 means the workspace is not attachable. The body is discriminated by kind, and the kind IS the answer — there is no flag to interpret:

`kind`	Meaning	What to do
`transitional`	A lifecycle operation is still settling; the same request answers differently once it lands. Carries `retry_after_ms`.	Wait `retry_after_ms` and call again. Bound your retries.
`startable`	A connect with `start=true` would actually start this workspace.	Stop polling. This is the only refusal on which you may offer the user a start.
`not_connectable`	Neither retrying this connect nor sending `start=true` can change it. Carries `display_state`.	Stop polling and surface `display_state`. Do not offer a start — it would be refused identically.

A workspace that is down can answer either arm. startable means this endpoint can bring it back — including resuming a suspended or stopped workspace whose run is still active; not_connectable means it cannot, because there is no machine left to start or the workspace failed. Either way that workspace is usually still recoverable by sending the agent a message, which goes through the task path rather than this endpoint.

{
  "kind": "not_connectable",
  "error": "Workspace is not running",
  "workspace_id": "5d1f...",
  "display_state": "suspended"
}

The running response shape:

{
  "workspace_id": "5d1f...",
  "state": "running",
  "display_state": "ready",
  "transport": {
    "websocket_path": "/workspaces/5d1f.../ws",
    "preview_token": "ab12cd34ef56ab12cd34ef56ab12cd34"
  }
}

The preview_token is a 32-character lowercase alphanumeric string used to build preview URLs.

Authentication

Pass an Aether API key (aether_…) or a session JWT one of three ways:

Method	How
Authorization header	`Authorization: Bearer YOUR_TOKEN`
Subprotocol	`Sec-WebSocket-Protocol: bearer, YOUR_TOKEN`
Query parameter	append `?token=YOUR_TOKEN` to the URL

Browsers can’t set request headers on a WebSocket, so the web client uses the query parameter. When a subprotocol is sent, the server echoes Sec-WebSocket-Protocol: bearer.

# Subprotocol
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

Every message is JSON with a channel field identifying the target subsystem and a type field identifying the message within that channel. Six channels are multiplexed over the connection:

Channel	Direction	Purpose
`terminal`	both	PTY terminal sessions
`files`	both	File operations and change notifications
`agent`	both	Subscribe to a task’s live event stream
`ports`	both	Open-port snapshot/changes and process kill
`git`	both	Workspace diff, checkpoints, restore, revert
`error`	server only	Out-of-band workspace errors

Client messages are validated against strict schemas — extra or misnamed fields are rejected. The canonical shapes live in packages/workspace-protocol/src/messages.ts.

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

The `error` Channel

The server pushes errors on a dedicated channel that you never send to. It is emitted after the socket opens when the VM fails to initialize or an inbound message fails to parse.

{
  "channel": "error",
  "type": "error",
  "error": "Invalid workspace message: ..."
}

If the API proxy cannot establish its connection to the VM, the browser WebSocket is not upgraded. The handshake returns HTTP 502 instead. The web client treats this as a failed connection attempt and re-runs the connect sequence so /connect can re-resolve the current workspace transport; other clients receive the failed handshake and can decide whether to retry.

Connection Keepalive

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

The API sends WebSocket ping frames every 15 seconds. If no pong arrives within 120 seconds, it closes the connection.

Reconnection

On reconnect, what comes back depends on the channel:

Terminal sessions keep running on the VM while you’re disconnected; reattach by sending create with the same sessionId.
Ports sends a fresh snapshot of currently-open ports on connect.
Agent resumes only live task_event messages for tasks you re-subscribe to. Conversation history is not replayed over the socket — fetch it via REST (conversation messages).
Files does not replay change events that occurred while disconnected; re-list or read to get current state.

Prompting an agent, responding to its questions, and stopping a task all happen over REST, not the WebSocket. See the agent channel.

API Reference

Projects

Workspaces

Tasks

Environment Variables

Secret Files

Skills

Automations

Agent Profiles

Usage

Profile

Organizations

User Discovery

Pr Reviews

Pull Requests

Push Tokens

Cursor Auth

Claude Code Auth

Slack

Provider API Keys

Codex Auth

Sentry

Feedback

Notifications

OpenCode Auth

GitHub

Platform API Keys

User Settings

Billing

Linear

WebSocket

WebSocket Overview

Endpoint

Connecting

When connect refuses

Authentication

Message Format

The `error` Channel

Connection Keepalive

Reconnection

​Endpoint

​Connecting

​When connect refuses

​Authentication

​Message Format

​The error Channel

​Connection Keepalive

​Reconnection

Endpoint

Connecting

When connect refuses

Authentication

Message Format

The `error` Channel

Connection Keepalive

Reconnection