Skip to Content
Tile TypesPreview

Preview

Preview tiles attach a running web app to the workspace UI so you can open routes, edit paths, and keep the same preview running consistently across sessions. Add one from the tile picker as Web Preview. A preview tile tracks a port: the moment a dev server on that port comes up, the tile goes live; if the server stops, the tile waits for it to return.

Watcher mode is the recommended way to create a preview. You — or an agent — start a dev server however you like, and the preview tile tracks the port rather than trying to own or restart the server itself.

  • The port is the source of truth. The tile watches the port and lights up the moment a server binds to it. If the server restarts, the tile follows it. There’s no manual “this preview owns that server” wiring to keep in sync.
  • No ownership bookkeeping. You don’t register a command, mark the preview ready, or manage its lifecycle. Run your dev server in a terminal; the tile reflects reality.
  • Idempotent by port. Pointing a preview at a port that already has a server simply adopts the running server — it never starts a duplicate.

The contract is explicit and predictable: you run the server, the tile follows the port — no framework guessing, no command to register.

Picking a port

When you create a preview you can let YOLO Studio choose a free port for you (recommended) or name a specific one:

  • Auto picks a free port from a dedicated range so it won’t collide with reserved in-pod services.
  • A specific port (for example 3000, 5173, 8080) targets a known dev-server port directly.

A handful of ports are reserved by in-pod services and can’t host a preview — if you target one, the tile picks a free port instead. If you also attach a command or environment to a reserved port, the request is rejected rather than remapped (the command would still bind the reserved port); use Auto and bind your command to the returned port.

Managed Previews (Optional)

If you’d rather have YOLO Studio start the dev server for you, you can attach a command to the preview instead of running the server yourself. The command is run once, and re-running it is a no-op when the server is already up — so it’s safe to “ensure the preview is running” repeatedly without spawning duplicate servers.

Managed previews are useful when you want the preview to come back automatically in a later session without remembering to start the server by hand. Watcher mode is the better default for day-to-day work; reach for a managed command when you specifically want hands-off restart behavior.

Following a branch

A preview can follow a git branch instead of a server you run yourself. Choose Follow branch in the tile header and fill in Set up automatic branch updates: the Branch (default main), the App directory, optional Setup and Build commands, a Start command that uses $PORT and $HOST, and a Health check path. Then choose Create managed preview.

YOLO checks out the branch in a separate place, builds each new version, and switches the tile over only once the new version passes its health check. A failed update keeps the previous version serving. The header then reads Following the branch, with a state of current, updating, waiting for app or update failed, and shows which commit is being served — linked to its pull request when a Kanban card landed it. The page reloads on its own when the served commit changes.

Waiting for app is normal while the app doesn’t exist on the branch yet — for example, before the card that scaffolds it has landed.

A preview that follows a branch runs commands on every new version, so keep setup to stateless steps — no database migrations. Agents set these up with studio.create_preview and followBranch, and the Kanban card editor’s Preview action uses the same machinery to preview a single card’s unmerged branch.

Preview Tile UX

Preview tiles are designed around the route you are viewing, not the full signed preview URL.

  • Editable path bar — Edit only the path and query such as /settings or /docs?page=2.
  • Host shown separately — The preview host is displayed as a label instead of exposing auth tokens in the input.
  • Open in new tab — Opens the authenticated preview URL while keeping the token out of the editable bar.
  • In-place editing — A running preview can be reopened and its route edited from the tile.

Fixed viewport and scale-to-fit

Preview tiles render at a fixed logical viewport and scale the whole page down to fit the tile. The app sees a stable device size — so a button, a media query, or a responsive layout looks the same no matter how large or small you’ve made the tile.

  • Cycle between viewport presets from the tile toolbar: Fit (fills the tile, no fixed size), Desktop 1280×800, and Mobile 390×844.
  • The page renders at the chosen logical size, then scales down to fit; it never scales up past 1:1, so the preview stays crisp.
  • The selected viewport persists with the preview, so the tile reopens at the same size next session.

Persistence

Preview configuration persists automatically. When a preview is up and has a command attached, its config (port, command, working directory, environment, framework) is saved in the background so a later session can bring the same preview back consistently — no manual “Save” step.

Watcher-mode previews (where you run the dev server yourself) don’t carry a command, so there’s nothing to auto-restart — just start your server again and point the preview at the same port.

MCP Support

Agents can create and manage preview tiles through the workspace MCP server, so an agent can surface a live app inside the workspace instead of only describing how to run it.

  • studio.create_preview — create a preview tile for a dev-server port (pass watch: true for watcher mode — it’s opt-in, not the default), or for a remote HTTPS origin (see Remote Previews).
  • studio.trigger_preview — on a managed preview, ensure the attached command is running; a no-op if the server is already up.
  • studio.finalize_preview — attach a dev-server command to a preview that was created without one.
  • studio.inspect_port / studio.reclaim_port — safely take back a blocked port (see below).

Reclaiming A Blocked Port

A workspace can run several dev servers at once — one per lane or site. When an agent tries to start a dev server and the port is already taken (EADDRINUSE), it should not blindly kill whatever is there: that port might be another lane’s live server. Two MCP tools provide a safe, deliberate way to take a port back:

  1. studio.inspect_port (read-only) — reports what is listening on the port (pid, command, working directory) and whether you are allowed to reclaim it. An occupant attributable to your own lane is reclaimable; another lane’s server is not (the right move there is to pick a different port). On a reclaimable port it returns a short-lived confirmToken.
  2. studio.reclaim_port — takes that confirmToken and gracefully tears down the occupant (a worktree-bounded SIGTERM → SIGKILL of the dev-server process tree) so you can bind the port. If the occupant changed since you inspected it, the reclaim is refused and you re-inspect.

This is a two-step flow by design: you always see exactly what you are about to kill before killing it, and you can never clobber another lane’s running work. Lane attribution is derived from your session automatically — you only pass the port. Every reclaim is audited.

If your dev server still won’t start after reclaiming, the port wasn’t the problem — check the command and dependencies instead.

Remote Previews

A preview tile can also proxy an external HTTPS origin — a deployed Cloudflare Worker, a staging environment, or any publicly reachable URL — instead of a dev server running inside the workspace. Remote origins must be added to a per-workspace allowlist by an operator first. See Remote Previews for the full flow.

Last updated on
TerminalRemote Preview