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.

{
  "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.

{
  "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.

{
  "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