Install

Already followed Getting Started? You're all set — this page is for alternative install methods, platform-specific instructions, and maintenance.

System requirements

• Node 22+ (the installer script will install it if missing)
• macOS, Linux, or Windows
• pnpm only if you build from source

Note: On Windows, we strongly recommend running OpenSoul under WSL2.

Install methods

Tip: The installer script is the recommended way to install OpenSoul. It handles Node detection, installation, and onboarding in one step.

Installer script

Downloads the CLI, installs it globally via npm, and launches the onboarding wizard.

macOS / Linux / WSL2

curl -fsSL https://opensoul.ai/install.sh | bash

Windows (PowerShell)

iwr -useb https://opensoul.ai/install.ps1 | iex

That's it — the script handles Node detection, installation, and onboarding.

To skip onboarding and just install the binary:

macOS / Linux / WSL2

curl -fsSL https://opensoul.ai/install.sh | bash -s -- --no-onboard

Windows (PowerShell)

& ([scriptblock]::Create((iwr -useb https://opensoul.ai/install.ps1))) -NoOnboard

For all flags, env vars, and CI/automation options, see Installer internals.

npm / pnpm

If you already have Node 22+ and prefer to manage the install yourself:

npm

npm install -g opensoul@latest
opensoul onboard --install-daemon

sharp build errors?

If you have libvips installed globally (common on macOS via Homebrew) and sharp fails, force prebuilt binaries:

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g opensoul@latest

If you see sharp: Please add node-gyp to your dependencies, either install build tooling (macOS: Xcode CLT + npm install -g node-gyp) or use the env var above.

pnpm

pnpm add -g opensoul@latest
pnpm approve-builds -g        # approve opensoul, node-llama-cpp, sharp, etc.
opensoul onboard --install-daemon

Note: pnpm requires explicit approval for packages with build scripts. After the first install shows the "Ignored build scripts" warning, run pnpm approve-builds -g and select the listed packages.