> ## Documentation Index
> Fetch the complete documentation index at: https://agdiai-597e782f.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Installer Internals

# Installer internals

Agdi ships three installer scripts, served from `agdi.ai`.

| Script | Platform | What it does |
| - | - | - |
| [`install.sh`](#installsh) | macOS / Linux / WSL | Installs Node if needed, installs Agdi via npm (default) or git, and can run onboarding. |
| [`install-cli.sh`](#install-clish) | macOS / Linux / WSL | Installs Node + Agdi into a local prefix (`~/.agdi`). No root required. |
| [`install.ps1`](#installps1) | Windows (PowerShell) | Installs Node if needed, installs Agdi via npm (default) or git, and can run onboarding. |

## Quick commands

> [tab] install.sh
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> curl -fsSL --proto '=https' --tlsv1.2 https://agdi.ai/install.sh | bash
> ```
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> curl -fsSL --proto '=https' --tlsv1.2 https://agdi.ai/install.sh | bash -s -- --help
> ```

> [tab] install-cli.sh
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> curl -fsSL --proto '=https' --tlsv1.2 https://agdi.ai/install-cli.sh | bash
> ```
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> curl -fsSL --proto '=https' --tlsv1.2 https://agdi.ai/install-cli.sh | bash -s -- --help
> ```

> [tab] install.ps1
>
> ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
> iwr -useb https://agdi.ai/install.ps1 | iex
> ```
>
> ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
> & ([scriptblock]::Create((iwr -useb https://agdi.ai/install.ps1))) -Tag beta -NoOnboard -DryRun
> ```

> [!NOTE]
>
> If install succeeds but `agdi` is not found in a new terminal, see [Node.js troubleshooting](https://agdiai-597e782f.mintlify.site/install/node.md#troubleshooting).

***

## install.sh

> [!TIP]
>
> Recommended for most interactive installs on macOS/Linux/WSL.

### Flow (install.sh)

**1. Detect OS**

Supports macOS and Linux (including WSL). If macOS is detected, installs Homebrew if missing.

**2. 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). Agdi still supports Node 22 LTS, currently `22.14+`, for compatibility.

**3. Ensure Git**

Installs Git if missing.

**4. Install Agdi**

* `npm` method (default): global npm install
* `git` method: clone/update repo, install deps with pnpm, build, then install wrapper at `~/.local/bin/agdi`

**5. Post-install tasks**

* Runs `agdi 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`

### Source checkout detection

If run inside an Agdi 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)

> [tab] Default
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> curl -fsSL --proto '=https' --tlsv1.2 https://agdi.ai/install.sh | bash
> ```

> [tab] Skip onboarding
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> curl -fsSL --proto '=https' --tlsv1.2 https://agdi.ai/install.sh | bash -s -- --no-onboard
> ```

> [tab] Git install
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> curl -fsSL --proto '=https' --tlsv1.2 https://agdi.ai/install.sh | bash -s -- --install-method git
> ```

> [tab] GitHub main via npm
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> curl -fsSL --proto '=https' --tlsv1.2 https://agdi.ai/install.sh | bash -s -- --version main
> ```

> [tab] Dry run
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> curl -fsSL --proto '=https' --tlsv1.2 https://agdi.ai/install.sh | bash -s -- --dry-run
> ```

> [accordion] 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: `~/agdi`). 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] Environment variables reference
>
> | Variable | Description |
> | - | - |
> | `OPENCLAW_INSTALL_METHOD=git\|npm` | Install method |
> | `OPENCLAW_VERSION=latest\|next\|main\|<semver>\|<spec>` | npm version, dist-tag, or package spec |
> | `OPENCLAW_BETA=0\|1` | Use beta if available |
> | `OPENCLAW_GIT_DIR=<path>` | Checkout directory |
> | `OPENCLAW_GIT_UPDATE=0\|1` | Toggle git updates |
> | `OPENCLAW_NO_PROMPT=1` | Disable prompts |
> | `OPENCLAW_NO_ONBOARD=1` | Skip onboarding |
> | `OPENCLAW_DRY_RUN=1` | Dry run mode |
> | `OPENCLAW_VERBOSE=1` | Debug mode |
> | `OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice` | npm log level |
> | `SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1` | Control sharp/libvips behavior (default: `1`) |

***

## install-cli.sh

> [!NOTE]
>
> Designed for environments where you want everything under a local prefix (default `~/.agdi`) and no system Node dependency.

### Flow (install-cli.sh)

**1. 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.

**2. Ensure Git**

If Git is missing, attempts install via apt/dnf/yum on Linux or Homebrew on macOS.

**3. Install Agdi under prefix**

Installs with npm using `--prefix <prefix>`, then writes wrapper to `<prefix>/bin/agdi`.

### Examples (install-cli.sh)

> [tab] Default
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> curl -fsSL --proto '=https' --tlsv1.2 https://agdi.ai/install-cli.sh | bash
> ```

> [tab] Custom prefix + version
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> curl -fsSL --proto '=https' --tlsv1.2 https://agdi.ai/install-cli.sh | bash -s -- --prefix /opt/agdi --version latest
> ```

> [tab] Automation JSON output
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> curl -fsSL --proto '=https' --tlsv1.2 https://agdi.ai/install-cli.sh | bash -s -- --json --prefix /opt/agdi
> ```

> [tab] Run onboarding
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> curl -fsSL --proto '=https' --tlsv1.2 https://agdi.ai/install-cli.sh | bash -s -- --onboard
> ```

> [accordion] Flags reference
>
> | Flag | Description |
> | - | - |
> | `--prefix <path>` | Install prefix (default: `~/.agdi`) |
> | `--version <ver>` | Agdi version or dist-tag (default: `latest`) |
> | `--node-version <ver>` | Node version (default: `22.22.0`) |
> | `--json` | Emit NDJSON events |
> | `--onboard` | Run `agdi 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] Environment variables reference
>
> | Variable | Description |
> | - | - |
> | `OPENCLAW_PREFIX=<path>` | Install prefix |
> | `OPENCLAW_VERSION=<ver>` | Agdi version or dist-tag |
> | `OPENCLAW_NODE_VERSION=<ver>` | Node version |
> | `OPENCLAW_NO_ONBOARD=1` | Skip onboarding |
> | `OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice` | npm log level |
> | `OPENCLAW_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`) |

