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

# Preview URLs

> Access running applications through preview URLs

# Preview URLs

Preview URLs let you access applications running inside a workspace from your browser. When a dev server starts on a port, Aether automatically generates a public URL that proxies traffic to the workspace VM.

## URL Format

Preview URLs follow this pattern:

```
https://{port}-{projectIdPrefix}.preview.runaether.dev
```

For example, a Vite dev server running on port 5173 in project `abc12345`:

```
https://5173-abc12345.preview.runaether.dev
```

### Token-Protected URLs

For additional security, you can include an optional token in the URL:

```
https://{port}-{projectIdPrefix}-{token}.preview.runaether.dev
```

Example:

```
https://3000-abc12345-mysecrettoken.preview.runaether.dev
```

Requests without a valid token are rejected. This is useful for sharing previews with specific people without exposing them publicly.

## How Routing Works

When a request hits a preview URL, Aether:

1. **Parses the subdomain** to extract the port, project ID prefix, and optional token
2. **Looks up the project** by its short prefix
3. **Validates the auth token** if one is included in the URL
4. **Resolves the workspace** for the project
5. **Proxies the request** to the correct port inside the workspace

```mermaid theme={null}
flowchart TD
    A[Browser Request] --> B[Parse subdomain]
    B --> C[Project Lookup]
    C --> D[Auth Token Validation - if present]
    D --> E[Workspace Resolution]
    E --> F["Proxy to localhost:{port}"]
```

## Port Discovery

Aether automatically discovers open ports inside the workspace. When a new port opens or closes, events are emitted to the frontend.

You don't need to configure anything — start a dev server on any port and the preview URL becomes active immediately.

<Info>
  Port discovery runs continuously while the workspace is active. New ports are detected within seconds of a server starting.
</Info>

## WebSocket Support

Preview URLs fully support WebSocket connections. This means:

* **Hot Module Replacement (HMR)** works through the proxy — Vite, Next.js, and webpack dev servers update in real-time
* **WebSocket-based applications** (chat, real-time dashboards) work without modification

No special configuration is needed. Connections are automatically upgraded to WebSocket when the client requests it.

## Host Header Rewriting

The `Host` header is rewritten to `localhost:{port}` before proxying to the workspace. This ensures dev servers that check the host (like Vite's default config) accept the request without additional configuration.

## CORS Headers

CORS headers are included in responses to allow cross-origin requests. This enables:

* Embedding previews in iframes
* Making API calls from a frontend preview to a backend preview on a different port
* Browser extensions and developer tools accessing preview URLs

## Troubleshooting

| Issue              | Cause                                                | Solution                                               |
| ------------------ | ---------------------------------------------------- | ------------------------------------------------------ |
| 502 Bad Gateway    | Dev server not running on the expected port          | Start the server and verify the port number            |
| Timeout            | Workspace is stopped or starting                     | Start the workspace and wait for `running` state       |
| Connection refused | Port is open but server is not accepting connections | Check server logs with `aether task watch` or SSH in   |
| HMR not working    | WebSocket blocked by network/proxy                   | Verify WebSocket support in your network configuration |

<Note>
  Preview URL routing is cached briefly. If you delete and recreate a project with the same prefix, there may be a short delay before the new workspace is resolved.
</Note>