apus onboard

Guided setup that establishes inference first: it detects existing AI access, waits for your provider choice, verifies that connection, persists only the working route, and then starts Apus to configure the rest. apus setup reaches this flow on fresh systems or whenever an onboarding option is present; configured systems use bare apus setup for system-agent chat. apus setup --baseline only writes the baseline config/workspace.

CLI onboarding hub

Walkthrough of the interactive CLI flow.

Onboarding overview

How Apus onboarding fits together.

CLI setup reference

Outputs, internals, and per-step behavior.

CLI automation

Non-interactive flags and scripted setups.

macOS app onboarding

Onboarding flow for the macOS menu bar app.

Examples

apus onboard
apus onboard --tui
apus onboard --classic
apus onboard --modern
apus onboard --flow quickstart
apus onboard --agent-name robby
apus onboard --flow manual
apus onboard --flow import
apus onboard --import-from hermes --import-source ~/.hermes
apus onboard --skip-bootstrap
apus onboard recommendations --json
apus onboard recommendations --agent writer --json
apus onboard recommendations --agent writer acknowledge
apus onboard recommendations acknowledge --agent writer
apus onboard recommendations refresh --agent writer
apus onboard recommendations acknowledge
apus onboard recommendations acknowledge --retry "<failed-id>"
apus onboard recommendations refresh
apus onboard --mode remote --remote-url wss://gateway-host:18789

apus onboard recommendations reads pending app-recommendation matches stored during onboarding. Add --json for the machine-readable list used by the first-run bootstrap. The command does not rescan installed apps or call a model. Its output contains only validated install IDs, source, and tier; it intentionally omits untrusted marketplace prose, model reasons, and local app labels. After the recommendation offer has been answered, the command returns an empty list and future onboarding runs skip the step entirely. apus onboard recommendations refresh clears the stored offer so the next onboarding run rescans installed apps and creates a new offer.

Pass --agent <id> to select a configured agent for reads, acknowledge, acknowledge --retry, or refresh. Place it before or after the subcommand; an explicit value on the subcommand takes precedence over a parent value. These operations use only that agent's workspace recommendations. Without the selector, the command keeps its existing default-agent behavior and asks you to select an agent when the owner is ambiguous. Blank or unknown agent IDs fail without changing the stored recommendations; use apus agents list to find configured IDs.

Fresh workspaces defer the recommendation choice to the bootstrap conversation. After that conversation handles the user's choices, apus onboard recommendations acknowledge marks the stored offer answered. The acknowledgement is idempotent. If a chosen install fails, pass each failed opaque ID with --retry <id...>; successful and declined matches are consumed, while failed matches remain pending for a later onboarding run. Unknown IDs fail without changing the stored offer. After an interrupted ClawHub skill install, an existing target counts as successful only when apus skills verify "@owner/slug" succeeds for the same publisher-qualified recommendation ID and its JSON output reports apus.resolution.source: "installed". Registry verification alone is not proof of a local install. Otherwise keep that ID pending with --retry and do not overwrite the existing skill.

Flags

Guided flow

Plain apus onboard starts the guided flow. It shows the security notice, asks for the first agent's name when no roster exists, then asks one discovery question up front: full access (recommended — setup looks for AI apps, keys, and local runtimes automatically) or ask first (setup asks once before looking around, or lets you configure manually). The choice persists as wizard.accessMode. With discovery allowed, onboarding detects AI access already available through configured models, API-key environment variables, and supported local CLIs. Detection only presents choices; it does not run live inference, install plugins, choose a model, or persist credentials. A provider marked Setup and utility, such as Apple Foundation Models, is verified and saved as utilityModel without replacing the primary model. On a fresh installation, it powers the Apus setup assistant; choose a separate primary model before opening regular agent chat. Existing primary models and credentials remain unchanged when you add a utility model.

Choose a detected connection or any supported provider in the shared picker. The selected connection runs a real completion. If it fails, the error is shown and the picker waits for your next choice. Cancellation stops the attempt without trying another provider.

