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, Aether:- Parses the subdomain to extract the port, project ID prefix, and optional token
- Looks up the project by its short prefix
- Validates the auth token if one is included in the URL
- Resolves the workspace for the project
- Proxies the request to the correct 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
TheHost 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 |
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.