> ## 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.

# Install

# Install

## Recommended: installer script

The fastest way to install. It detects your OS, installs Node if needed, installs Agdi, and launches onboarding.

> [tab] macOS / Linux / WSL2
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> curl -fsSL https://agdi.ai/install.sh | bash
> ```

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

To install without running onboarding:

> [tab] macOS / Linux / WSL2
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> curl -fsSL https://agdi.ai/install.sh | bash -s -- --no-onboard
> ```

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

For all flags and CI/automation options, see [Installer internals](https://agdiai-597e782f.mintlify.site/install/installer.md).

## System requirements

* **Node 24** (recommended) or Node 22.14+ — the installer script handles this automatically
* **macOS, Linux, or Windows** — both native Windows and WSL2 are supported; WSL2 is more stable. See [Windows](https://agdiai-597e782f.mintlify.site/platforms/windows.md).
* `pnpm` is only needed if you build from source

## Alternative install methods

### npm or pnpm

If you already manage Node yourself:

> [tab] npm
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> npm install -g agdi@latest
> agdi onboard --install-daemon
> ```

> [tab] pnpm
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> pnpm add -g agdi@latest
> pnpm approve-builds -g
> agdi onboard --install-daemon
> ```
>
> > [!NOTE]
> >
> > pnpm requires explicit approval for packages with build scripts. Run `pnpm approve-builds -g` after the first install.

> [accordion] Troubleshooting: sharp build errors (npm)
>
> If `sharp` fails due to a globally installed libvips:
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g agdi@latest
> ```

### From source

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
git clone https://github.com/agdi/agdi.git
cd agdi
pnpm install && pnpm ui:build && pnpm build
pnpm link --global
agdi onboard --install-daemon
```

Or skip the link and use `pnpm agdi ...` from inside the repo. See [Setup](https://agdiai-597e782f.mintlify.site/start/setup.md) for full development workflows.

### Install from GitHub main

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
npm install -g github:agdi/agdi#main
```

### Containers and package managers

> [card] [Docker](https://agdiai-597e782f.mintlify.site/install/docker.md)
>
> Containerized or headless deployments.

> [card] [Podman](https://agdiai-597e782f.mintlify.site/install/podman.md)
>
> Rootless container alternative to Docker.

> [card] [Nix](https://agdiai-597e782f.mintlify.site/install/nix.md)
>
> Declarative install via Nix flake.

> [card] [Ansible](https://agdiai-597e782f.mintlify.site/install/ansible.md)
>
> Automated fleet provisioning.

> [card] [Bun](https://agdiai-597e782f.mintlify.site/install/bun.md)
>
> CLI-only usage via the Bun runtime.

## Verify the install

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
agdi --version      # confirm the CLI is available
agdi doctor         # check for config issues
agdi gateway status # verify the Gateway is running
```

## Hosting and deployment

Deploy Agdi on a cloud server or VPS:

> [card] [VPS](https://agdiai-597e782f.mintlify.site/vps.md)
>
> Any Linux VPS

> [card] [Docker VM](https://agdiai-597e782f.mintlify.site/install/docker-vm-runtime.md)
>
> Shared Docker steps

> [card] [Kubernetes](https://agdiai-597e782f.mintlify.site/install/kubernetes.md)
>
> K8s

> [card] [Fly.io](https://agdiai-597e782f.mintlify.site/install/fly.md)
>
> Fly.io

> [card] [Hetzner](https://agdiai-597e782f.mintlify.site/install/hetzner.md)
>
> Hetzner

> [card] [GCP](https://agdiai-597e782f.mintlify.site/install/gcp.md)
>
> Google Cloud

> [card] [Azure](https://agdiai-597e782f.mintlify.site/install/azure.md)
>
> Azure

> [card] [Railway](https://agdiai-597e782f.mintlify.site/install/railway.md)
>
> Railway

> [card] [Render](https://agdiai-597e782f.mintlify.site/install/render.md)
>
> Render

> [card] [Northflank](https://agdiai-597e782f.mintlify.site/install/northflank.md)
>
> Northflank

## Update, migrate, or uninstall

> [card] [Updating](https://agdiai-597e782f.mintlify.site/install/updating.md)
>
> Keep Agdi up to date.

> [card] [Migrating](https://agdiai-597e782f.mintlify.site/install/migrating.md)
>
> Move to a new machine.

> [card] [Uninstall](https://agdiai-597e782f.mintlify.site/install/uninstall.md)
>
> Remove Agdi completely.

## Troubleshooting: `agdi` not found

If the install succeeded but `agdi` is not found in your terminal:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
export PATH="$(npm prefix -g)/bin:$PATH"
```

Then open a new terminal. See [Node setup](https://agdiai-597e782f.mintlify.site/install/node.md) for more details.


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