> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiveku.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Live Preview
> How the preview container works, the agent tools that manage it, and the playbook for classifying and fixing a broken preview
The live preview is a container running `next dev` on ephemeral disk, hydrated from your saved project files. It is not a deployment: file saves and preview syncs reach it instantly and touch no hosting environment, and nothing on your live site changes until you [deploy](/publishing/deployments). The container itself is disposable. It auto-suspends after idle (a stopped preview is routine, not a failure), it is excluded from [checkpoints](/editor/checkpoints), and it can be rebuilt from the saved project at any time. The saved project, and in particular its `package.json`, is the only source of truth: since 2026-09-02 the platform no longer seeds the starter template over a project that has files, and leftover starter files from older boots are cleaned automatically on the next sync.
The tools on this page are the agent tool catalog, used by external agents such as the [Claude Code plugin](/integrations/claude-code-plugin) and [LLM connectors](/integrations/llm-connectors). The [AI assistant](/ai/tools) inside the builder carries an equivalent surface of its own and applies the same repairs automatically when the preview misbehaves.
## Reading preview state
`preview_overview` is the one-call status and the first call in any code-change workflow. It returns `ready`, the user-visible preview URL, `status` (running / stopped / starting), health, phase, the last sync timestamp, and the count of file changes pending sync, plus `blockers` (hard stops to surface to the user) and `hints` (next actions for the agent).
`ready: true` here means the container is up **and** the project's files have landed on it. A change is not verifiable, and not "done", while `ready` is false. A phase of `syncing` means files are still being delivered: check again every 5 to 10 seconds until ready. A blocker naming a delivery or Node-version problem carries the fix in plain language; surface it rather than retrying blindly.
### Boot phases
`preview_health` is a passthrough of the container's own `/api/health` endpoint: `{ ready, phase, app, proxy }`. The `phase` field is the boot truth:
| Phase | Meaning | What to do |
| ------------------------------------ | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `installing` / `downloading` | A dependency install is in progress. This runs 2 to 5 minutes after a `package.json` change | Wait and re-check. Never diagnose a healthy install as a failure |
| `starting` / `compiling` / `syncing` | Normal boot | Wait |
| `stopped` | The machine is not running; answered from the machine state without waking it | `preview_start`, then poll |
| `unresponsive` | The dev server stopped answering | `preview_force_recompile` after a failed restart |
| absent | The machine was built from an older image | Treat as unknown and fall back to `preview_overview` |
`ready: true` is gated server-side on both `preview_health` and `preview_overview`: it means the dev server compiled **and** the project's files landed on this machine. If a page still renders the starter template or "Untitled site", treat that as container divergence (Class 1 below), never as a health problem. Polling `preview_health` never wakes a stopped machine: a stopped preview is answered from the machine state as `{ ready: false, phase: "stopped", machine_status }` - start it with `preview_start`, then poll.
## Status and lifecycle
| Tool | What it does | When |
| ------------------ | --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `preview_overview` | One-call status: ready, preview URL, status, health, phase, last sync, pending changes, blockers, hints | First, on any code-change workflow |
| `preview_health` | The container's own health endpoint, including the boot phase | After a start or restart, to tell a booting preview from a broken one |
| `preview_start` | Boots or resumes the preview and returns the preview URL once the container is reachable. Idempotent, safe to re-call | When `preview_overview` reports status `stopped` or `unknown` |
| `preview_stop` | Stops the preview | Sparingly. The environment auto-suspends after idle, so explicit stop is mainly for forcing a clean restart after a broken change. Pair with `preview_start` afterward |
## Getting changes onto it
| Tool | What it does | When |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `preview_sync` | Pushes the latest project files into the running preview | After any file write, so the change appears at the preview URL. Requires the preview to be running |
| `preview_assets_resync` | Restores missing binary assets (images, fonts, videos) from storage. `preview_sync` pushes code files and only very recent assets; this reconciles the full asset set | When the preview shows broken images for files that exist in the media library, typical after a machine was recreated following long idle. Never ask anyone to re-upload files the library already has |
`preview_sync` reports the container's real per-file result. The `synced` count is the container's successful count, so a genuine 0 means 0:
| Status | Response | Meaning |
| ------ | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 200 | `success: true` with `synced`, `failed: 0` | Everything synced |
| 207 | `success: false`, `partial: true`, code `preview_sync_incomplete` | Some files failed. Retry the sync; `preview_force_recompile` if failures persist |
| 502 | `synced: 0` with code `preview_sync_incomplete` | Nothing synced; the container is not accepting writes. Retry once, then `preview_force_recompile` |
| 503 | code `preview_container_unhealthy` with `breaker_retry_after_ms` and a `Retry-After` header | The per-URL circuit breaker is open after 5 consecutive failures; no files were attempted. Wait the hinted interval, then retry or `preview_force_recompile` |
## Seeing and diagnosing
| Tool | What it does | When |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `preview_screenshot` | Captures a page of the preview, cropped to 1920x1080, with the image returned inline plus full-resolution and thumbnail URLs. Warms the route first to trigger the on-demand compile. Optional `cookies` and `headers` reach auth-gated routes | Any user-visible change. A 409 `preview_not_running` means start the preview first |
| `preview_logs` | Tails the dev server output from `/app/dev-server.log` inside the container, SSR stacks included | Raw log reading. For typecheck, lint, or test failures prefer the `verify_*` tools; for parsed runtime errors prefer `preview_runtime_errors` |
| `preview_runtime_errors` | Structured server-side errors parsed out of the dev-server log, as `{ message, stack }` objects | After a preview 500, a blank page, or a failed screenshot |
| `preview_client_errors` | Browser-side errors: React hydration mismatches, uncaught client exceptions, unhandled promise rejections, and `console.error` output. These occur in the browser and never appear in the server logs | Whenever the page renders but behaves wrong, interactivity is dead, or a change touched SSR/client boundaries |
| `preview_http_get` | HTTP GET against localhost inside the container, returned as structured status, content type, and body | Reading a 500 page's embedded error when the dev server swallows the stack, or checking an API route without leaving the container |
| `preview_read_file` | Reads a file from inside the running container: the live `/app` tree the dev server actually sees, including generated files and logs | Inspecting container state that can differ from the saved project while a sync is pending. Credential paths are refused |
| `preview_exec` | Runs an ad-hoc command inside the container. Common dev commands (package managers, `tsc`, `eslint`, test runners, `node`, `git`, file inspection) run directly; anything else returns an escalation token and requires the user's approval in the dashboard before it runs | Rerunning a non-standard build or a custom script. Prefer the dedicated tools above for common diagnostics |
The verification tools (`verify_typecheck`, `verify_lint`, `verify_run_tests`) also run inside the preview environment and return structured exit codes; prefer them over log-scraping for typecheck, lint, and test results.
An empty `preview_client_errors` result is not proof the page is clean. Check the returned `capture_installed` flag: `false` means capture is not wired on this container (an older machine image), so recreate it with `preview_force_recompile({ refresh_image: true })`. Even when `true`, errors are only recorded when the page actually runs in a browser, so load it first (for example with `preview_screenshot`) and re-check.
## Repair
| Tool | What it does | When |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `preview_force_recompile` | Stops and restarts the Fly machine, clears the Next.js compile cache, and re-syncs the saved files. Roughly 30 to 90 seconds of downtime; it returns immediately by default, so poll `preview_overview` for readiness. `refresh_image: true` destroys and recreates the machine so it re-pulls the current container image | The escape hatch when the container has diverged from the saved project: a stale compile cache, a route serving old code despite a fresh save, a white screen after a restore, or starter leftovers. `refresh_image: true` only when a plain run did not clear it or the platform shipped a container-level fix |
| `preview_reinstall_deps` | Clean dependency reinstall inside the container. Async: it kicks the install off detached and returns immediately. Poll `preview_read_file({ path: '/tmp/hiveku-reinstall.log', tail_lines: 40 })` every 15 seconds or so until a line containing `hiveku-reinstall: exit=` appears (`exit=0` is success). Installs typically run 1 to 4 minutes | After changing `package.json`, or when the install itself is broken (errors from inside `node_modules//`) |
## When the preview breaks: classify first
Preview failures divide into four classes. Only one of them is fixed by editing code, so read the error and classify before acting:
1. **The error names a file that is not in the project.** For example `Module not found: Can't resolve '@radix-ui/react-label'` from `./components/ui/label.tsx`, when the project's saved file list has no such file. That is a starter leftover on the container, not your code: run `preview_force_recompile`. If the identical error persists, run it once more with `refresh_image: true`; only the full recreate prunes leftovers. Two fixes are forbidden: never add the starter's package to the project's `package.json` to silence the error, and never delete or edit the container file by hand, because container edits sync back into the saved project.
2. **`Module not found: Can't resolve './x'` where the importing file is inside `node_modules//`.** A package failing to resolve its own relative file is a broken install: run `preview_reinstall_deps` and poll the install log as described above.
3. **The error points at a file the project owns.** Fix the code. This is the only class where editing is the answer. One sub-case: a persistent module-not-found on a file the project does own means the project imports a package it never declared. Add the dependency to `package.json`; recreating the container cannot fix a manifest defect.
4. **Blank page, or the HTML serves but interactivity is dead.** This is hydration territory: run `preview_client_errors`. A `capture_installed: false` result means an old container image, so run `preview_force_recompile({ refresh_image: true })`.
Related container state, same discipline: missing images for files that do exist in the media library are Class-1-adjacent divergence, fixed by `preview_assets_resync`, never by re-uploading.
Since 2026-09-02, a recreated machine of a project with files no longer seeds the starter template or its `node_modules`. It waits for the project's own files and installs exactly what `package.json` declares, so a routine reinstall after `refresh_image: true` is no longer required; reach for `preview_reinstall_deps` only when the install itself is broken.
## Preview-green is not deploy-green
A build error that does not surface in the live preview can still kill a deploy: the deploy pipeline uses a different bundler, Node baseline, and env injection. Verify the deploy path itself before shipping; see [Deployments](/publishing/deployments).