The provider picker includes installed and installable official providers. Choose More… for additional provider groups; regions, plans, and auth methods then appear in a second menu. Supported browser or device sign-in and masked API-key or token methods use the same live completion path. Apus persists only the verified model route and its credential after the test succeeds; a failed candidate does not replace the configured model or save the attempted credential. In local onboarding, Skip for now prepares the named agent's workspace and local Gateway configuration, then exits without starting the Gateway or AI chat. Rerun apus onboard when you are ready to connect AI; interrupted baseline setup resumes under its existing onboarding owner.

In guided mode, --workspace <dir> supplies Apus's proposed workspace and the isolated inference context. It is not persisted until you approve the Apus setup proposal. Classic and noninteractive onboarding persist their workspace through their normal setup flow. A workspace must be a directory or a new path beneath directories; a file, non-directory ancestor, dangling symbolic link, or symlink loop is rejected before setup or reset, with the failing path named. Other inspection failures, such as permission errors, are reported rather than treated as missing directories. Symbolic links to existing directories, including new paths beneath them, are allowed. On a rerun with an existing agent roster, onboarding preserves the configured fleet workspace: the classic wizard shows both paths and requires explicit confirmation before moving it, while non-interactive setup warns and keeps the current value. For an explicitly managed multi-agent fleet, provider setup updates the configured system agent's model and aliases without replacing fleet-wide model defaults or another agent's model.

After inference passes, onboarding checks for memories from supported local AI tools: Claude Code auto-memory, Codex consolidated memories, and Hermes memory files. When it finds any, one page offers to copy them into the agent workspace under memory/imports/ for indexed recall. Nothing is imported without confirmation, previously imported files are skipped, and you can always import later from the Control UI Memory import page, which offers the same memory-only scope. (A full apus migrate run is broader: it can also import config, skills, and credentials.) The classic wizard shows the same page after it prepares the workspace.

After inference passes (and the memory-import offer), guided onboarding applies the standard setup automatically — workspace, Gateway, and sessions, the same plan the conversational apus setup chat would apply on "yes" — then offers plugin and skill recommendations from installed apps; app names are matched through your configured model and ClawHub search, and the step can be disabled with wizard.appRecommendations. When the platform has a supported browser opener, it then opens the authenticated Control UI dashboard and waits up to 60 seconds for the browser client to connect. The short-lived handoff gives that exact signed browser a durable administrator credential. This includes display-less WSL when wslview is installed. On headless Linux, WSL without an opener, or over SSH without a display, it prints a prominent copy-pasteable dashboard URL, including an SSH port-forward command for a loopback Gateway, and waits up to five minutes. A successful connection continues in the browser; an unreachable Gateway or a timeout falls back to the same terminal hatch as before. Pass --tui to skip the browser handoff and force that terminal hatch. If applying setup fails after inference succeeds, the status identifies workspace, Gateway, or general setup failure rather than an AI check failure. The detailed error keeps its recovery guidance, and onboarding falls back to the conversational Apus chat to finish interactively. Channels, agents, plugins, and other optional features remain Apus chat territory: run apus and use open channel wizard for <channel> to hand channel credential collection to a masked terminal wizard. To change the model provider or its authentication, exit Apus and run apus onboard; Apus does not open the guided or classic provider flows.

On a configured install, running apus onboard again offers the current default model in the detected-connections group. Choose it for a verification pass that does not re-apply setup, reinstall, or restart the Gateway service. If that check fails, the configured model stays unchanged and the picker waits for your next choice. The check runs outside your workspace, so a model provided by a workspace plugin can fail here while still working in the agent. Use apus onboard --classic for provider-specific auth, channels, skills, remote Gateway setup, imports, or full Gateway controls. For conversational non-inference setup and repair, run apus setup; apus onboard --modern is a compatibility alias through the same inference gate. The classic wizard can optionally verify the default model with a live completion, but Apus will not start until its own live inference check passes.

In an interactive terminal, bare apus (no subcommand) routes by config state:

