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 OpenAEON under WSL2.

Install methods

The installer script is the recommended way to install OpenAEON. 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 OpenAEON yourself with the installer script.

Installer script

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

macOS / Linux / WSL2

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

Windows (PowerShell)

iwr -useb https://openaeon.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://openaeon.ai/install.sh | bash -s -- --no-onboard

Windows (PowerShell)

& ([scriptblock]::Create((iwr -useb https://openaeon.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 openaeon@latest
openaeon 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 openaeon@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 openaeon@latest
pnpm approve-builds -g        # approve openaeon, node-llama-cpp, sharp, etc.
openaeon onboard --install-daemon

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.

From source

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

1. Clone and build

   Clone the OpenAEON repo and build:

   git clone https://github.com/openaeon/openaeon.git
   cd openaeon
   pnpm install
   pnpm ui:build
   pnpm build
   
2. Link the CLI

   Make the openaeon command available globally:

   pnpm link --global
   

   Alternatively, skip the link and run commands via pnpm openaeon ... from inside the repo.

3. Run onboarding

   openaeon onboard --install-daemon
   

For deeper development workflows, see Setup.

Other install methods

Docker

Containerized or headless deployments.

Podman

Rootless container: run setup-podman.sh once, then the launch script.

Nix

Declarative install via Nix.

Ansible

Automated fleet provisioning.

Bun

CLI-only usage via the Bun runtime.

After install

Verify everything is working:

openaeon doctor         # check for config issues
openaeon status         # gateway status
openaeon dashboard      # open the browser UI

If you need custom runtime paths, use:

• OPENAEON_HOME for home-directory based internal paths
• OPENAEON_STATE_DIR for mutable state location
• OPENAEON_CONFIG_PATH for config file location

See Environment vars for precedence and full details.

Troubleshooting: openaeon not found

PATH diagnosis and fix

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 openaeon).

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

Updating

Keep OpenAEON up to date.

Migrating

Move to a new machine.

Uninstall

Remove OpenAEON completely.