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:abc12345:
Token-Protected URLs
For additional security, you can include an optional token in the URL:How Routing Works
When a request hits a preview URL, the gateway:- Parses the subdomain to extract the port, project ID prefix, and optional token
- Looks up the project by its short prefix (cached for 30 seconds)
- Validates the auth token if one is included in the URL
- Fetches the VM’s private IP from the workspace record
- Proxies the request to
{vmIp}:{port}inside the workspace
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.Port discovery runs continuously while the workspace is active. New ports are detected within seconds of a server starting.
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
Host Header Rewriting
The gateway rewrites theHost header to localhost:{port} before proxying to the VM. This ensures dev servers that check the host (like Vite’s default config) accept the request without additional configuration.
CORS Headers
The gateway includes CORS headers 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 |
Preview URL routing is cached for 30 seconds. If you delete and recreate a project with the same prefix, there may be a brief delay before the new workspace’s IP is resolved.