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

# Onboarding Reference

This is the full reference for `agdi onboard`.
For a high-level overview, see [Onboarding (CLI)](https://agdiai-597e782f.mintlify.site/start/wizard.md).

## Flow details (local mode)

**1. Existing config detection**

* If `~/.agdi/agdi.json` exists, choose **Keep / Modify / Reset**.
* Re-running onboarding does **not** wipe anything unless you explicitly choose **Reset**
  (or pass `--reset`).
* CLI `--reset` defaults to `config+creds+sessions`; use `--reset-scope full`
  to also remove workspace.
* If the config is invalid or contains legacy keys, the wizard stops and asks
  you to run `agdi doctor` before continuing.
* Reset uses `trash` (never `rm`) and offers scopes:
  * Config only
  * Config + credentials + sessions
  * Full reset (also removes workspace)

**2. Model/Auth**

* **Anthropic API key**: uses `ANTHROPIC_API_KEY` if present or prompts for a key, then saves it for daemon use.
* **Anthropic OAuth (Claude Code CLI)**: on macOS onboarding checks Keychain item "Claude Code-credentials" (choose "Always Allow" so launchd starts don't block); on Linux/Windows it reuses `~/.claude/.credentials.json` if present.
* **Anthropic token (paste setup-token)**: run `claude setup-token` on any machine, then paste the token (you can name it; blank = default).
* **OpenAI Code (Codex) subscription (Codex CLI)**: if `~/.codex/auth.json` exists, onboarding can reuse it.
* **OpenAI Code (Codex) subscription (OAuth)**: browser flow; paste the `code#state`.
  * Sets `agents.defaults.model` to `openai-codex/gpt-5.2` when model is unset or `openai/*`.
* **OpenAI API key**: uses `OPENAI_API_KEY` if present or prompts for a key, then stores it in auth profiles.
* **xAI (Grok) API key**: prompts for `XAI_API_KEY` and configures xAI as a model provider.
* **OpenCode**: prompts for `OPENCODE_API_KEY` (or `OPENCODE_ZEN_API_KEY`, get it at [https://opencode.ai/auth](https://opencode.ai/auth)) and lets you pick the Zen or Go catalog.
* **Ollama**: prompts for the Ollama base URL, offers **Cloud + Local** or **Local** mode, discovers available models, and auto-pulls the selected local model when needed.
* More detail: [Ollama](https://agdiai-597e782f.mintlify.site/providers/ollama.md)
* **API key**: stores the key for you.
* **Vercel AI Gateway (multi-model proxy)**: prompts for `AI_GATEWAY_API_KEY`.
* More detail: [Vercel AI Gateway](https://agdiai-597e782f.mintlify.site/providers/vercel-ai-gateway.md)
* **Cloudflare AI Gateway**: prompts for Account ID, Gateway ID, and `CLOUDFLARE_AI_GATEWAY_API_KEY`.
* More detail: [Cloudflare AI Gateway](https://agdiai-597e782f.mintlify.site/providers/cloudflare-ai-gateway.md)
* **MiniMax**: config is auto-written; hosted default is `MiniMax-M2.7` and `MiniMax-M2.5` stays available.
* More detail: [MiniMax](https://agdiai-597e782f.mintlify.site/providers/minimax.md)
* **Synthetic (Anthropic-compatible)**: prompts for `SYNTHETIC_API_KEY`.
* More detail: [Synthetic](https://agdiai-597e782f.mintlify.site/providers/synthetic.md)
* **Moonshot (Kimi K2)**: config is auto-written.
* **Kimi Coding**: config is auto-written.
* More detail: [Moonshot AI (Kimi + Kimi Coding)](https://agdiai-597e782f.mintlify.site/providers/moonshot.md)
* **Skip**: no auth configured yet.
* Pick a default model from detected options (or enter provider/model manually). For best quality and lower prompt-injection risk, choose the strongest latest-generation model available in your provider stack.
* Onboarding runs a model check and warns if the configured model is unknown or missing auth.
* API key storage mode defaults to plaintext auth-profile values. Use `--secret-input-mode ref` to store env-backed refs instead (for example `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`).
* OAuth credentials live in `~/.agdi/credentials/oauth.json`; auth profiles live in `~/.agdi/agents/<agentId>/agent/auth-profiles.json` (API keys + OAuth).
* More detail: [/concepts/oauth](https://agdiai-597e782f.mintlify.site/concepts/oauth.md)

> [!NOTE]
>
> Headless/server tip: complete OAuth on a machine with a browser, then copy
> `~/.agdi/credentials/oauth.json` (or `$AGDI_STATE_DIR/credentials/oauth.json`) to the
> gateway host.

**3. Workspace**

* Default `~/.agdi/workspace` (configurable).
* Seeds the workspace files needed for the agent bootstrap ritual.
* Full workspace layout + backup guide: [Agent workspace](https://agdiai-597e782f.mintlify.site/concepts/agent-workspace.md)

**4. Gateway**

* Port, bind, auth mode, tailscale exposure.
* Auth recommendation: keep **Token** even for loopback so local WS clients must authenticate.
* In token mode, interactive setup offers:
  * **Generate/store plaintext token** (default)
  * **Use SecretRef** (opt-in)
  * Quickstart reuses existing `gateway.auth.token` SecretRefs across `env`, `file`, and `exec` providers for onboarding probe/dashboard bootstrap.
  * If that SecretRef is configured but cannot be resolved, onboarding fails early with a clear fix message instead of silently degrading runtime auth.
* In password mode, interactive setup also supports plaintext or SecretRef storage.
* Non-interactive token SecretRef path: `--gateway-token-ref-env <ENV_VAR>`.
  * Requires a non-empty env var in the onboarding process environment.
  * Cannot be combined with `--gateway-token`.
* Disable auth only if you fully trust every local process.
* Non‑loopback binds still require auth.

**5. Channels**

* [WhatsApp](https://agdiai-597e782f.mintlify.site/channels/whatsapp.md): optional QR login.
* [Telegram](https://agdiai-597e782f.mintlify.site/channels/telegram.md): bot token.
* [Discord](https://agdiai-597e782f.mintlify.site/channels/discord.md): bot token.
* [Google Chat](https://agdiai-597e782f.mintlify.site/channels/googlechat.md): service account JSON + webhook audience.
* [Mattermost](https://agdiai-597e782f.mintlify.site/channels/mattermost.md) (plugin): bot token + base URL.
* [Signal](https://agdiai-597e782f.mintlify.site/channels/signal.md): optional `signal-cli` install + account config.
* [BlueBubbles](https://agdiai-597e782f.mintlify.site/channels/bluebubbles.md): **recommended for iMessage**; server URL + password + webhook.
* [iMessage](https://agdiai-597e782f.mintlify.site/channels/imessage.md): legacy `imsg` CLI path + DB access.
* DM security: default is pairing. First DM sends a code; approve via `agdi pairing approve <channel> <code>` or use allowlists.

**6. Web search**

* Pick a provider: Perplexity, Brave, Gemini, Grok, or Kimi (or skip).
* Paste your API key (QuickStart auto-detects keys from env vars or existing config).
* Skip with `--skip-search`.
* Configure later: `agdi configure --section web`.

**7. Daemon install**

* macOS: LaunchAgent
  * Requires a logged-in user session; for headless, use a custom LaunchDaemon (not shipped).
* Linux (and Windows via WSL2): systemd user unit
  * Onboarding attempts to enable lingering via `loginctl enable-linger <user>` so the Gateway stays up after logout.
  * May prompt for sudo (writes `/var/lib/systemd/linger`); it tries without sudo first.
* **Runtime selection:** Node (recommended; required for WhatsApp/Telegram). Bun is **not recommended**.
* If token auth requires a token and `gateway.auth.token` is SecretRef-managed, daemon install validates it but does not persist resolved plaintext token values 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.

**8. Health check**

* Starts the Gateway (if needed) and runs `agdi health`.
* Tip: `agdi status --deep` adds gateway health probes to status output (requires a reachable gateway).

**9. Skills (recommended)**

* Reads the available skills and checks requirements.
* Lets you choose a node manager: **npm / pnpm** (bun not recommended).
* Installs optional dependencies (some use Homebrew on macOS).

**10. Finish**

* Summary + next steps, including iOS/Android/macOS apps for extra features.

> [!NOTE]
>
> If no GUI is detected, onboarding prints SSH port-forward instructions for the Control UI instead of opening a browser.
> If the Control UI assets are missing, onboarding attempts to build them; fallback is `pnpm ui:build` (auto-installs UI deps).

## Non-interactive mode

Use `--non-interactive` to automate or script onboarding:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
agdi onboard --non-interactive \
  --mode local \
  --auth-choice apiKey \
  --anthropic-api-key "$ANTHROPIC_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback \
  --install-daemon \
  --daemon-runtime node \
  --skip-skills
```

Add `--json` for a machine‑readable summary.

Gateway token SecretRef in non-interactive mode:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
export AGDI_GATEWAY_TOKEN="your-token"
agdi onboard --non-interactive \
  --mode local \
  --auth-choice skip \
  --gateway-auth token \
  --gateway-token-ref-env AGDI_GATEWAY_TOKEN
```

`--gateway-token` and `--gateway-token-ref-env` are mutually exclusive.

> [!NOTE]
>
> `--json` does **not** imply non-interactive mode. Use `--non-interactive` (and `--workspace`) for scripts.

Provider-specific command examples live in [CLI Automation](https://agdiai-597e782f.mintlify.site/start/wizard-cli-automation.md#provider-specific-examples).
Use this reference page for flag semantics and step ordering.

### Add agent (non-interactive)

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
agdi agents add work \
  --workspace ~/.agdi/workspace-work \
  --model openai/gpt-5.2 \
  --bind whatsapp:biz \
  --non-interactive \
  --json
```

## Gateway wizard RPC

The Gateway exposes the onboarding flow over RPC (`wizard.start`, `wizard.next`, `wizard.cancel`, `wizard.status`).
Clients (macOS app, Control UI) can render steps without re‑implementing onboarding logic.

## Signal setup (signal-cli)

Onboarding can install `signal-cli` from GitHub releases:

* Downloads the appropriate release asset.
* Stores it under `~/.agdi/tools/signal-cli/<version>/`.
* Writes `channels.signal.cliPath` to your config.

Notes:

* JVM builds require **Java 21**.
* Native builds are used when available.
* Windows uses WSL2; signal-cli install follows the Linux flow inside WSL.

## What the wizard writes

Typical fields in `~/.agdi/agdi.json`:

* `agents.defaults.workspace`
* `agents.defaults.model` / `models.providers` (if Minimax chosen)
* `tools.profile` (local onboarding defaults to `"coding"` when unset; existing explicit values are preserved)
* `gateway.*` (mode, bind, auth, tailscale)
* `session.dmScope` (behavior details: [CLI Setup Reference](https://agdiai-597e782f.mintlify.site/start/wizard-cli-reference.md#outputs-and-internals))
* `channels.telegram.botToken`, `channels.discord.token`, `channels.signal.*`, `channels.imessage.*`
* Channel allowlists (Slack/Discord/Matrix/Microsoft Teams) when you opt in during the prompts (names resolve to IDs when possible).
* `skills.install.nodeManager`
* `wizard.lastRunAt`
* `wizard.lastRunVersion`
* `wizard.lastRunCommit`
* `wizard.lastRunCommand`
* `wizard.lastRunMode`

`agdi agents add` writes `agents.list[]` and optional `bindings`.

WhatsApp credentials go under `~/.agdi/credentials/whatsapp/<accountId>/`.
Sessions are stored under `~/.agdi/agents/<agentId>/sessions/`.

Some channels are delivered as plugins. When you pick one during setup, onboarding
will prompt to install it (npm or a local path) before it can be configured.

## Related docs

* Onboarding overview: [Onboarding (CLI)](https://agdiai-597e782f.mintlify.site/start/wizard.md)
* macOS app onboarding: [Onboarding](https://agdiai-597e782f.mintlify.site/start/onboarding.md)
* Config reference: [Gateway configuration](https://agdiai-597e782f.mintlify.site/gateway/configuration.md)
* Providers: [WhatsApp](https://agdiai-597e782f.mintlify.site/channels/whatsapp.md), [Telegram](https://agdiai-597e782f.mintlify.site/channels/telegram.md), [Discord](https://agdiai-597e782f.mintlify.site/channels/discord.md), [Google Chat](https://agdiai-597e782f.mintlify.site/channels/googlechat.md), [Signal](https://agdiai-597e782f.mintlify.site/channels/signal.md), [BlueBubbles](https://agdiai-597e782f.mintlify.site/channels/bluebubbles.md) (iMessage), [iMessage](https://agdiai-597e782f.mintlify.site/channels/imessage.md) (legacy)
* Skills: [Skills](https://agdiai-597e782f.mintlify.site/tools/skills.md), [Skills config](https://agdiai-597e782f.mintlify.site/tools/skills-config.md)


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