Install Apus, run onboarding, and chat with your AI assistant in about 5 minutes. By the end you will have a running Gateway, configured auth, and a working chat session.

What you need

Check your Node version with node --version. Windows users: the native Windows Hub app is the easiest desktop path. The PowerShell installer and WSL2 Gateway paths are also supported. See Windows. Need to install Node? See Node setup.

Try it in one command

npx apus@latest

On a fresh install, choose Quick start after a one-line pointer to the security guide. That is the only onboarding prompt when usable AI access is already available: Apus finds an existing Claude Code or Codex CLI login or API key, verifies it with a real completion, saves the config, and opens the web dashboard.

The Gateway runs in this terminal until you press Ctrl+C; your config stays saved. If no detected route works, onboarding opens manual provider setup. Choose Custom setup to walk through all guided options instead.

To keep the Gateway running in the background later, install the CLI below and run apus gateway install. Run apus for the TUI or apus dashboard to reopen the web UI.

Quick setup

Install Apus

macOS / Linux

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

src="/assets/install-script.svg" alt="Install Script Process" className="rounded-lg" />

Windows (PowerShell)

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

Other install methods (Docker, Nix, npm): [Install](/install).

Complete onboarding

The installer starts the guided onboarding wizard automatically. Choose
**Quick start** to reuse detected AI access and open the dashboard, or
**Custom setup** for the full guided flow. Provider sign-in and optional
setup can take longer. Return later with `apus configure` for
additional settings. `apus onboard --classic` opens the classic
step-by-step wizard instead.

See [Onboarding (CLI)](/start/wizard) for the full reference.

Install the Gateway service

Quick start keeps the Gateway in the foreground of this terminal. The next
steps need it running in the background. Press **Ctrl+C** to stop the
foreground Gateway, then install the service:

```bash
apus gateway install
```

This installs a LaunchAgent on macOS, a systemd user unit on Linux and
WSL2, or a Scheduled Task on native Windows (with a per-user
Startup-folder login item as the fallback if task creation is denied).
Your config stays saved across the stop and the install.

Verify the Gateway is running

```bash
apus gateway status
```

You should see the Gateway listening on port 18789.

Open the dashboard

```bash
apus dashboard
```

This opens the Control UI in your browser. If it loads, everything is working.

Send your first message

Type a message in the Control UI chat and you should get an AI reply.

Want to chat from your phone instead? The fastest channel to set up is
[Telegram](/channels/telegram) (just a bot token). See [Channels](/channels)
for all options.
Advanced: mount a custom Control UI build

If you maintain a localized or customized dashboard build, point gateway.controlUi.root to a directory that contains your built static assets and index.html.

mkdir -p "$HOME/.apus/control-ui-custom"
# Copy your built static files into that directory.

Then set:

{
  "gateway": {
    "controlUi": {
      "enabled": true,
      "root": "${HOME}/.apus/control-ui-custom"
    }
  }
}

Restart the gateway and reopen the dashboard:

apus gateway restart
apus dashboard

If setup does not work

One command turns the current state of your install into a diagnosis you can act on:

apus triage

It runs read-only health checks, writes a sanitized prompt describing what it found, and then offers to hand that prompt to a coding agent it detects on your machine — Claude Code, Codex CLI, or the built-in Apus agent — so the agent starts with the diagnosis already loaded. Pick "just print the commands" if you would rather run the handoff yourself.

Nothing leaves your machine until you choose an agent, and secrets, tokens, raw chat payloads, and raw logs are excluded from the prompt.

To read the findings yourself instead, run apus doctor. For symptom-first routes, see Troubleshooting.

What to do next

Connect a channel

Discord, Feishu, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo, and more.

Pairing and safety

Control who can message your agent.

Configure the Gateway

Models, tools, sandbox, and advanced settings.

Browse tools

Browser, exec, web search, skills, and plugins.
Advanced: environment variables

If you run Apus as a service account or want custom paths:

  • APUS_HOME — home directory for internal path resolution
  • APUS_STATE_DIR — override the state directory
  • APUS_CONFIG_PATH — override the config file path

Full reference: Environment variables.

Related