Installation

Install Previewhost with npm. Check the Node.js, operating-system, and Docker requirements for the features you need.

Requirements

Requirement	When you need it
Node.js 22.23 or later	All workflows.
macOS or Linux on x64/arm64, or Windows on x64	Supported platforms.
`ps` and `lsof`	macOS uses system tools. Linux needs procps at `/bin/ps` and lsof at `/usr/bin/lsof`.
macOS 13 or later	Optional automatic keystore unlock through Keychain.
An unlocked keystore	Stored secrets and managed database credentials. See Secrets.
A local Docker Engine	Managed PostgreSQL/Redis and Compose previews. See Databases.
Docker CLI with the Compose plugin	Compose previews.
Your application's dependencies	Install these before startup, or declare setup jobs.

Windows ARM64 is not supported.

Windows databases: experimental. Tested on x64 with WSL Docker; Docker Desktop unverified. Windows interactive terminal input remains unverified. Stdin secret input is tested.

The npm package includes the macOS Keychain helper and uses Koffi platform packages for kernel APIs. Installation needs no compiler or GitHub access.

On Debian or Ubuntu, install the Linux command prerequisites with sudo apt-get install procps lsof. Windows commands preserve literal arguments. Batch files require an explicit cmd.exe command, or node.exe with the JavaScript CLI path.

Install the CLI

Run these commands in your terminal:

npm install -g previewhost
previewhost --version
previewhost --help

Run previewhost dashboard to start a preview in your browser. See the dashboard guide for configuration and private setup. For terminal use, follow First preview with the CLI. For a coding agent, follow MCP setup. If your editor cannot find the executable, follow the PATH troubleshooting steps.

Install in a project

For library imports or a project-specific CLI, run this from the application directory:

npm install previewhost
./node_modules/.bin/previewhost --version

Use ./node_modules/.bin/previewhost instead of previewhost in the guides that follow. See the library guide for a complete program.

Update an installation

Before updating an existing installation, follow the reset instructions for runtime storage and managed data.

For a global installation:

npm install -g previewhost
previewhost --version

Existing project owners keep their loaded version. When you can stop their previews, run this from each affected project:

previewhost shutdown

Then start the preview again. Managed data and stored values remain, but owner shutdown ends secret access approvals. Each restarted owner needs keystore unlock unless automatic unlock is available. See secret access troubleshooting.