Dev Preview

Overview

Dev Preview panels run your project's dev server and display its output in an embedded browser inside Canopy. You can watch your UI update in real time as agents make changes to your code. Each panel runs its own isolated dev server session, so you can open multiple previews without them interfering with each other.

Setting Up

Manual Configuration

Configure your dev server command in the project settings:

1. Open your project's settings (or use the Dev Server button in the toolbar)
2. Set the dev server command (e.g., npm run dev, yarn dev, pnpm dev)
3. Canopy will run this command and detect the local URL it serves on

Automatic Discovery

Canopy scans your project for runnable commands every time it loads. Detection covers several file types:

• package.json scripts — the runner is selected automatically based on your lock file (bun.lock uses bun, pnpm-lock.yaml uses pnpm, yarn.lock uses yarn, otherwise npm)
• Makefile targets (non-private, non-PHONY)
• Justfile recipes (skips underscore-prefixed entries)
• Taskfile.yml tasks (only those with a desc field)
• Django manage.py — common commands like runserver, migrate, test, and shell
• composer.json scripts (non-lifecycle)

All discovered commands appear in the QuickRun autocomplete. Detection results are cached for 60 seconds and refresh automatically on project load or when you switch worktrees.

For the Dev Preview panel specifically, the six file types above power QuickRun's suggestions but the one-click setup is narrower: Canopy only looks for a package.json script named dev, start, or serve (checked in that order). When it finds one, the unconfigured Dev Preview panel shows a Configure Dev Server heading with a one-click Use [detected command] button. Clicking it saves the command to your project settings and starts the server automatically.

If no candidate script is found, the panel shows only an Open Project Settings button so you can configure the command manually.

Opening Dev Preview

Launch a Dev Preview panel from the toolbar (Dev Server button), the panel palette (Cmd+N), or the worktree context menu. If no dev server command is configured, the panel shows a Configure Dev Server prompt with an auto-detect button and a link to Project Settings.

The toolbar button can be shown, hidden, or repositioned in Settings > Toolbar. It uses the Monitor icon and is labelled "Dev Preview" in the toolbar configuration.

QuickRun

QuickRun is a collapsible panel at the bottom of the project sidebar, below the worktree list. It gives you quick access to any command against the active worktree. Not restricted to dev servers, it handles build scripts, test runners, watch processes, or anything you'd normally type into a terminal.

The panel header reads Run on [worktree name] with a collapse/expand toggle. If no worktree is selected, it shows "Select a worktree above to enable Quick Run" and the input is hidden.

Running a Command

Type into the $ input field and press Enter to run. Use ↑/↓ to navigate suggestions and Escape to close the dropdown.

The autocomplete dropdown (labelled COMMANDS) shows three categories of suggestions:

• Pinned — commands you've saved, shown first with a filled pin icon in accent color
• Scripts — commands discovered from your project files (all six file types listed in Automatic Discovery), shown with a terminal icon
• History — up to 10 previously run commands per project, shown with a clock icon

Pinning Commands

Hover over any command in the dropdown and click the pin icon to save it. Pinned commands store two preferences that are restored automatically when you run them:

• Output location — Grid panel (interactive terminal) or Dock (background task)
• Auto-restart — whether the process should restart automatically if it exits

To remove a pinned command, hover over it and click the unpin icon.

Output Location and Auto-Restart

Three controls sit to the right of the input field:

• Auto-restart (refresh icon) — toggles automatic restart for the command. Green when active. The process restarts if it exits.
• Location (grid/panel icon) — switches between Grid (opens as an interactive terminal panel) and Dock (runs as a background task)
• Run (return icon) — equivalent to pressing Enter

Running Tasks List

When commands are running, a task list appears above the input showing up to five active or recent tasks. Each row displays:

• A status dot — green pulsing (running), amber pulsing (restarting), solid green (success), or red (failed)
• The command name (truncated to 28 characters)
• An elapsed timer that ticks while the process is active
• Action buttons — Stop, Restart, Dismiss, or Focus (click to jump to the panel)

Successful tasks clear automatically after three seconds. Failed tasks stay visible until you dismiss them. If more than five tasks are running, a "+N more" indicator appears.

Toolbar

