When you replace a preview, its local URL stays the same. New requests switch only after the replacement services pass readiness checks. Stop ends owned processes and retains managed database data.

Get started

Previewhost requires Node.js 22.23 or later. macOS and Linux support x64 and arm64. Windows requires x64. Native commands and automatic project owners run on macOS, Linux, and Windows. See the platform and database requirements. Linux requires procps (/bin/ps) and lsof (/usr/bin/lsof). Automatic unlock requires macOS 13 or later.

For an existing installation, read the reset instructions before updating.

Choose the interface you need:

| Interface | Guide | | --- | --- | | Coding agent | MCP setup: register a client and ask it to preview your application. | | Terminal | First preview with the CLI: run a frontend and backend, replace them, and stop them. | | Node.js program | Node.js library: start a runtime, request a page, and close it. |

Each guide includes its installation steps. The introduction explains how previews, environments, and project owners work.

Default lookup uses root preview.yaml, then preview.yml. If both exist, select one with --file or keep one default. New configurations save as preview.yaml only when neither file exists.

For a project with a configuration file and the global CLI installed:

previewhost inspect
previewhost start --allow-exec
previewhost dashboard

--allow-exec permits trusted commands and managed database operations with your user permissions, without a sandbox. The dashboard opens in your browser and needs its terminal to remain open. Closing it does not stop previews.

Documentation

| Task | Guide | | --- | --- | | Install or update Previewhost | Installation | | Run a complete example | First preview with the CLI | | Connect a coding agent | MCP setup | | Describe your application | Write preview.yaml | | Run services, migrations, and seeds | Services and jobs | | Connect or manage local data | Databases | | Supply private credentials | Secrets | | Preview existing task checkouts | Worktrees | | Inspect previews in the browser | Dashboard | | Diagnose errors | Troubleshooting | | Embed the runtime | Node.js library | | Look up fields and commands | API and CLI reference | | Check supported clients and frameworks | Integrations | | Understand permissions and recovery | Security |

The optional agent skill ships in the npm package under dist/skills/previewhost. Install it through your client's skill mechanism. MCP registration and skill installation are separate operations.

Reset required for earlier installations

This release uses ~/.local/share/previewhost for runtime storage and Previewhost names for managed Docker resources. It does not discover or migrate earlier runtime namespaces, Keychain secrets, or retained-data records. Existing files and resources are left intact.

1. Before updating, stop earlier Previewhost owners with the installed version.
2. If no encrypted keystore exists, run previewhost secrets init. Enter required secrets through private input.
3. For new managed databases, choose a fresh --data-dir.
4. Keep old data directories, Docker volumes, and Keychain items until you decide how to retain them.

For valuable old database data, use the earlier release to access and export it first. Use that release for any explicit cleanup of old data. Removing a record or generating a new password does not recover its database. See keystore recovery for backups and lost passwords.

Development

See CONTRIBUTING.md for source builds and verification. The documentation website renders the same Markdown guides with search, page outlines, and light and dark themes. Run npm run dev:docs after installing repository dependencies. Website code and build output are excluded from the npm package. The bundled agent skill includes its referenced guides and product screenshots.

See NOTICE for attribution and LICENSE for the MIT license.