---
title: "Preview your app"
description: "Live preview URLs for your running app, plus the in-thread Preview and Terminal panels"
canonical_url: "https://hoplite.sh/docs/sandboxes/previews"
markdown_url: "https://hoplite.sh/docs/sandboxes/previews.md"
---

# Preview your app
URL: /docs/sandboxes/previews
LLM index: /llms.txt
Description: Live preview URLs for your running app, plus the in-thread Preview and Terminal panels
Related: /docs/sandboxes/scripts, /docs/sandboxes/resources, /docs/threads

# Preview your app

When the agent starts your app, you get a live preview in the thread, and the agent gets a running target to verify its own changes against with its browser tools.

## Starting a preview

The agent starts previews with its `preview_start` tool: it runs your project's [run script](/docs/sandboxes/scripts), waits for the preview port to start listening, and returns a provider-neutral `agent-preview:` reference. The call is idempotent — if the app is already up, it returns the same reference. Hoplite resolves that reference into a fresh provider endpoint only when you open the Preview panel, so expired links and provider changes do not leak into chat history.

Once the managed run is ready, Hoplite also finds its other listening ports. Undeclared HTTP listeners appear as additional Preview-panel entries with stable `agent-preview:` references; PostgreSQL, Redis, Temporal, and MongoDB listeners remain marked as services rather than browser previews. If an additional HTTP port should be permanent, the agent can promote the live listener into `.hoplite/settings.json` as a named additional port.

Keep a run command in `.hoplite/settings.json` or Project settings for a reliable preview configuration. When that command is absent but not explicitly disabled, Hoplite can detect common application frameworks and infer a development-server command, including a preferred application workspace in a monorepo. Inference is a fallback, not a replacement for an explicit command that captures your project's required services and setup.

For processes the agent started some other way, `sandbox_open_preview` creates the same kind of stable reference for any port that's already listening.

## Preview states

| State | Meaning |
| --- | --- |
| `starting` | The run script is up but the port isn't listening yet |
| `ready` | The app is serving; the preview URL is live |
| `stopped` | The process exited normally or was stopped |
| `crashed` | The process died — the agent sees the exit reason (including out-of-memory kills) and a redacted, bounded run-log tail to diagnose it |
| `unsupported` | The sandbox cannot provide the requested preview capability or port |

## How preview links work

Browser-facing preview and terminal endpoints run through Hoplite's preview proxy. Each thread port receives a durable share hostname under `usehoplite.com`; the proxy attaches fresh sandbox-provider HTTP or WebSocket credentials server-side. Provider tokens and Hoplite session cookies never reach the sandbox, and preview content stays outside the `hoplite.sh` authentication boundary.

Opening a shared link first verifies that you're signed in to Hoplite and still belong to the preview's workspace. When you open a preview from the Hoplite app, a short-lived, single-use bootstrap skips the visible login round trip and establishes dedicated preview access for the tab or embedded panel. The bootstrap is removed from the address bar before any sandbox content loads.

Only after authentication does Hoplite start or restore the sandbox. It shows a lightweight startup page while the workspace wakes, polls readiness on the same preview origin, and reloads into the app without changing the durable shared URL.

<Callout type="info" title="Only app previews are durable links">
Terminal and internal browser-control URLs remain short-lived and stop working when the sandbox generation changes.
</Callout>

## In-thread panels

- **Preview panel** — renders the running app right inside the [thread](/docs/threads), so you can click through the agent's work without leaving the conversation.
- **Terminal panel** — a shell into the sandbox for when you want to poke at things yourself.

On desktop, a newly ready preview opens automatically when no other panel is open, you are not composing, the tab is visible, and you have not explicitly selected another view. On mobile or when one of those conditions is not met, Hoplite leaves your layout alone and shows a one-time ready indicator on the panel control so the preview is easy to find.

## Review checklists

For user-facing UI changes, the agent can attach an ordered checklist to the Preview panel using its `preview_checklist_set` tool. Each step can point at a same-origin path and a specific control or piece of text, so you can work through the intended review flow in order.

Mark a step reviewed when you have checked it. If a later change affects that step, the agent can mark it unreviewed again with `preview_checklist_update`, so the checklist reflects what still needs attention. Checklist changes pause for your approval before they apply.

<Callout type="warning" title="Resource changes can interrupt previews">
The active provider may restart the sandbox runtime to apply a resource change, which stops running previews and background processes. The result reports whether the operation was disruptive. See [Resources and scaling](/docs/sandboxes/resources).
</Callout>

## Sitemap

See the full [sitemap](/docs/sitemap.md) for all pages.
Well-known sitemap: [/docs/.well-known/sitemap.md](/docs/.well-known/sitemap.md).