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

# Ports Channel

> Port discovery and preview URL management

## Overview

The `ports` channel provides real-time notifications when network ports open and close inside the workspace. This enables automatic preview URLs and port management without polling from the client.

## How It Works

Aether continuously monitors for new listening ports inside the workspace. When a new port appears, the server emits an `open` event and automatically makes it externally accessible. When a port stops listening, it emits a `close` event.

### Ignored Ports

These ports are excluded from detection:

| Port | Reason              |
| ---- | ------------------- |
| 22   | SSH                 |
| 2222 | Internal SSH        |
| 3001 | Reserved (internal) |

## Server to Client Events

### `open`

A new listening port was detected.

```json theme={null}
{
  "channel": "ports",
  "type": "open",
  "port": 3000,
  "pid": 12345,
  "process": "node"
}
```

| Field     | Type            | Description                |
| --------- | --------------- | -------------------------- |
| `port`    | integer         | Port number                |
| `pid`     | integer or null | Process ID of the listener |
| `process` | string or null  | Process name               |

### `close`

A port is no longer listening.

```json theme={null}
{
  "channel": "ports",
  "type": "close",
  "port": 3000
}
```

| Field  | Type    | Description             |
| ------ | ------- | ----------------------- |
| `port` | integer | Port number that closed |

## Client to Server Messages

### `kill`

Terminate the process listening on a port.

```json theme={null}
{
  "channel": "ports",
  "type": "kill",
  "port": 3000
}
```

| Field  | Type    | Required | Description                             |
| ------ | ------- | -------- | --------------------------------------- |
| `port` | integer | Yes      | Port whose process should be terminated |

## Preview URLs

When a port is detected, a preview URL is automatically available at:

```
https://{port}-{projectIdPrefix}.{previewDomain}
```

For example, if your project ID starts with `abc123` and the preview domain is `preview.runaether.dev`, a server on port 3000 would be accessible at:

```
https://3000-abc123.preview.runaether.dev
```

Incoming requests on preview URLs are routed to the correct workspace and port. No client configuration is required -- the URL is live as soon as the `open` event is emitted.

## Example Flow

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Server as Aether

    User->>Server: Starts dev server on port 3000
    Server-->>Server: Detects port 3000 listening
    Server->>User: open (port: 3000, process: "node")
    Note right of Server: Port forwarding started
    Note left of User: Preview URL live:<br/>3000-abc123.preview.runaether.dev

    User->>Server: Stops dev server
    Server-->>Server: Port 3000 gone
    Server->>User: close (port: 3000)
    Note right of Server: Port forwarding stopped
```