***

## install.ps1

### Flow (install.ps1)

**1. Ensure PowerShell + Windows environment**

Requires PowerShell 5+.

**2. Ensure Node.js 24 by default**

If missing, attempts install via winget, then Chocolatey, then Scoop. Node 22 LTS, currently `22.14+`, remains supported for compatibility.

**3. Install Agdi**

* `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\agdi.cmd`

**4. Post-install tasks**

Adds needed bin directory to user PATH when possible, then runs `agdi doctor --non-interactive` on upgrades and git installs (best effort).

### Examples (install.ps1)

> [tab] Default
>
> ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
> iwr -useb https://agdi.ai/install.ps1 | iex
> ```

> [tab] Git install
>
> ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
> & ([scriptblock]::Create((iwr -useb https://agdi.ai/install.ps1))) -InstallMethod git
> ```

> [tab] GitHub main via npm
>
> ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
> & ([scriptblock]::Create((iwr -useb https://agdi.ai/install.ps1))) -Tag main
> ```

> [tab] Custom git directory
>
> ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
> & ([scriptblock]::Create((iwr -useb https://agdi.ai/install.ps1))) -InstallMethod git -GitDir "C:\agdi"
> ```

> [tab] Dry run
>
> ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
> & ([scriptblock]::Create((iwr -useb https://agdi.ai/install.ps1))) -DryRun
> ```

> [tab] Debug trace
>
> ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
> # install.ps1 has no dedicated -Verbose flag yet.
> Set-PSDebug -Trace 1
> & ([scriptblock]::Create((iwr -useb https://agdi.ai/install.ps1))) -NoOnboard
> Set-PSDebug -Trace 0
> ```

> [accordion] 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%\agdi`) |
> | `-NoOnboard` | Skip onboarding |
> | `-NoGitUpdate` | Skip `git pull` |
> | `-DryRun` | Print actions only |

> [accordion] Environment variables reference
>
> | Variable | Description |
> | - | - |
> | `OPENCLAW_INSTALL_METHOD=git\|npm` | Install method |
> | `OPENCLAW_GIT_DIR=<path>` | Checkout directory |
> | `OPENCLAW_NO_ONBOARD=1` | Skip onboarding |
> | `OPENCLAW_GIT_UPDATE=0` | Disable git pull |
> | `OPENCLAW_DRY_RUN=1` | Dry run mode |

> [!NOTE]
>
> If `-InstallMethod git` is used and Git is missing, the script exits and prints the Git for Windows link.

***

## CI and automation

Use non-interactive flags/env vars for predictable runs.

> [tab] install.sh (non-interactive npm)
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> curl -fsSL --proto '=https' --tlsv1.2 https://agdi.ai/install.sh | bash -s -- --no-prompt --no-onboard
> ```

> [tab] install.sh (non-interactive git)
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> OPENCLAW_INSTALL_METHOD=git OPENCLAW_NO_PROMPT=1 \
>   curl -fsSL --proto '=https' --tlsv1.2 https://agdi.ai/install.sh | bash
> ```

> [tab] install-cli.sh (JSON)
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> curl -fsSL --proto '=https' --tlsv1.2 https://agdi.ai/install-cli.sh | bash -s -- --json --prefix /opt/agdi
> ```

> [tab] install.ps1 (skip onboarding)
>
> ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
> & ([scriptblock]::Create((iwr -useb https://agdi.ai/install.ps1))) -NoOnboard
> ```

***

## Troubleshooting

> [accordion] 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] 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] sharp/libvips issues
>
> The scripts default `SHARP_IGNORE_GLOBAL_LIBVIPS=1` to avoid sharp building against system libvips. To override:
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> SHARP_IGNORE_GLOBAL_LIBVIPS=0 curl -fsSL --proto '=https' --tlsv1.2 https://agdi.ai/install.sh | bash
> ```

> [accordion] Windows: "npm error spawn git / ENOENT"
>
> Install Git for Windows, reopen PowerShell, rerun installer.

> [accordion] Windows: "agdi 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] Windows: how to get verbose installer output
>
> `install.ps1` does not currently expose a `-Verbose` switch.
> Use PowerShell tracing for script-level diagnostics:
>
> ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
> Set-PSDebug -Trace 1
> & ([scriptblock]::Create((iwr -useb https://agdi.ai/install.ps1))) -NoOnboard
> Set-PSDebug -Trace 0
> ```

> [accordion] agdi not found after install
>
> Usually a PATH issue. See [Node.js troubleshooting](https://agdiai-597e782f.mintlify.site/install/node.md#troubleshooting).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.