Remote setup reuses device pairing for the selected Gateway, including a configured remote connection forwarded through loopback. Its readiness checks do not create new device pairings. Setup chat keeps a stable authenticated caller across replies, including on loopback connections.

When interactive remote setup activates inference and the Gateway requires a restart, onboarding waits up to 45 seconds for a new Gateway boot and a successful inference check before opening setup chat. A healthy connection to the old Gateway does not count. If the restart wait expires or boot identity is missing, onboarding reports that the settings were saved and stops rather than trying another provider. Check the remote Gateway, then rerun bare apus in the connected terminal. If the error says the Gateway did not provide a boot identity, update and restart that Gateway first.

Plaintext ws:// is accepted for loopback, private IP literals, .local, and Tailnet *.ts.net gateway URLs. For other trusted private-DNS names, set APUS_ALLOW_INSECURE_PRIVATE_WS=1 in the onboarding process environment.

Reset

apus onboard --reset
apus onboard --reset --reset-scope full

--reset is a destructive pre-dispatch flag, not a choice in the classic wizard's Setup mode menu. --reset-scope controls how much it removes: config (config only), config+creds+sessions (default when --reset is passed without a scope), or full (also resets the workspace). Before moving state to Trash, onboarding validates TTY availability, the reset scope, auth and Gateway options, migration import options, and the workspace target for a full reset. Migration import options cannot be combined with --reset; run the import without --reset. Non-interactive setup also requires --accept-risk before reset. Interactive classic setup performs reset before showing its risk acknowledgement, so invoking --reset can move state to Trash before you can decline that prompt. After reset, the command runs guided, classic, or non-interactive onboarding according to the other flags.

Session reset permanently removes canonical SQLite history and its owned archive files through the same cleanup as apus reset. It preserves auth profiles and unrelated database state. Stop any running Gateway first; onboarding refuses session cleanup while another process owns the state directory.

Locale

Interactive onboarding uses the CLI wizard locale for fixed setup copy. It uses the first nonblank value in this order:

  1. APUS_LOCALE
  2. LC_ALL
  3. LC_MESSAGES
  4. LANG
  5. English fallback

Supported wizard locales are en, zh-CN, and zh-TW. Locale values may use underscore or POSIX suffix forms such as zh_CN.UTF-8. Product names, command names, config keys, URLs, provider IDs, model IDs, and plugin/channel labels remain literal.

The Control UI's fixed onboarding welcome and setup choices use the UI language reported when it connects to the Gateway. Chinese UI locales use the same source-maintained setup translations; command replies such as yes and talk to agent remain unchanged.

APUS_LOCALE=zh-CN apus onboard
APUS_LOCALE=en apus onboard # Explicit English override

Non-interactive setup

--non-interactive requires --accept-risk (acknowledges that agents are powerful and full system access is risky). --mode defaults to local.

Replacing an existing provider credential saves it inactive and prints a models auth activate command; setup does not automatically switch your working connection or continue to daemon installation. Temporary credential staging files are removed after their databases close. If removal remains blocked, setup warns with the leftover directory path without hiding the provider result or activation instructions. Remove that directory manually once the lock clears.

Required external plugins

--accept-risk does not approve plugin capabilities. If local setup needs an external provider or runtime plugin, non-interactive onboarding stops when that plugin requires a capability review. Review and preinstall the required plugin, then rerun the same onboarding command. For the official Codex runtime used by OpenAI setup:

# After reviewing the plugin and its declared capabilities:
apus plugins install codex --accept-capabilities
apus onboard --non-interactive --accept-risk --skip-health \
  --auth-choice openai-api-key \
  --secret-input-mode ref

Set OPENAI_API_KEY before running this example. The codex selector uses Apus's official plugin catalog. If the required plugin is already installed but needs approval to enable it, use apus plugins enable <plugin-id> --accept-capabilities instead. The flag approves only that plugin operation; it is not a global bypass. The same preinstall-and-rerun flow applies to external plugins required by apus channels add. Bundled plugins do not need this review. See Capability consent and the automation guide.

