Preview
Preview containers let you see your project running live in the browser. Each preview launches a container with the appropriate framework runtime.
Starting a Preview#
From the Command Center right panel, click Start Preview. The system:
- Builds a container from the framework-specific image
- Runs the install command (if configured)
- Starts the dev server with the framework's default command
- Configures a reverse proxy for browser access
No manual port forwarding is needed — the reverse proxy handles routing automatically.
Preview States#
| State | Description |
|---|---|
| Idle | No preview container running |
| Loading | Container is starting up |
| Active | Preview is live and accessible |
| Error | Container failed to start; click Try Again to retry |
Framework-Specific Behavior#
Each framework has a pre-configured container image and default start command (see Projects). You can override the start command in project settings.
Preview containers have resource limits:
- Memory: 128MB (None/static) to 512MB (all others)
- CPU: 0.25 (None/static) to 1.0 (all others)
Log Streaming#
While a preview is active, container logs (stdout and stderr) stream to the bottom panel via WebSocket. This shows:
- Build output and compilation errors
- Server startup messages
- Runtime errors and warnings
- Request logs
Viewport Emulation#
The preview toolbar includes a device selector that constrains the preview pane width so you can verify responsive layouts without resizing your browser:
| Preset | Width |
|---|---|
| Desktop | Unconstrained |
| Tablet | 768 px |
| Mobile | 375 px |
| Custom | User-entered width × height |
The selected preset is saved per-project in your browser's local storage and restored on your next visit.
Sharing Previews#
Generate shareable links for your preview:
- Click the Share icon in the preview address bar while the preview is active
- Click Create New Share Link — the link is automatically copied to your clipboard
- Share with anyone — no authentication required to view
Manage shares:
- List all active share links
- Revoke individual share links
- Share links expire after 1 hour or when explicitly revoked; they return a 404 if the preview container is not running
Lifecycle#
- Idle timeout: Previews stop automatically after a period of inactivity (default 15 minutes on Free, 30 minutes on Pro, 2 hours on Team and Business — configurable by plan). The idle reaper polls every 30 seconds, so actual shutdown may lag the timeout by up to 30 seconds.
- Hard maximum: After 8 hours the preview session record expires and the preview becomes unreachable. The container is not explicitly stopped at that point — it becomes orphaned and is not automatically cleaned up.
- Heartbeat: The frontend sends periodic heartbeats to keep the preview alive while you're actively viewing it
- Agent-initiated start: Worker agents can start a preview automatically without user interaction via an internal API. The resulting preview URL is available to the agent for smoke-testing the running application.
- Ephemeral: Each preview starts fresh — no state is preserved between sessions. The project workspace files persist, but the container environment is rebuilt each time.
- Session security: In production, the preview iframe runs on a separate subdomain (
<tenant>.preview.<domain>). Before the iframe loads, the frontend performs an HMAC handshake with the proxy to obtain a scoped session cookie. This happens automatically — no action is required from you.
Terminal Access#
When a preview container is running, you can open an interactive terminal inside it. See Terminal.
Troubleshooting#
"Workspace is empty" error when starting. The preview container requires at least one file in the project workspace. Push or create files before starting the preview.
Preview stuck in Loading / fails to start. Check the Server Logs tab in the bottom panel for build errors or missing start commands. An error banner appears on the first failure with a View Logs shortcut and a Retry button. After three consecutive failures the Retry button is removed; check and fix your preview command in project settings, then restart the container. Verify the preview command matches how your framework's dev server is launched (e.g. npm run dev, uvicorn main:app --host 0.0.0.0).
Preview shuts down unexpectedly. A warning banner appears in the preview pane approximately 2 minutes before the idle timeout is reached. Sending a heartbeat (simply keeping the preview tab visible and the browser tab active) resets the timer. After 8 hours the session expires and the preview becomes unreachable regardless of activity.
Share link returns "Preview not found". The shared URL requires the preview container to be running. Restart the preview and share a new link, or ask the owner to restart it.