@quantumclaw/quantumclaw 2026.3.22

package/docs/install/index.md

@@ -0,0 +1,183 @@
+---
+summary: "Install QuantumClaw — installer script, npm/pnpm, from source, Docker, and more"
+read_when:
+  - 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
+title: "Install"
+---
+
+# Install
+
+## Recommended: installer script
+
+The fastest way to install. It detects your OS, installs Node if needed, installs QuantumClaw, and launches onboarding.
+
+<Tabs>
+  <Tab title="macOS / Linux / WSL2">
+    ```bash
+    curl -fsSL https://quantumclaw.ai/install.sh | bash
+    ```
+  </Tab>
+  <Tab title="Windows (PowerShell)">
+    ```powershell
+    iwr -useb https://quantumclaw.ai/install.ps1 | iex
+    ```
+  </Tab>
+</Tabs>
+
+To install without running onboarding:
+
+<Tabs>
+  <Tab title="macOS / Linux / WSL2">
+    ```bash
+    curl -fsSL https://quantumclaw.ai/install.sh | bash -s -- --no-onboard
+    ```
+  </Tab>
+  <Tab title="Windows (PowerShell)">
+    ```powershell
+    & ([scriptblock]::Create((iwr -useb https://quantumclaw.ai/install.ps1))) -NoOnboard
+    ```
+  </Tab>
+</Tabs>
+
+For all flags and CI/automation options, see [Installer internals](/install/installer).
+
+## System requirements
+
+- **Node 24** (recommended) or Node 22.16+ — the installer script handles this automatically
+- **macOS, Linux, or Windows** — both native Windows and WSL2 are supported; WSL2 is more stable. See [Windows](/platforms/windows).
+- `pnpm` is only needed if you build from source
+
+## Alternative install methods
+
+### npm or pnpm
+
+If you already manage Node yourself:
+
+<Tabs>
+  <Tab title="npm">
+    ```bash
+    npm install -g quantumclaw@latest
+    quantumclaw onboard --install-daemon
+    ```
+  </Tab>
+  <Tab title="pnpm">
+    ```bash
+    pnpm add -g quantumclaw@latest
+    pnpm approve-builds -g
+    quantumclaw onboard --install-daemon
+    ```
+
+    <Note>
+    pnpm requires explicit approval for packages with build scripts. Run `pnpm approve-builds -g` after the first install.
+    </Note>
+
+  </Tab>
+</Tabs>
+
+<Accordion title="Troubleshooting: sharp build errors (npm)">
+  If `sharp` fails due to a globally installed libvips:
+
+```bash
+SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g quantumclaw@latest
+```
+
+</Accordion>
+
+### From source
+
+For contributors or anyone who wants to run from a local checkout:
+
+```bash
+git clone https://github.com/quantumclaw/quantumclaw.git
+cd quantumclaw
+pnpm install && pnpm ui:build && pnpm build
+pnpm link --global
+quantumclaw onboard --install-daemon
+```
+
+Or skip the link and use `pnpm quantumclaw ...` from inside the repo. See [Setup](/start/setup) for full development workflows.
+
+### Install from GitHub main
+
+```bash
+npm install -g github:quantumclaw/quantumclaw#main
+```
+
+### Containers and package managers
+
+<CardGroup cols={2}>
+  <Card title="Docker" href="/install/docker" icon="container">
+    Containerized or headless deployments.
+  </Card>
+  <Card title="Podman" href="/install/podman" icon="container">
+    Rootless container alternative to Docker.
+  </Card>
+  <Card title="Nix" href="/install/nix" icon="snowflake">
+    Declarative install via Nix flake.
+  </Card>
+  <Card title="Ansible" href="/install/ansible" icon="server">
+    Automated fleet provisioning.
+  </Card>
+  <Card title="Bun" href="/install/bun" icon="zap">
+    CLI-only usage via the Bun runtime.
+  </Card>
+</CardGroup>
+
+## Verify the install
+
+```bash
+quantumclaw --version      # confirm the CLI is available
+quantumclaw doctor         # check for config issues
+quantumclaw gateway status # verify the Gateway is running
+```
+
+## Hosting and deployment
+
+Deploy QuantumClaw on a cloud server or VPS:
+
+<CardGroup cols={3}>
+  <Card title="VPS" href="/vps">Any Linux VPS</Card>
+  <Card title="Docker VM" href="/install/docker-vm-runtime">Shared Docker steps</Card>
+  <Card title="Kubernetes" href="/install/kubernetes">K8s</Card>
+  <Card title="Fly.io" href="/install/fly">Fly.io</Card>
+  <Card title="Hetzner" href="/install/hetzner">Hetzner</Card>
+  <Card title="GCP" href="/install/gcp">Google Cloud</Card>
+  <Card title="Azure" href="/install/azure">Azure</Card>
+  <Card title="Railway" href="/install/railway">Railway</Card>
+  <Card title="Render" href="/install/render">Render</Card>
+  <Card title="Northflank" href="/install/northflank">Northflank</Card>
+</CardGroup>
+
+## Update, migrate, or uninstall
+
+<CardGroup cols={3}>
+  <Card title="Updating" href="/install/updating" icon="refresh-cw">
+    Keep QuantumClaw up to date.
+  </Card>
+  <Card title="Migrating" href="/install/migrating" icon="arrow-right">
+    Move to a new machine.
+  </Card>
+  <Card title="Uninstall" href="/install/uninstall" icon="trash-2">
+    Remove QuantumClaw completely.
+  </Card>
+</CardGroup>
+
+## Troubleshooting: `quantumclaw` not found
+
+If the install succeeded but `quantumclaw` is not found in your terminal:
+
+```bash
+node -v           # Node installed?
+npm prefix -g     # Where are global packages?
+echo "$PATH"      # Is the global bin dir in PATH?
+```
+
+If `$(npm prefix -g)/bin` is not in your `$PATH`, add it to your shell startup file (`~/.zshrc` or `~/.bashrc`):
+
+```bash
+export PATH="$(npm prefix -g)/bin:$PATH"
+```
+
+Then open a new terminal. See [Node setup](/install/node) for more details.