Provider setup examples

apus onboard --non-interactive --accept-risk --skip-health \
  --agent-name robby \
  --auth-choice custom-api-key \
  --custom-base-url "https://llm.example.com/v1" \
  --custom-model-id "foo-large" \
  --custom-api-key "$CUSTOM_API_KEY" \
  --secret-input-mode plaintext \
  --custom-compatibility openai \
  --custom-image-input

--custom-api-key is optional; if omitted, onboarding checks CUSTOM_API_KEY in env. Apus marks common vision model IDs (GPT-4o/4.1/5.x, Claude 3/4, Gemini, Qwen-VL, LLaVA, Pixtral, and similar) as image-capable automatically. Pass --custom-image-input for unknown custom vision IDs, or --custom-text-input to force text-only metadata. Use --custom-compatibility openai-responses for OpenAI-compatible endpoints that support /v1/responses but not /v1/chat/completions; valid values are openai (default), openai-responses, anthropic.

LM Studio also has a provider-specific key flag:

apus onboard --non-interactive --accept-risk --skip-health \
  --auth-choice lmstudio \
  --custom-base-url "http://localhost:1234/v1" \
  --custom-model-id "qwen/qwen3.5-9b" \
  --lmstudio-api-key "$LM_API_TOKEN"

Non-interactive Ollama:

apus onboard --non-interactive --accept-risk --skip-health \
  --auth-choice ollama \
  --custom-base-url "http://ollama-host:11434" \
  --custom-model-id "qwen3.5:27b"

--custom-base-url defaults to http://127.0.0.1:11434. --custom-model-id is optional; if omitted, onboarding uses Ollama's suggested defaults. Cloud model IDs such as kimi-k2.5:cloud also work here.

Non-interactive llama.cpp against an existing llama-server:

apus onboard --non-interactive --accept-risk \
  --auth-choice llama-cpp-existing-server \
  --custom-base-url "http://127.0.0.1:8080/v1" \
  --custom-model-id "my-model" \
  --llama-server-api-key "$LLAMA_SERVER_API_KEY"

--auth-choice llama-cpp selects the managed local server instead. --llama-server-api-key is optional; if omitted, onboarding checks LLAMA_SERVER_API_KEY in env. See llama.cpp for endpoint-replacement and auth-profile behavior.

Store provider keys as refs instead of plaintext:

apus onboard --non-interactive --accept-risk --skip-health \
  --auth-choice openai-api-key \
  --secret-input-mode ref

With --secret-input-mode ref, onboarding stores new credentials as refs instead of plaintext: auth profiles use keyRef: { source: "env", provider: "default", id: <envVar> }, and custom providers use models.providers.<id>.apiKey (for example { source: "env", provider: "default", id: "CUSTOM_API_KEY" }). Set the provider env var when adding a new credential; an inline key flag without its matching env var fails fast. Existing resolvable named auth profiles and their env, file, exec, or store references are reused unchanged, without a new apiKey or keyRef write or additional provider env var. Existing plaintext profile credentials are not migrated; run apus secrets configure --apply, then apus secrets audit --check. See Secrets management.

Gateway auth (non-interactive)

Existing trusted-proxy authentication and its proxy policy stay intact on rerun unless you explicitly select another auth mode. Selecting Tailscale Funnel while retaining trusted-proxy auth is rejected; switch explicitly with --gateway-auth password or keep Tailscale exposure off. Same-host completion uses the configured local password (including SecretRefs) or APUS_GATEWAY_PASSWORD, through the Gateway's loopback listener. Post-setup health checks stay on the configured local Gateway port, ignoring ambient Gateway URL and port overrides.

export OPENAI_API_KEY="your-provider-key"
export APUS_GATEWAY_TOKEN="your-token"
apus onboard --non-interactive --accept-risk --skip-health \
  --mode local \
  --auth-choice openai-api-key \
  --secret-input-mode ref \
  --gateway-auth token \
  --gateway-token-ref-env APUS_GATEWAY_TOKEN

