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

# Terminal Channel

> Multiplexed PTY terminal sessions over the workspace WebSocket

The `terminal` channel runs PTY sessions inside the workspace. Multiple sessions multiplex over one connection, keyed by `sessionId`. See the [WebSocket overview](/api-reference/websocket/overview) for how to connect and authenticate.

A session spawns a shell resolved from `$SHELL`, falling back to `bash`. The PTY uses `TERM=xterm-256color`, starts at 80×24, and runs in the project working directory.

## Client to Server

### `create`

Open a new PTY session. Carries only the session ID — sizing is set afterward with `resize`. Reusing an existing `sessionId` is an error.

```json theme={"dark"}
{
  "channel": "terminal",
  "type": "create",
  "sessionId": "cli-123"
}
```

| Field | Type | Description |
| - | - | - |
| `sessionId` | string | Unique identifier for this session |

### `input`

Send keystrokes to a session.

```json theme={"dark"}
{
  "channel": "terminal",
  "type": "input",
  "sessionId": "cli-123",
  "data": "ls -la\n"
}
```

| Field | Type | Description |
| - | - | - |
| `sessionId` | string | Target session |
| `data` | string | Raw input (include `\n` for Enter, `\t` for Tab) |

### `resize`

Resize a session. Send when the terminal UI changes size. Both dimensions must be positive integers.

```json theme={"dark"}
{
  "channel": "terminal",
  "type": "resize",
  "sessionId": "cli-123",
  "cols": 200,
  "rows": 50
}
```

| Field | Type | Description |
| - | - | - |
| `sessionId` | string | Target session |
| `cols` | integer | New width in columns |
| `rows` | integer | New height in rows |

### `close`

Close a session and terminate its shell.

```json theme={"dark"}
{
  "channel": "terminal",
  "type": "close",
  "sessionId": "cli-123"
}
```

| Field | Type | Description |
| - | - | - |
| `sessionId` | string | Session to close |

## Server to Client

### `output`

PTY output, including ANSI escape codes.

```json theme={"dark"}
{
  "channel": "terminal",
  "type": "output",
  "sessionId": "cli-123",
  "data": "total 48\ndrwxr-xr-x  12 user  staff   384 Feb 20 10:30 .\n"
}
```

| Field | Type | Description |
| - | - | - |
| `sessionId` | string | Source session |
| `data` | string | Raw terminal output |

### `close`

The session's shell process exited. The message carries only the session ID — there is no exit code on the wire.

```json theme={"dark"}
{
  "channel": "terminal",
  "type": "close",
  "sessionId": "cli-123"
}
```

| Field | Type | Description |
| - | - | - |
| `sessionId` | string | Session that ended |

## Example Flow

```mermaid theme={"dark"}
sequenceDiagram
    participant Client
    participant Server

    Client->>Server: create (sessionId: "cli-123")
    Note right of Server: Spawn PTY shell
    Server->>Client: output (shell prompt)
    Client->>Server: input ("ls -la\n")
    Server->>Client: output (directory listing)
    Client->>Server: resize (cols: 200, rows: 50)
    Client->>Server: input ("exit\n")
    Server->>Client: close (sessionId: "cli-123")
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.