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

> PTY terminal sessions over WebSocket

## Overview

The `terminal` channel provides multiplexed PTY terminal sessions. Multiple concurrent sessions can run over a single WebSocket connection.

Default terminal settings:

| Setting | Value            |
| ------- | ---------------- |
| Shell   | `bash`           |
| TERM    | `xterm-256color` |
| Columns | 80               |
| Rows    | 24               |

## Client to Server Messages

### `create`

Create a new terminal session.

```json theme={null}
{
  "channel": "terminal",
  "type": "create",
  "sessionId": "cli-123",
  "cols": 120,
  "rows": 40
}
```

| Field       | Type    | Required | Description                                 |
| ----------- | ------- | -------- | ------------------------------------------- |
| `sessionId` | string  | Yes      | Unique identifier for this terminal session |
| `cols`      | integer | No       | Terminal width in columns (default: 80)     |
| `rows`      | integer | No       | Terminal height in rows (default: 24)       |

### `input`

Send keyboard input to a terminal session.

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

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

### `resize`

Resize a terminal session. Send this when the user resizes their terminal UI.

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

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

### `close`

Close a terminal session and terminate its process.

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

| Field       | Type   | Required | Description               |
| ----------- | ------ | -------- | ------------------------- |
| `sessionId` | string | Yes      | Terminal session to close |

## Server to Client Messages

### `output`

Terminal output data from the PTY.

```json theme={null}
{
  "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 terminal session                         |
| `data`      | string | Raw terminal output including ANSI escape codes |

### `close`

Terminal session has ended (process exited).

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

| Field       | Type            | Description                                        |
| ----------- | --------------- | -------------------------------------------------- |
| `sessionId` | string          | Terminal session that closed                       |
| `exitCode`  | integer or null | Process exit code, or null if terminated by signal |

## Example Flow

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

    Client->>Server: create (sessionId: "cli-123")
    Note right of Server: Spawn PTY
    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 (exitCode: 0)
```