bot/docs/install/index.md

summary, read_when, title

summary	read_when	title
Install HanzoBot — installer script, npm/pnpm, from source, Docker, and more	You need an install method other than the Getting Started quickstart You want to deploy to a cloud platform You need to update, migrate, or uninstall	Install

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

On Windows, we strongly recommend running HanzoBot under [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install).

Install methods

The **installer script** is the recommended way to install HanzoBot. It handles Node detection, installation, and onboarding in one step. For VPS/cloud hosts, avoid third-party "1-click" marketplace images when possible. Prefer a clean base OS image (for example Ubuntu LTS), then install HanzoBot yourself with the installer script. Downloads the CLI, installs it globally via npm, and launches the onboarding wizard.

<Tabs>
  <Tab title="macOS / Linux / WSL2">
    ```bash
    curl -fsSL https://hanzo-bot.ai/install.sh | bash
    ```
  </Tab>
  <Tab title="Windows (PowerShell)">
    ```powershell
    iwr -useb https://hanzo-bot.ai/install.ps1 | iex
    ```
  </Tab>
</Tabs>

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

To skip onboarding and just install the binary:

<Tabs>
  <Tab title="macOS / Linux / WSL2">
    ```bash
    curl -fsSL https://hanzo-bot.ai/install.sh | bash -s -- --no-onboard
    ```
  </Tab>
  <Tab title="Windows (PowerShell)">
    ```powershell
    & ([scriptblock]::Create((iwr -useb https://hanzo-bot.ai/install.ps1))) -NoOnboard
    ```
  </Tab>
</Tabs>

For all flags, env vars, and CI/automation options, see [Installer internals](/install/installer).

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

<Tabs>
  <Tab title="npm">
    ```bash
    npm install -g hanzo-bot@latest
    hanzo-bot onboard --install-daemon
    ```

    <Accordion title="sharp build errors?">
      If you have libvips installed globally (common on macOS via Homebrew) and `sharp` fails, force prebuilt binaries:

      ```bash
      SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g hanzo-bot@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.
    </Accordion>
  </Tab>
  <Tab title="pnpm">
    ```bash
    pnpm add -g hanzo-bot@latest
    pnpm approve-builds -g        # approve hanzo-bot, node-llama-cpp, sharp, etc.
    hanzo-bot 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.
    </Note>
  </Tab>
</Tabs>

For contributors or anyone who wants to run from a local checkout.

<Steps>
  <Step title="Clone and build">
    Clone the [HanzoBot repo](https://github.com/hanzo-bot/hanzo-bot) and build:

    ```bash
    git clone https://github.com/hanzo-bot/hanzo-bot.git
    cd hanzo-bot
    pnpm install
    pnpm ui:build
    pnpm build
    ```
  </Step>
  <Step title="Link the CLI">
    Make the `hanzo-bot` command available globally:

    ```bash
    pnpm link --global
    ```

    Alternatively, skip the link and run commands via `pnpm hanzo-bot ...` from inside the repo.
  </Step>
  <Step title="Run onboarding">
    ```bash
    hanzo-bot onboard --install-daemon
    ```
  </Step>
</Steps>

For deeper development workflows, see [Setup](/start/setup).

Other install methods

Containerized or headless deployments. Rootless container: run `setup-podman.sh` once, then the launch script. Declarative install via Nix. Automated fleet provisioning. CLI-only usage via the Bun runtime.

After install

Verify everything is working:

hanzo-bot doctor         # check for config issues
hanzo-bot status         # gateway status
hanzo-bot dashboard      # open the browser UI

If you need custom runtime paths, use:

• BOT_HOME for home-directory based internal paths
• BOT_STATE_DIR for mutable state location
• BOT_CONFIG_PATH for config file location

See Environment vars for precedence and full details.

Troubleshooting: hanzo-bot not found

Quick diagnosis:

node -v
npm -v
npm prefix -g
echo "$PATH"

If $(npm prefix -g)/bin (macOS/Linux) or $(npm prefix -g) (Windows) is not in your $PATH, your shell can't find global npm binaries (including hanzo-bot).

Fix — add it to your shell startup file (~/.zshrc or ~/.bashrc):

export PATH="$(npm prefix -g)/bin:$PATH"

On Windows, add the output of npm prefix -g to your PATH.

Then open a new terminal (or rehash in zsh / hash -r in bash).

Update / uninstall

Keep HanzoBot up to date. Move to a new machine. Remove HanzoBot completely.