---
title: "Previews"
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"
---

# Previews
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/threads

# Previews

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.

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.

Browser-facing preview and terminal endpoints must either need no HTTP authentication or use a provider-supplied query credential. Hoplite rejects endpoints that require a custom header or cookie because an iframe cannot attach those credentials safely; supporting those providers requires a server-side preview broker.

## 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 can diagnose |
| `unsupported` | The project has no usable run script yet |

## In-thread panels

- **Preview panel** — renders the running app right inside the thread, 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.

<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](/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).