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

# Onboarding (CLI)

# Onboarding (CLI)

CLI onboarding is the **recommended** way to set up Agdi on macOS,
Linux, or Windows (via WSL2; strongly recommended).
It configures a local Gateway or a remote Gateway connection, plus channels, skills,
and workspace defaults in one guided flow.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
agdi onboard
```

> [!NOTE]
>
> Fastest first chat: open the Control UI (no channel setup needed). Run
> `agdi dashboard` and chat in the browser. Docs: [Dashboard](https://agdiai-597e782f.mintlify.site/web/dashboard.md).

To reconfigure later:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
agdi configure
agdi agents add <name>
```

> [!NOTE]
>
> `--json` does not imply non-interactive mode. For scripts, use `--non-interactive`.

> [!TIP]
>
> CLI onboarding includes a web search step where you can pick a provider
> (Perplexity, Brave, Gemini, Grok, or Kimi) and paste your API key so the agent
> can use `web_search`. You can also configure this later with
> `agdi configure --section web`. Docs: [Web tools](https://agdiai-597e782f.mintlify.site/tools/web.md).

## QuickStart vs Advanced

Onboarding starts with **QuickStart** (defaults) vs **Advanced** (full control).

> [tab] QuickStart (defaults)
>
> * Local gateway (loopback)
> * Workspace default (or existing workspace)
> * Gateway port **18789**
> * Gateway auth **Token** (auto‑generated, even on loopback)
> * Tool policy default for new local setups: `tools.profile: "coding"` (existing explicit profile is preserved)
> * DM isolation default: local onboarding writes `session.dmScope: "per-channel-peer"` when unset. Details: [CLI Setup Reference](https://agdiai-597e782f.mintlify.site/start/wizard-cli-reference.md#outputs-and-internals)
> * Tailscale exposure **Off**
> * Telegram + WhatsApp DMs default to **allowlist** (you'll be prompted for your phone number)

> [tab] Advanced (full control)
>
> * Exposes every step (mode, workspace, gateway, channels, daemon, skills).

## What onboarding configures

**Local mode (default)** walks you through these steps:

1. **Model/Auth** — choose any supported provider/auth flow (API key, OAuth, or setup-token), including Custom Provider
   (OpenAI-compatible, Anthropic-compatible, or Unknown auto-detect). Pick a default model.
   Security note: if this agent will run tools or process webhook/hooks content, prefer the strongest latest-generation model available and keep tool policy strict. Weaker/older tiers are easier to prompt-inject.
   For non-interactive runs, `--secret-input-mode ref` stores env-backed refs in auth profiles instead of plaintext API key values.
   In non-interactive `ref` mode, the provider env var must be set; passing inline key flags without that env var fails fast.
   In interactive runs, choosing secret reference mode lets you point at either an environment variable or a configured provider ref (`file` or `exec`), with a fast preflight validation before saving.
2. **Workspace** — Location for agent files (default `~/.agdi/workspace`). Seeds bootstrap files.
3. **Gateway** — Port, bind address, auth mode, Tailscale exposure.
   In interactive token mode, choose default plaintext token storage or opt into SecretRef.
   Non-interactive token SecretRef path: `--gateway-token-ref-env <ENV_VAR>`.
4. **Channels** — WhatsApp, Telegram, Discord, Google Chat, Mattermost, Signal, BlueBubbles, or iMessage.
5. **Daemon** — Installs a LaunchAgent (macOS) or systemd user unit (Linux/WSL2).
   If token auth requires a token and `gateway.auth.token` is SecretRef-managed, daemon install validates it but does not persist the resolved token into supervisor service environment metadata.
   If token auth requires a token and the configured token SecretRef is unresolved, daemon install is blocked with actionable guidance.
   If both `gateway.auth.token` and `gateway.auth.password` are configured and `gateway.auth.mode` is unset, daemon install is blocked until mode is set explicitly.
6. **Health check** — Starts the Gateway and verifies it's running.
7. **Skills** — Installs recommended skills and optional dependencies.

> [!NOTE]
>
> Re-running onboarding does **not** wipe anything unless you explicitly choose **Reset** (or pass `--reset`).
> CLI `--reset` defaults to config, credentials, and sessions; use `--reset-scope full` to include workspace.
> If the config is invalid or contains legacy keys, onboarding asks you to run `agdi doctor` first.

**Remote mode** only configures the local client to connect to a Gateway elsewhere.
It does **not** install or change anything on the remote host.

## Add another agent

Use `agdi agents add <name>` to create a separate agent with its own workspace,
sessions, and auth profiles. Running without `--workspace` launches onboarding.

What it sets:

* `agents.list[].name`
* `agents.list[].workspace`
* `agents.list[].agentDir`

Notes:

* Default workspaces follow `~/.agdi/workspace-<agentId>`.
* Add `bindings` to route inbound messages (onboarding can do this).
* Non-interactive flags: `--model`, `--agent-dir`, `--bind`, `--non-interactive`.

## Full reference

For detailed step-by-step breakdowns and config outputs, see
[CLI Setup Reference](https://agdiai-597e782f.mintlify.site/start/wizard-cli-reference.md).
For non-interactive examples, see [CLI Automation](https://agdiai-597e782f.mintlify.site/start/wizard-cli-automation.md).
For the deeper technical reference, including RPC details, see
[Onboarding Reference](https://agdiai-597e782f.mintlify.site/reference/wizard.md).

## Related docs

* CLI command reference: [`agdi onboard`](https://agdiai-597e782f.mintlify.site/cli/onboard)
* Onboarding overview: [Onboarding Overview](https://agdiai-597e782f.mintlify.site/start/onboarding-overview.md)
* macOS app onboarding: [Onboarding](https://agdiai-597e782f.mintlify.site/start/onboarding.md)
* Agent first-run ritual: [Agent Bootstrapping](https://agdiai-597e782f.mintlify.site/start/bootstrapping.md)


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