Skip to main content
Workspace showing preview panel on the right with built-in browser displaying the application
The preview browser lets you test your application without leaving the workspace.

​
Configuring Dev Server Scripts

Before using the preview, you need to configure a dev server script. There are two ways to do this.

​
Quick Setup from Preview Panel

If no dev server script is configured, the preview panel shows a setup prompt:
Preview panel showing prompt to set up dev server script with Edit Dev Server Script button
  1. Click Edit Dev Server Script
  2. Enter your dev server command (e.g., npm run dev)
  3. Click Save or Save and Test to verify it works
Fix Dev Server Script dialog with script input field and Save and Test button
The Save and Test button saves your script and immediately starts the dev server so you can verify the configuration works.

​
From Repository Settings

Alternatively, configure scripts through the settings:
1

Open Settings

Open the command bar (Cmd/Ctrl + K) and select Settings, or click the settings icon () in the navbar.
2

Go to Repository Settings

Select the Repos tab to view repository-specific settings.
3

Select Your Repository

Choose the repository you want to configure from the dropdown.
4

Configure Dev Server Script

Enter your dev server command in the Dev Server Script field:
FrameworkCommand
Vitenpm run dev
Next.jsnpm run dev
Create React Appnpm start
Yarn projectsyarn dev
PNPM projectspnpm dev
You can also configure:
  • Setup Script - Commands to run before starting (e.g., npm install)
  • Cleanup Script - Commands to run when workspace closes
5

Save Settings

Click Save to apply your changes.
Ensure your dev server prints the URL (e.g., http://localhost:3000) to stdout for automatic detection.
For detailed setup including the Web Companion for component selection, see Testing Your Application.

​
Opening the Preview

  • Click the Preview toggle () in the navbar
  • Click the preview icon in the context bar
  • Use the command bar: Cmd/Ctrl + K → “Toggle Preview Panel”
The preview panel automatically opens when a dev server starts.

​
Starting the Dev Server

From the context bar:
  • Click the Play icon () to toggle the dev server
From the command bar:
  • Press Cmd/Ctrl + K → “Toggle Dev Server”
The preview panel opens automatically and your application loads in the built-in browser.

​
Device Modes

Preview panel in mobile device mode showing responsive view of the application
Test across different viewport sizes:
ModeDescription
DesktopFull-width browser view
MobileMobile device dimensions
CustomSet specific viewport width and height
Switch modes using the device selector in the preview toolbar.

​
Multiple Dev Servers

For projects with multiple services:
  • Each dev server appears as a tab
  • Switch between servers to view different parts of your application
  • Logs are separated per server

​
Viewing Logs

The preview panel includes a log viewer:
  • View stdout/stderr from your dev server
  • View Full Logs button for complete output
  • Logs update in real-time
  • Filter or search log content
If your preview isn’t loading, check the logs for error messages or port conflicts.

​
Best Practices

  1. Start the dev server early in your task
  2. Keep the preview visible while the agent works
  3. Test changes incrementally
  4. Use device modes to verify responsive design

​
Troubleshooting

Possible causes:
  • Dev server hasn’t finished starting
  • Wrong URL being loaded
  • Application has a JavaScript error
Solutions:
  1. Check the Logs panel for the dev server output - wait for “ready” or similar message
  2. Verify the correct URL is detected (shown in the preview address bar)
  3. Open browser DevTools (right-click → Inspect) to check for console errors
  4. Try refreshing the preview with the reload button
Possible causes:
  • Hot reload isn’t working
  • Build error preventing update
  • Browser caching
Solutions:
  1. Check Logs panel for build errors
  2. Try a hard refresh (Cmd/Ctrl + Shift + R)
  3. Restart the dev server using the Play button
  4. Verify your framework supports hot module replacement (HMR)
What to do:
  1. Click Edit Dev Server Script in the preview panel
  2. Enter your dev server command (see table below)
  3. Click Save and Test
FrameworkCommand
Vitenpm run dev or pnpm dev
Next.jsnpm run dev
Create React Appnpm start
Vue CLInpm run serve
Angularng serve
Djangopython manage.py runserver
Railsrails server
Gogo run main.go
What it means: Another process is using the same port your dev server wants.Solutions:
  1. Find and stop the conflicting process
  2. Change your dev server port in your project config
  3. Close other workspaces that might have dev servers running
  4. Run lsof -i :3000 (replace 3000 with your port) to find what’s using it
Possible causes:
  • Relative paths not resolving correctly
  • Assets served from wrong directory
  • CORS issues
Solutions:
  1. Check that asset paths in your code are correct
  2. Verify your dev server is configured to serve static assets
  3. Check browser DevTools Network tab for failed requests