# 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](/secrets/index.md). |
| A local Docker Engine | Managed PostgreSQL/Redis and Compose previews. See [Databases](/databases/index.md#prepare-docker). |
| Docker CLI with the Compose plugin | Compose previews. |
| Your application's dependencies | Install these before startup, or declare [setup jobs](/services-and-jobs/index.md). |

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:

```sh
npm install -g previewhost
previewhost --version
previewhost --help
```

Run `previewhost dashboard` to start a preview in your browser. See the [dashboard guide](/dashboard/index.md#start-a-preview) for configuration and private setup.
For terminal use, follow [First preview with the CLI](/first-preview/index.md). For a coding agent, follow [MCP setup](/mcp/index.md).
If your editor cannot find the executable, follow the [PATH troubleshooting steps](/troubleshooting/index.md#the-client-cannot-find-previewhost).

## Install in a project

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

```sh
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](/library/index.md) for a complete program.

## Update an installation

Before updating an existing installation, follow the [reset instructions](https://github.com/RojhatToptamus/previewhost/blob/main/README.md#reset-required-for-earlier-installations) for runtime storage and managed data.

For a global installation:

```sh
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:

```sh
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](/troubleshooting/index.md#stored-secrets-are-missing-or-inaccessible).