> ## Documentation Index > Fetch the complete documentation index at: https://aiwithapex.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Wizard # Onboarding Wizard (CLI) The onboarding wizard is the **recommended** way to set up crocbot on 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. Primary entrypoint: ```bash theme={null} crocbot onboard ``` Fastest first chat: open the Control UI (no channel setup needed). Run `crocbot dashboard` and chat in the browser. Docs: [Dashboard](/web/dashboard). Follow‑up reconfiguration: ```bash theme={null} crocbot configure ``` Recommended: set up a Brave Search API key so the agent can use `web_search` (`web_fetch` works without a key). Easiest path: `crocbot configure --section web` which stores `tools.web.search.apiKey`. Docs: [Web tools](/tools/web). ## QuickStart vs Advanced The wizard starts with **QuickStart** (defaults) vs **Advanced** (full control). **QuickStart** keeps the defaults: * Local gateway (loopback) * Workspace default (or existing workspace) * Gateway port **18789** * Gateway auth **Token** (auto‑generated, even on loopback) * Tailscale exposure **Off** * Telegram DMs default to **allowlist** **Advanced** exposes every step (mode, workspace, gateway, channels, daemon, skills). ## What the wizard does **Local mode (default)** walks you through: * Model/auth (OpenAI Code (Codex) subscription OAuth, Anthropic API key (recommended) or setup-token (paste), plus MiniMax/GLM/Moonshot/AI Gateway options) * Workspace location + bootstrap files * Gateway settings (port/bind/auth/tailscale) * Telegram channel * Daemon install (systemd user unit) * Health check * Skills (recommended) **Remote mode** only configures the local client to connect to a Gateway elsewhere. It does **not** install or change anything on the remote host. To add more isolated agents (separate workspace + sessions + auth), use: ```bash theme={null} crocbot agents add ``` Tip: `--json` does **not** imply non-interactive mode. Use `--non-interactive` (and `--workspace`) for scripts. ## Flow details (local) 1. **Existing config detection** * If `~/.crocbot/crocbot.json` exists, choose **Keep / Modify / Reset**. * Re-running the wizard does **not** wipe anything unless you explicitly choose **Reset** (or pass `--reset`). * If the config is invalid or contains legacy keys, the wizard stops and asks you to run `crocbot 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 (recommended)**: uses `ANTHROPIC_API_KEY` if present or prompts for a key, then saves it for daemon use. * **Anthropic OAuth (Claude Code CLI)**: on macOS the wizard 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, the wizard 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 saves it to `~/.crocbot/.env` so launchd can read it. * **OpenCode Zen (multi-model proxy)**: prompts for `OPENCODE_API_KEY` (or `OPENCODE_ZEN_API_KEY`, get it at [https://opencode.ai/auth](https://opencode.ai/auth)). * **API key**: stores the key for you. * **Vercel AI Gateway (multi-model proxy)**: prompts for `AI_GATEWAY_API_KEY`. * More detail: [Vercel AI Gateway](/providers/vercel-ai-gateway) * **MiniMax M2.1**: config is auto-written. * More detail: [MiniMax](/providers/minimax) * **Synthetic (Anthropic-compatible)**: prompts for `SYNTHETIC_API_KEY`. * More detail: [Synthetic](/providers/synthetic) * **Moonshot (Kimi K2)**: config is auto-written. * **Kimi Code**: config is auto-written. * More detail: [Moonshot AI (Kimi + Kimi Code)](/providers/moonshot) * **Skip**: no auth configured yet. * Pick a default model from detected options (or enter provider/model manually). * Wizard runs a model check and warns if the configured model is unknown or missing auth. * OAuth credentials live in `~/.crocbot/credentials/oauth.json`; auth profiles live in `~/.crocbot/agents//agent/auth-profiles.json` (API keys + OAuth). * More detail: [/concepts/oauth](/concepts/oauth) 3. **Workspace** * Default `~/croc` (configurable). * Seeds the workspace files needed for the agent bootstrap ritual. * Full workspace layout + backup guide: [Agent workspace](/concepts/agent-workspace) 4. **Gateway** * Port, bind, auth mode, tailscale exposure. * Auth recommendation: keep **Token** even for loopback so local WS clients must authenticate. * Disable auth only if you fully trust every local process. * Non‑loopback binds still require auth. 5. **Channels** * Telegram: bot token from BotFather. * DM security: default is allowlist. Add your user ID to `channels.telegram.allowFrom`. 6. **Daemon install** * Linux (and Windows via WSL2): systemd user unit * Wizard attempts to enable lingering via `loginctl enable-linger ` 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). Bun is **not recommended**. 7. **Health check** * Starts the Gateway (if needed) and runs `crocbot health`. * Tip: `crocbot status --deep` adds gateway health probes to status output (requires a reachable gateway). 8. **Skills (recommended)** * Reads the available skills and checks requirements. * Lets you choose a node manager: **npm / pnpm** (bun not recommended). * Installs optional dependencies. 9. **Finish** * Summary + next steps. * If no GUI is detected, the wizard prints SSH port-forward instructions for the Control UI instead of opening a browser. * If the Control UI assets are missing, the wizard attempts to build them; fallback is `pnpm ui:build` (auto-installs UI deps). ## Remote mode Remote mode configures a local client to connect to a Gateway elsewhere. What you'll set: * Remote Gateway URL (`ws://...`) * Token if the remote Gateway requires auth (recommended) Notes: * No remote installs or daemon changes are performed. * If the Gateway is loopback-only, use SSH tunneling or a tailnet. * Discovery hints: * Linux: Avahi (`avahi-browse`) ## Add another agent Use `crocbot agents add ` to create a separate agent with its own workspace, sessions, and auth profiles. Running without `--workspace` launches the wizard. What it sets: * `agents.list[].name` * `agents.list[].workspace` * `agents.list[].agentDir` Notes: * Default workspaces follow `~/croc-`. * Add `bindings` to route inbound messages (the wizard can do this). * Non-interactive flags: `--model`, `--agent-dir`, `--bind`, `--non-interactive`. ## Non‑interactive mode Use `--non-interactive` to automate or script onboarding: ```bash theme={null} crocbot 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. Gemini example: ```bash theme={null} crocbot onboard --non-interactive \ --mode local \ --auth-choice gemini-api-key \ --gemini-api-key "$GEMINI_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback ``` Z.AI example: ```bash theme={null} crocbot onboard --non-interactive \ --mode local \ --auth-choice zai-api-key \ --zai-api-key "$ZAI_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback ``` Vercel AI Gateway example: ```bash theme={null} crocbot onboard --non-interactive \ --mode local \ --auth-choice ai-gateway-api-key \ --ai-gateway-api-key "$AI_GATEWAY_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback ``` Moonshot example: ```bash theme={null} crocbot onboard --non-interactive \ --mode local \ --auth-choice moonshot-api-key \ --moonshot-api-key "$MOONSHOT_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback ``` Synthetic example: ```bash theme={null} crocbot onboard --non-interactive \ --mode local \ --auth-choice synthetic-api-key \ --synthetic-api-key "$SYNTHETIC_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback ``` OpenCode Zen example: ```bash theme={null} crocbot onboard --non-interactive \ --mode local \ --auth-choice opencode-zen \ --opencode-zen-api-key "$OPENCODE_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback ``` Add agent (non‑interactive) example: ```bash theme={null} crocbot agents add work \ --workspace ~/croc-work \ --model openai/gpt-5.2 \ --bind telegram:main \ --non-interactive \ --json ``` ## Gateway wizard RPC The Gateway exposes the wizard flow over RPC (`wizard.start`, `wizard.next`, `wizard.cancel`, `wizard.status`). Clients (Control UI, CLI) can render steps without re‑implementing onboarding logic. ## What the wizard writes Typical fields in `~/.crocbot/crocbot.json`: * `agents.defaults.workspace` * `agents.defaults.model` / `models.providers` (if Minimax chosen) * `gateway.*` (mode, bind, auth, tailscale) * `channels.telegram.botToken` * `skills.install.nodeManager` * `wizard.lastRunAt` * `wizard.lastRunVersion` * `wizard.lastRunCommit` * `wizard.lastRunCommand` * `wizard.lastRunMode` `crocbot agents add` writes `agents.list[]` and optional `bindings`. Sessions are stored under `~/.crocbot/agents//sessions/`. ## Related docs * Config reference: [Gateway configuration](/gateway/configuration) * Telegram: [Telegram](/channels/telegram) * Skills: [Skills](/tools/skills), [Skills config](/tools/skills-config)