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

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

```bash theme={null}
# 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             |

```json theme={null}
{
  "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

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant Server

    Client->>Server: HTTP Upgrade Request
    Note right of Server: Authenticate token
    Server->>Client: 101 Switching Protocols
    Client<<->>Server: Channels active
    Server->>Client: ping
    Client->>Server: pong
    Server->>Client: close
```

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.