package/docs/install/installer.md

@@ -0,0 +1,415 @@
+---
+summary: "How the installer scripts work (install.sh, install-cli.sh, install.ps1), flags, and automation"
+read_when:
+  - You want to understand `quantumclaw.ai/install.sh`
+  - You want to automate installs (CI / headless)
+  - You want to install from a GitHub checkout
+title: "Installer Internals"
+---
+
+# Installer internals
+
+QuantumClaw ships three installer scripts, served from `quantumclaw.ai`.
+
+| Script                             | Platform             | What it does                                                                                 |
+| ---------------------------------- | -------------------- | -------------------------------------------------------------------------------------------- |
+| [`install.sh`](#installsh)         | macOS / Linux / WSL  | Installs Node if needed, installs QuantumClaw via npm (default) or git, and can run onboarding. |
+| [`install-cli.sh`](#install-clish) | macOS / Linux / WSL  | Installs Node + QuantumClaw into a local prefix (`~/.quantumclaw`). No root required.              |
+| [`install.ps1`](#installps1)       | Windows (PowerShell) | Installs Node if needed, installs QuantumClaw via npm (default) or git, and can run onboarding. |
+
+## Quick commands
+
+<Tabs>
+  <Tab title="install.sh">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://quantumclaw.ai/install.sh | bash
+    ```
+
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://quantumclaw.ai/install.sh | bash -s -- --help
+    ```
+
+  </Tab>
+  <Tab title="install-cli.sh">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://quantumclaw.ai/install-cli.sh | bash
+    ```
+
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://quantumclaw.ai/install-cli.sh | bash -s -- --help
+    ```
+
+  </Tab>
+  <Tab title="install.ps1">
+    ```powershell
+    iwr -useb https://quantumclaw.ai/install.ps1 | iex
+    ```
+
+    ```powershell
+    & ([scriptblock]::Create((iwr -useb https://quantumclaw.ai/install.ps1))) -Tag beta -NoOnboard -DryRun
+    ```
+
+  </Tab>
+</Tabs>
+
+<Note>
+If install succeeds but `quantumclaw` is not found in a new terminal, see [Node.js troubleshooting](/install/node#troubleshooting).
+</Note>
+
+---
+
+## install.sh
+
+<Tip>
+Recommended for most interactive installs on macOS/Linux/WSL.
+</Tip>
+
+### Flow (install.sh)
+
+<Steps>
+  <Step title="Detect OS">
+    Supports macOS and Linux (including WSL). If macOS is detected, installs Homebrew if missing.
+  </Step>
+  <Step title="Ensure Node.js 24 by default">
+    Checks Node version and installs Node 24 if needed (Homebrew on macOS, NodeSource setup scripts on Linux apt/dnf/yum). QuantumClaw still supports Node 22 LTS, currently `22.16+`, for compatibility.
+  </Step>
+  <Step title="Ensure Git">
+    Installs Git if missing.
+  </Step>
+  <Step title="Install QuantumClaw">
+    - `npm` method (default): global npm install
+    - `git` method: clone/update repo, install deps with pnpm, build, then install wrapper at `~/.local/bin/quantumclaw`
+  </Step>
+  <Step title="Post-install tasks">
+    - Runs `quantumclaw doctor --non-interactive` on upgrades and git installs (best effort)
+    - Attempts onboarding when appropriate (TTY available, onboarding not disabled, and bootstrap/config checks pass)
+    - Defaults `SHARP_IGNORE_GLOBAL_LIBVIPS=1`
+  </Step>
+</Steps>
+
+### Source checkout detection
+
+If run inside an QuantumClaw checkout (`package.json` + `pnpm-workspace.yaml`), the script offers:
+
+- use checkout (`git`), or
+- use global install (`npm`)
+
+If no TTY is available and no install method is set, it defaults to `npm` and warns.
+
+The script exits with code `2` for invalid method selection or invalid `--install-method` values.
+
+### Examples (install.sh)
+
+<Tabs>
+  <Tab title="Default">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://quantumclaw.ai/install.sh | bash
+    ```
+  </Tab>
+  <Tab title="Skip onboarding">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://quantumclaw.ai/install.sh | bash -s -- --no-onboard
+    ```
+  </Tab>
+  <Tab title="Git install">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://quantumclaw.ai/install.sh | bash -s -- --install-method git
+    ```
+  </Tab>
+  <Tab title="GitHub main via npm">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://quantumclaw.ai/install.sh | bash -s -- --version main
+    ```
+  </Tab>
+  <Tab title="Dry run">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://quantumclaw.ai/install.sh | bash -s -- --dry-run
+    ```
+  </Tab>
+</Tabs>
+
+<AccordionGroup>
+  <Accordion title="Flags reference">
+
+| Flag                                  | Description                                                |
+| ------------------------------------- | ---------------------------------------------------------- |
+| `--install-method npm\|git`           | Choose install method (default: `npm`). Alias: `--method`  |
+| `--npm`                               | Shortcut for npm method                                    |
+| `--git`                               | Shortcut for git method. Alias: `--github`                 |
+| `--version <version\|dist-tag\|spec>` | npm version, dist-tag, or package spec (default: `latest`) |
+| `--beta`                              | Use beta dist-tag if available, else fallback to `latest`  |
+| `--git-dir <path>`                    | Checkout directory (default: `~/quantumclaw`). Alias: `--dir` |
+| `--no-git-update`                     | Skip `git pull` for existing checkout                      |
+| `--no-prompt`                         | Disable prompts                                            |
+| `--no-onboard`                        | Skip onboarding                                            |
+| `--onboard`                           | Enable onboarding                                          |
+| `--dry-run`                           | Print actions without applying changes                     |
+| `--verbose`                           | Enable debug output (`set -x`, npm notice-level logs)      |
+| `--help`                              | Show usage (`-h`)                                          |
+
+  </Accordion>
+
+  <Accordion title="Environment variables reference">
+
+| Variable                                                | Description                                   |
+| ------------------------------------------------------- | --------------------------------------------- |
+| `QUANTUMCLAW_INSTALL_METHOD=git\|npm`                      | Install method                                |
+| `QUANTUMCLAW_VERSION=latest\|next\|main\|<semver>\|<spec>` | npm version, dist-tag, or package spec        |
+| `QUANTUMCLAW_BETA=0\|1`                                    | Use beta if available                         |
+| `QUANTUMCLAW_GIT_DIR=<path>`                               | Checkout directory                            |
+| `QUANTUMCLAW_GIT_UPDATE=0\|1`                              | Toggle git updates                            |
+| `QUANTUMCLAW_NO_PROMPT=1`                                  | Disable prompts                               |
+| `QUANTUMCLAW_NO_ONBOARD=1`                                 | Skip onboarding                               |
+| `QUANTUMCLAW_DRY_RUN=1`                                    | Dry run mode                                  |
+| `QUANTUMCLAW_VERBOSE=1`                                    | Debug mode                                    |
+| `QUANTUMCLAW_NPM_LOGLEVEL=error\|warn\|notice`             | npm log level                                 |
+| `SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1`                      | Control sharp/libvips behavior (default: `1`) |
+
+  </Accordion>
+</AccordionGroup>
+
+---
+
+## install-cli.sh
+
+<Info>
+Designed for environments where you want everything under a local prefix (default `~/.quantumclaw`) and no system Node dependency.
+</Info>
+
+### Flow (install-cli.sh)
+
+<Steps>
+  <Step title="Install local Node runtime">
+    Downloads a pinned supported Node LTS tarball (the version is embedded in the script and updated independently) to `<prefix>/tools/node-v<version>` and verifies SHA-256.
+  </Step>
+  <Step title="Ensure Git">
+    If Git is missing, attempts install via apt/dnf/yum on Linux or Homebrew on macOS.
+  </Step>
+  <Step title="Install QuantumClaw under prefix">
+    Installs with npm using `--prefix <prefix>`, then writes wrapper to `<prefix>/bin/quantumclaw`.
+  </Step>
+</Steps>
+
+### Examples (install-cli.sh)
+
+<Tabs>
+  <Tab title="Default">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://quantumclaw.ai/install-cli.sh | bash
+    ```
+  </Tab>
+  <Tab title="Custom prefix + version">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://quantumclaw.ai/install-cli.sh | bash -s -- --prefix /opt/quantumclaw --version latest
+    ```
+  </Tab>
+  <Tab title="Automation JSON output">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://quantumclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/quantumclaw
+    ```
+  </Tab>
+  <Tab title="Run onboarding">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://quantumclaw.ai/install-cli.sh | bash -s -- --onboard
+    ```
+  </Tab>
+</Tabs>
+
+<AccordionGroup>
+  <Accordion title="Flags reference">
+
+| Flag                   | Description                                                                     |
+| ---------------------- | ------------------------------------------------------------------------------- |
+| `--prefix <path>`      | Install prefix (default: `~/.quantumclaw`)                                         |
+| `--version <ver>`      | QuantumClaw version or dist-tag (default: `latest`)                                |
+| `--node-version <ver>` | Node version (default: `22.22.0`)                                               |
+| `--json`               | Emit NDJSON events                                                              |
+| `--onboard`            | Run `quantumclaw onboard` after install                                            |
+| `--no-onboard`         | Skip onboarding (default)                                                       |
+| `--set-npm-prefix`     | On Linux, force npm prefix to `~/.npm-global` if current prefix is not writable |
+| `--help`               | Show usage (`-h`)                                                               |
+
+  </Accordion>
+
+  <Accordion title="Environment variables reference">
+
+| Variable                                    | Description                                                                       |
+| ------------------------------------------- | --------------------------------------------------------------------------------- |
+| `QUANTUMCLAW_PREFIX=<path>`                    | Install prefix                                                                    |
+| `QUANTUMCLAW_VERSION=<ver>`                    | QuantumClaw version or dist-tag                                                      |
+| `QUANTUMCLAW_NODE_VERSION=<ver>`               | Node version                                                                      |
+| `QUANTUMCLAW_NO_ONBOARD=1`                     | Skip onboarding                                                                   |
+| `QUANTUMCLAW_NPM_LOGLEVEL=error\|warn\|notice` | npm log level                                                                     |
+| `QUANTUMCLAW_GIT_DIR=<path>`                   | Legacy cleanup lookup path (used when removing old `Peekaboo` submodule checkout) |
+| `SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1`          | Control sharp/libvips behavior (default: `1`)                                     |
+
+  </Accordion>
+</AccordionGroup>
+
+---
+
+## install.ps1
+
+### Flow (install.ps1)
+
+<Steps>
+  <Step title="Ensure PowerShell + Windows environment">
+    Requires PowerShell 5+.
+  </Step>
+  <Step title="Ensure Node.js 24 by default">
+    If missing, attempts install via winget, then Chocolatey, then Scoop. Node 22 LTS, currently `22.16+`, remains supported for compatibility.
+  </Step>
+  <Step title="Install QuantumClaw">
+    - `npm` method (default): global npm install using selected `-Tag`
+    - `git` method: clone/update repo, install/build with pnpm, and install wrapper at `%USERPROFILE%\.local\bin\quantumclaw.cmd`
+  </Step>
+  <Step title="Post-install tasks">
+    Adds needed bin directory to user PATH when possible, then runs `quantumclaw doctor --non-interactive` on upgrades and git installs (best effort).
+  </Step>
+</Steps>
+
+### Examples (install.ps1)
+
+<Tabs>
+  <Tab title="Default">
+    ```powershell
+    iwr -useb https://quantumclaw.ai/install.ps1 | iex
+    ```
+  </Tab>
+  <Tab title="Git install">
+    ```powershell
+    & ([scriptblock]::Create((iwr -useb https://quantumclaw.ai/install.ps1))) -InstallMethod git
+    ```
+  </Tab>
+  <Tab title="GitHub main via npm">
+    ```powershell
+    & ([scriptblock]::Create((iwr -useb https://quantumclaw.ai/install.ps1))) -Tag main
+    ```
+  </Tab>
+  <Tab title="Custom git directory">
+    ```powershell
+    & ([scriptblock]::Create((iwr -useb https://quantumclaw.ai/install.ps1))) -InstallMethod git -GitDir "C:\quantumclaw"
+    ```
+  </Tab>
+  <Tab title="Dry run">
+    ```powershell
+    & ([scriptblock]::Create((iwr -useb https://quantumclaw.ai/install.ps1))) -DryRun
+    ```
+  </Tab>
+  <Tab title="Debug trace">
+    ```powershell
+    # install.ps1 has no dedicated -Verbose flag yet.
+    Set-PSDebug -Trace 1
+    & ([scriptblock]::Create((iwr -useb https://quantumclaw.ai/install.ps1))) -NoOnboard
+    Set-PSDebug -Trace 0
+    ```
+  </Tab>
+</Tabs>
+
+<AccordionGroup>
+  <Accordion title="Flags reference">
+
+| Flag                        | Description                                                |
+| --------------------------- | ---------------------------------------------------------- |
+| `-InstallMethod npm\|git`   | Install method (default: `npm`)                            |
+| `-Tag <tag\|version\|spec>` | npm dist-tag, version, or package spec (default: `latest`) |
+| `-GitDir <path>`            | Checkout directory (default: `%USERPROFILE%\quantumclaw`)     |
+| `-NoOnboard`                | Skip onboarding                                            |
+| `-NoGitUpdate`              | Skip `git pull`                                            |
+| `-DryRun`                   | Print actions only                                         |
+
+  </Accordion>
+
+  <Accordion title="Environment variables reference">
+
+| Variable                           | Description        |
+| ---------------------------------- | ------------------ |
+| `QUANTUMCLAW_INSTALL_METHOD=git\|npm` | Install method     |
+| `QUANTUMCLAW_GIT_DIR=<path>`          | Checkout directory |
+| `QUANTUMCLAW_NO_ONBOARD=1`            | Skip onboarding    |
+| `QUANTUMCLAW_GIT_UPDATE=0`            | Disable git pull   |
+| `QUANTUMCLAW_DRY_RUN=1`               | Dry run mode       |
+
+  </Accordion>
+</AccordionGroup>
+
+<Note>
+If `-InstallMethod git` is used and Git is missing, the script exits and prints the Git for Windows link.
+</Note>
+
+---
+
+## CI and automation
+
+Use non-interactive flags/env vars for predictable runs.
+
+<Tabs>
+  <Tab title="install.sh (non-interactive npm)">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://quantumclaw.ai/install.sh | bash -s -- --no-prompt --no-onboard
+    ```
+  </Tab>
+  <Tab title="install.sh (non-interactive git)">
+    ```bash
+    QUANTUMCLAW_INSTALL_METHOD=git QUANTUMCLAW_NO_PROMPT=1 \
+      curl -fsSL --proto '=https' --tlsv1.2 https://quantumclaw.ai/install.sh | bash
+    ```
+  </Tab>
+  <Tab title="install-cli.sh (JSON)">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://quantumclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/quantumclaw
+    ```
+  </Tab>
+  <Tab title="install.ps1 (skip onboarding)">
+    ```powershell
+    & ([scriptblock]::Create((iwr -useb https://quantumclaw.ai/install.ps1))) -NoOnboard
+    ```
+  </Tab>
+</Tabs>
+
+---
+
+## Troubleshooting
+
+<AccordionGroup>
+  <Accordion title="Why is Git required?">
+    Git is required for `git` install method. For `npm` installs, Git is still checked/installed to avoid `spawn git ENOENT` failures when dependencies use git URLs.
+  </Accordion>
+
+  <Accordion title="Why does npm hit EACCES on Linux?">
+    Some Linux setups point npm global prefix to root-owned paths. `install.sh` can switch prefix to `~/.npm-global` and append PATH exports to shell rc files (when those files exist).
+  </Accordion>
+
+  <Accordion title="sharp/libvips issues">
+    The scripts default `SHARP_IGNORE_GLOBAL_LIBVIPS=1` to avoid sharp building against system libvips. To override:
+
+    ```bash
+    SHARP_IGNORE_GLOBAL_LIBVIPS=0 curl -fsSL --proto '=https' --tlsv1.2 https://quantumclaw.ai/install.sh | bash
+    ```
+
+  </Accordion>
+
+  <Accordion title='Windows: "npm error spawn git / ENOENT"'>
+    Install Git for Windows, reopen PowerShell, rerun installer.
+  </Accordion>
+
+  <Accordion title='Windows: "quantumclaw is not recognized"'>
+    Run `npm config get prefix` and add that directory to your user PATH (no `\bin` suffix needed on Windows), then reopen PowerShell.
+  </Accordion>
+
+  <Accordion title="Windows: how to get verbose installer output">
+    `install.ps1` does not currently expose a `-Verbose` switch.
+    Use PowerShell tracing for script-level diagnostics:
+
+    ```powershell
+    Set-PSDebug -Trace 1
+    & ([scriptblock]::Create((iwr -useb https://quantumclaw.ai/install.ps1))) -NoOnboard
+    Set-PSDebug -Trace 0
+    ```
+
+  </Accordion>
+
+  <Accordion title="quantumclaw not found after install">
+    Usually a PATH issue. See [Node.js troubleshooting](/install/node#troubleshooting).
+  </Accordion>
+</AccordionGroup>