System requirements

Download the desktop app

Prefer a normal app download over the CLI? Apus ships desktop companions:

Both desktop apps can provision a local Gateway during first-run setup, or connect to an existing remote Gateway.

Recommended: installer script

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

Windows desktop users can also install the native Windows Hub companion app, which includes setup, tray status, chat, node mode, and local MCP mode.

macOS / Linux / WSL2

```bash
curl -fsSL https://ami-docs.dev.apuscorp.com/install.sh | bash
```

Windows (PowerShell)

```powershell
iwr -useb https://ami-docs.dev.apuscorp.com/install.ps1 | iex
```

To install without running onboarding:

macOS / Linux / WSL2

```bash
curl -fsSL https://ami-docs.dev.apuscorp.com/install.sh | bash -s -- --no-onboard
```

Windows (PowerShell)

```powershell
& ([scriptblock]::Create((iwr -useb https://ami-docs.dev.apuscorp.com/install.ps1))) -NoOnboard
```

For all flags and CI/automation options, see Installer internals.

Alternative install methods

Local prefix installer (install-cli.sh)

Use this when you want Apus and Node kept under a local prefix such as ~/.apus, without depending on a system-wide Node install:

curl -fsSL https://ami-docs.dev.apuscorp.com/install-cli.sh | bash

It supports npm installs by default, plus git-checkout installs under the same prefix flow. Full reference: Installer internals.

Already installed? Switch between package and git installs with apus update --channel dev and apus update --channel stable. See Updating.

npm, pnpm, or bun

If you already manage Node yourself:

npm

On npm 12 or npm 11.16+:

```bash
npm install -g apus@latest --allow-scripts=apus
apus onboard --install-daemon
```

On npm 11.15 and earlier, use the same command without
`--allow-scripts=apus`.

npm 12 blocks unapproved package lifecycle scripts by default. The
`--allow-scripts=apus` option explicitly allows Apus's `preinstall`
and `postinstall` steps; without it, npm reports them as `blocked because
they are not covered by allowScripts`.

npm 11.16 accepts the option but otherwise only warns that the scripts are
`not yet covered by allowScripts` and still runs them. npm 11.15 and earlier
have neither the policy nor the option, so their command must be unflagged.
The `npm approve-scripts apus`
command suggested by npm 11.16 does not work for a global install — it fails
with `ENOMATCH  No installed packages match: apus`.

The hosted installer clears npm freshness filters such as `min-release-age`
for the Apus package install. If you install manually with npm, your own
npm policy still applies.

pnpm

```bash
pnpm add -g --allow-build=apus apus@latest
apus onboard --install-daemon
```

pnpm requires explicit approval for packages with build scripts. `approve-builds -g` is not supported for global installs, so pass `--allow-build=apus` on the `pnpm add -g` command instead.

bun

```bash
bun add -g --trust apus@latest
bun run --bun apus onboard --install-daemon --daemon-runtime bun
```

`--trust` allows Apus's package lifecycle scripts for this install. Bun
1.4 or newer can also run Apus's CLI, local agent, and Gateway. Node
remains the primary runtime, so the plain `apus` executable keeps its
Node shebang. `bun run --bun` forces the Bun runtime, while
`--daemon-runtime bun` installs the managed Gateway under Bun.

From source

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

git clone https://git.apuscorp.com/business/saas/erp/desktop-app/apusami.git
cd apus
corepack enable
pnpm install && pnpm build && pnpm ui:build
pnpm add --global "apus@link:$PWD"
apus onboard --install-daemon

pnpm add --global "apus@link:$PWD" links the CLI to this checkout without changing its package files. If pnpm reports that its global bin directory is not on PATH, run pnpm setup, reopen your shell, and retry.

Corepack selects the exact pnpm version from package.json (currently pnpm 12). If Corepack is unavailable, read that version from the checkout and install it explicitly:

pnpm_spec=$(node -p "require('./package.json').packageManager.split('+')[0]")
npm install -g "$pnpm_spec" --allow-scripts="$pnpm_spec"

The + suffix records Corepack's integrity hash and is not part of the npm package specifier. Keep npm install scripts and optional dependencies enabled so pnpm can provision its native executable.

Or skip the global install and use pnpm apus ... from inside the repo. See Setup for full development workflows.

Install from the GitHub main checkout

curl -fsSL --proto '=https' --tlsv1.2 https://ami-docs.dev.apuscorp.com/install.sh | bash -s -- --install-method git --version main

Containers and package managers

Ansible

Automated fleet provisioning.

Bun

Optional dependency installer and package-script runner.

Docker

Containerized or headless deployments.

Nix

Declarative install via Nix flake.

Podman

Rootless container alternative to Docker.

Verify the install

apus --version      # confirm the CLI is available
apus doctor         # check for config issues
apus gateway status # verify the Gateway is running

If you want managed startup after install:

Next: run onboarding and connect a channel

Getting started

Run onboarding, install the Gateway service, and open the dashboard.

Connect a channel

Message your agent from Telegram, Discord, Slack, WhatsApp, and more.

Hosting and deployment

Deploy Apus on a cloud server or VPS. See Linux server for the full provider picker (DigitalOcean, Hetzner, Hostinger, Fly.io, GCP, Azure, Railway, Northflank, Oracle Cloud, Raspberry Pi, and more), deploy declaratively on Render, or try the experimental Cloudflare Containers template.

Cloudflare

Experimental Worker + Container deployment.

Docker VM

Shared Docker steps.

Kubernetes

K8s deployment.

macOS VM

Isolated local or hosted macOS deployment.

Upstash Box

Managed Linux host with SSH-tunneled access.

VPS

Pick a provider.

Back up, update, migrate, or uninstall

Backups

Create, verify, and restore state archives.

Updating

Keep Apus up to date.

Migrating

Move to a new machine.

Uninstall

Remove Apus completely.

Troubleshooting: apus not found

Almost always a PATH issue: npm's global bin directory isn't on your shell's PATH. See Node.js troubleshooting for the full fix, including the Windows path.

node -v           # Node installed?
npm prefix -g     # Where are global packages?
echo "$PATH"      # Is the global bin dir in PATH?