Local gateway health

Interactive ref mode

Z.AI endpoint choices

--auth-choice zai-api-key auto-detects the best Z.AI endpoint and model for your key: Coding Plan endpoints prefer zai/glm-5.3, falling back to glm-5.1 and then glm-4.7 when the key does not expose them; general API endpoints use the Z.AI provider default, zai/glm-5.2. To force a Coding Plan endpoint, pick zai-coding-global or zai-coding-cn directly.

# Promptless endpoint selection
apus onboard --non-interactive --accept-risk --skip-health \
  --auth-choice zai-coding-global \
  --zai-api-key "$ZAI_API_KEY"

# Other Z.AI endpoint choices: zai-coding-cn, zai-global, zai-cn

Mistral:

apus onboard --non-interactive --accept-risk --skip-health \
  --auth-choice mistral-api-key \
  --mistral-api-key "$MISTRAL_API_KEY"

Arcee AI. The arcee provider plugin supplies both choices and their flags, so install it before running onboarding non-interactively:

# Direct (chat.arcee.ai)
apus onboard --non-interactive --accept-risk --skip-health \
  --auth-choice arceeai-api-key \
  --arceeai-api-key "$ARCEEAI_API_KEY"

# Via OpenRouter
apus onboard --non-interactive --accept-risk --skip-health \
  --auth-choice arceeai-openrouter \
  --openrouter-api-key "$OPENROUTER_API_KEY"

Additional non-interactive flags

Token-based model auth (used with --auth-choice token):

Flag Description
--token-provider <id> Token provider id issuing the token
--token <token> Token value for model authentication
--token-profile-id <id> Auth profile id (default <provider>:manual; some provider-owned flows use their own default, such as anthropic:default)
--token-expires-in <duration> Optional token expiry duration (e.g. 365d, 12h)

Cloudflare AI Gateway: --cloudflare-ai-gateway-account-id <id>, --cloudflare-ai-gateway-gateway-id <id>.

Daemon install control: --no-install-daemon / --skip-daemon (aliases; skip gateway service install), --daemon-runtime <node|bun> (default: node). Bun 1.4+ with WAL-reset-safe node:sqlite is an explicit opt-in; Node remains recommended.

Skills: --node-manager <npm|pnpm|bun> (default npm), --skip-skills.

UI and hook setup: --skip-ui (skip Control UI/TUI prompts), --skip-hooks (skip webhook/hook setup), --skip-channels, --skip-search.

Output: --suppress-gateway-token-output disables the automatic Control UI handoff in guided onboarding. Classic onboarding never prints reusable Gateway token values or tokenized URLs; it still prints safe recovery commands.

--json does not imply non-interactive mode in guided or classic onboarding. Without an interactive terminal, both onboarding modes return a structured JSON error; add --non-interactive --accept-risk for automation. With --modern, JSON is a one-shot Apus overview and exits after that single result. Use --non-interactive for other scripts. Invalid existing configuration also returns one JSON failure; repair guidance remains on stderr. Non-interactive provider setup failures, including an unreachable local model server or missing credentials, return a JSON error on stdout and a nonzero exit status. Without --json, the same recovery guidance is printed as readable text.

Provider prefiltering

When an auth choice implies a preferred provider, onboarding prefilters the default-model and allowlist pickers to that provider's models. The filter also matches other providers owned by the same plugin, which covers coding-plan variants such as volcengine/volcengine-plan and byteplus/byteplus-plan. If the preferred-provider filter yields no loaded models, onboarding falls back to the unfiltered catalog instead of leaving the picker empty.

Web-search follow-ups

Some web-search providers trigger provider-specific follow-up prompts during onboarding:

Other behaviors

Common follow-up commands

Use apus configure later for targeted non-inference changes and apus channels add for channel-only setup. For model provider or auth route changes, run apus onboard instead.

apus channels add
apus configure
apus agents add <name>

Related