previewhost

Previewhost runs local previews for full-stack apps.

Run multiple isolated previews side by side for different Git worktrees or repositories. Each preview can start your frontend, backend, databases, Redis, setup jobs, and other services together.

Previewhost assigns local URLs and ports, starts services in dependency order, and keeps managed data separate between environments. Use it from the dashboard, CLI, Node.js library, or through MCP with your coding agent.

Secrets stay as references in configuration and can be entered privately outside the agent chat. Service and job logs are available in one place.

Get started

Previewhost requires Node.js 22.23 or later.

npm install -g previewhost

Choose the interface you need:

Previewhost supports macOS, Linux, and Windows. See the platform and database requirements for architecture, system dependency, and database details.

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

Start with installation if Previewhost is not installed. The introduction explains previews, environments, and project owners.

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. Use New preview to select a local folder and configuration, or Configuration to edit bindings and apply changes. Keep its terminal open; closing the dashboard does not stop previews.

Related MCP server: ChatGPT Gateway MCP Nyan

Documentation

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.

Run npm run dev:docs to start the documentation site locally.

See NOTICE for attribution and LICENSE for the MIT license.