The toolbar at the top of each Dev Preview panel provides browser-style controls:

• Back / Forward — navigate through page history (disabled when there's no history)
• Reload — refresh the current page (animates while loading)
• Zoom Out / Zoom Level / Zoom In — adjust the preview zoom. Click the percentage label to reset to 100%. Available presets: 25%, 50%, 75%, 100%, 125%, 150%, 200%
• URL bar — shows the current URL. You can edit it and press Enter to navigate directly. Frecency-based autocomplete suggests URLs from your history as you type
• Copy URL — copies the current URL to the clipboard
• Open in External Browser — opens the current page in your default browser

Find in Page

Press Cmd+F (Ctrl+F on Windows and Linux) to search for text within the current preview page. A floating find bar appears in the top-right corner of the webview with a text input, match count, and navigation buttons.

The search runs in real time as you type and displays the current match position (e.g., "3 / 12"). If there are no matches, the bar shows "No results". The shortcut works regardless of whether the Canopy UI or the embedded page has focus. Pressing Cmd+F again when the bar is already open refocuses the input and selects the text.

Find in Page is SPA-aware and automatically restarts the search when the page navigates internally. Closing the bar clears all highlights.

Find in Page is also available in Portal Browser and works identically.

Console Drawer

The console drawer is a collapsible panel at the bottom of the Dev Preview that shows your dev server's terminal output. Toggle it with the Show Terminal / Hide Terminal button.

A status indicator in the console bar shows the server's current state with a color-coded dot:

The Hard Restart button in the console bar header kills the server process and relaunches it. It's disabled while the server is starting. If the server is in the Installing state, a tooltip warns that restarting may interrupt the installation.

When a panel re-mounts (for example, after docking or undocking) and the server is still starting, the last 300 lines of terminal output are replayed so you don't lose context.

Session Lifecycle

Each Dev Preview panel maintains its own isolated dev server session, keyed by project and panel. Sessions survive panel remounts, so docking, undocking, or rearranging panels won't restart your server.

Lazy Loading

The embedded browser isn't created until the panel is first visible. Background panels show a placeholder until you switch to them, which saves memory when you have several panels open.

Load Timeout

Canopy waits for the dev server to respond before showing the preview. The timeout is configurable from 1 to 120 seconds (default: 30 seconds) in Project Settings. If the server stays in the Starting state for more than 10 seconds with no URL detected, Canopy attempts one automatic restart.

Connection Retry

If the embedded browser gets a connection-refused or connection-reset error, Canopy retries up to 5 times with exponential backoff (starting at 500ms, capping at 8 seconds). This handles the common race condition where the dev server reports ready before it's fully reachable.

Scroll Position

Canopy saves your scroll position when a panel unmounts and restores it when the same URL loads again. A Hard Restart clears the saved position since the page content has changed.

Memory Reclaim

Background panels may have their webview released to free memory. When this happens, the panel shows a "Reclaimed for memory" placeholder. The webview is recreated the next time you focus the panel.

Blocked External Navigation

If a page in the preview tries to navigate to an external URL (a different origin from your dev server), Canopy intercepts it and shows a banner at the top of the webview: "Navigation to external site blocked: [hostname]". You can click Open in External Browser to follow the link in your default browser, or dismiss the banner. It auto-dismisses after 10 seconds.

Two-Pane Layout

Dev Preview works well with the two-pane split layout. Enable "prefer preview" in Settings > Terminal (Panel Grid) to automatically place Dev Preview panels in the secondary pane, giving you a side-by-side view of agent work and your running app.

Settings Reference

• Dev server command — the command to run (e.g., npm run dev). Set in Project Settings
• Dev server load timeout — how long to wait for the server to respond, 1 to 120 seconds, default 30. Set in Project Settings
• Environment variables — injected into the dev server process. Set in Settings > Environment Variables
• Prefer preview — places Dev Preview panels in the secondary pane automatically. Set in Settings > Terminal (Panel Grid)
• Dev Preview toolbar button — show, hide, or reorder the Dev Preview button (Monitor icon) in the toolbar. Set in Settings > Toolbar
• Always show dev server in launcher — shows the dev server option in the launcher palette even when no command is configured for the project. Set in Settings > Toolbar