Live Preview and Dev Server

Helm Desktop includes built-in dev server management that lets you start your project's development server and preview changes in real-time as your AI agent makes edits. This article explains how to use these features.

Overview

When working on web projects, you often want to see changes immediately as code is modified. Helm's dev server integration lets you:

• Start/stop your dev server directly from the session UI
• Open live previews in your browser for each running service
• Monitor service health with real-time status indicators

Requirements

Live preview features require:

• Helm Desktop app (not available in browser-only mode)
• Local runtime mode enabled for your session
• A project with dev server configuration in project.json

Starting the Dev Server

When you have an active session in local runtime mode:

Look for the Dev Server panel in the session UI

Click Start Dev Server to launch your project's development server

Wait for the server to initialize — you'll see status indicators for each service

The dev server runs the command configured in your project (typically npm run dev or pnpm dev).

Multi-Service Projects

If your project has multiple services (e.g., web frontend and API backend), Helm will:

• Start all configured services
• Show separate health indicators for each service
• Allow you to open each service independently in your browser

Service Health Indicators

Each running service displays a health status indicator:

Indicator	Color	Meaning
Healthy	Green dot	Service is responding to health checks
Unhealthy	Red dot	Service is not responding
Checking	Spinning	Health check in progress
Unknown	Gray dot	Health status not yet determined

Health checks run automatically every 5 seconds while the dev server is running.

Opening Live Previews

Once your dev server is running:

Look for the Open in Browser buttons next to each service

Each button shows the service name and port (e.g., "Open web (localhost:4005)")

Click to open that service in your default browser

The buttons are:

• Enabled when the service is running (even if health check is pending)
• Disabled when the dev server is stopped
• Color-coded based on health status (green border = healthy, red = unhealthy)

Multiple Services

For projects with multiple services, you can open each one independently:

• Web frontend — Usually your main application UI
• API server — Backend endpoints (useful for API testing)
• Other services — Any additional services configured in your project

Stopping the Dev Server

To stop the dev server:

Click Stop Dev Server in the session UI

All services will be terminated gracefully

The live preview buttons will be disabled

The dev server also stops automatically when:

• You end your session
• You switch to a different project
• You close the Helm Desktop app

Configuration

Dev server settings are read from your project's project.json file:

{
"environments": {
"development": {
"services": [
{
"name": "web",
"port": 3000,
"command": "npm run dev:web",
"healthCheck": "/"
},
{
"name": "api",
"port": 4000,
"command": "npm run dev:api",
"healthCheck": "/health"
}
],
"primaryService": "web"
}
},
"commands": {
"dev": "npm run dev"
}
}

Configuration Options

Field	Description
services[].name	Display name for the service
services[].port	Port the service runs on
services[].command	Command to start this specific service (optional)
services[].healthCheck	Path for health check requests (default: /)
primaryService	Which service to use as the main entry point
commands.dev	Fallback command if individual service commands aren't defined

Troubleshooting

Dev server won't start

Check project configuration — Ensure project.json has valid dev server settings

Check dependencies — Run npm install or pnpm install if dependencies are missing

Check port conflicts — Another process may be using the configured port

Check terminal output — Expand the dev server log panel to see error messages

Live preview shows blank page

Wait for server — The dev server may still be starting up

Check health indicator — A red dot means the service isn't responding

Refresh the browser — Sometimes the browser cache causes issues

Check the URL — Ensure you're accessing the correct port

Health check shows unhealthy

This usually means:

Server crashed — Check the dev server logs for errors

Wrong health check path — Verify healthCheck path in configuration matches your API

Server overloaded — The server might be busy; wait and check again

CORS issues — Health checks use no-cors mode but some servers may still block

Buttons are disabled

The "Open in Browser" buttons are disabled when:

• Dev server is not running — Click Start Dev Server first
• Service failed to start — Check dev server logs for errors

Runtime Mode Requirements

Live preview features are only available when using Local runtime mode:

Runtime Mode	Dev Server Available	Live Preview Available
Local	Yes	Yes
Cloud	No	No

To switch to local mode:

Go to Profile Settings (in the desktop app)

Find the Runtime Mode section

Select Local

See Runtime Hosting Modes for more information.

Related Topics

• Runtime Hosting Modes — Configure local vs. cloud runtime
• Session Navigation — Navigate active sessions
• App Workspace Overview — Overview of the main workspace