apus setup

apus setup is the system-agent entry point. On a configured system, bare apus setup opens an interactive Apus chat. On a fresh system, it falls through to guided onboarding. Use -m/--message for one request or --baseline to initialize config/workspace folders without the wizard.

Routing order:

  1. Any onboarding option (--wizard, --baseline, workspace, reset, non-interactive, flow, mode, Gateway, daemon, skip, import, remote, or auth options) runs onboarding exactly as apus onboard does.
  2. -m/--message or --yes runs the system agent.
  3. With no routing option, a configured interactive system opens Apus. A fresh system runs onboarding. On a configured system, --json prints the system overview even without a TTY; an onboarding option keeps onboarding's JSON summary.

In guided mode, --workspace <dir> is the workspace proposed to Apus; it is persisted only after you approve that proposal. Baseline, classic, and noninteractive setup persist the supplied workspace through their normal flow on a fresh install. When an existing agent roster would be remapped, the classic wizard requires explicit confirmation; noninteractive setup keeps the current fleet workspace and prints a warning.

Guided inference detection runs on the Gateway host on macOS or Linux. The CLI and macOS app call the same Gateway-owned detector, which checks configured models, supported CLI logins, API-key environment variables, and already installed Ollama or LM Studio models. Local models are never downloaded by this discovery pass. Both CLI onboarding and the macOS app wait for you to choose a connection before testing it. A failed or cancelled attempt never selects another provider automatically. Setup saves the credential, then sends one tool-free confirmation turn using the candidate settings in memory. It saves the provider and model configuration only after that turn succeeds. A failed connection keeps the credential and leaves the configuration unchanged. Choose the saved sign-in to retry without signing in again. Custom endpoint settings stay available for retry while the Gateway runs; after a restart, enter the endpoint settings again.

Initial Claude Code and Codex detection checks executable versions without running auth-status commands or starting an app server. Readable Codex credentials are reported as stored evidence; the active login remains unverified during detection. Stored credentials do not receive verified-subscription priority over environment API keys.

In the Control UI, Model Setup can also select models from installed native agents through the shared model picker. Use saves that model and its runtime without running the setup test; authentication and tools stay with the native agent. Provider Test & use still requires a verified tool-free reply. Gemini CLI and Antigravity are not offered as detected setup routes.

setup accepts the same onboarding flags as apus onboard, including auth (--auth-choice, --token, provider key flags), Gateway (--gateway-port, --gateway-bind, --gateway-auth, --install-daemon), Tailscale (--tailscale), reset (--reset, --reset-scope), flow (--flow quickstart|advanced|manual|import), and skip flags (--skip-channels, --skip-skills, --skip-bootstrap, --skip-search, --skip-health, --skip-ui, --skip-hooks). Pass --tui to use the same terminal hatch as apus onboard --tui. See Onboard and CLI automation for the full flag reference and non-interactive examples. apus onboard --modern remains a compatibility entry for the same inference-gated Apus assistant.

Local onboarding generates a Gateway secret in token mode by default, without asking you to choose token or password. Existing password-mode configs are preserved. Use --gateway-auth password or --gateway-password <value> to choose a password explicitly; Tailscale Funnel still requires password mode.

Use setup --team for the same small-team onboarding as onboard --team. --agent-name <name> names the first agent or, with --team, the coordinator.

apus setup is for mutable config installs. In Nix mode (APUS_NIX_MODE=1) Apus refuses setup writes because the config file is managed by Nix. Use the first-party nix-apus Quick Start or the equivalent source config for another Nix package.

Options

Flag Description
-m, --message <text> Run one Apus request.
--yes Approve persistent config writes for one --message request.
--workspace <dir> Workspace proposal; existing fleets require classic confirmation and are preserved noninteractively.
--baseline Create baseline config/workspace/session folders without onboarding.
--wizard Force interactive onboarding.
--classic Run the classic multi-step onboarding wizard; not valid with --non-interactive.
--agent-name <name> Name for the first agent (default: main).
--tui Use the terminal hatch instead of the browser handoff.
--non-interactive Run onboarding without prompts.
--accept-risk Acknowledge full-system agent access risk; required with --non-interactive.
--mode <mode> Onboarding mode: local or remote.
--flow <flow> Onboard flow: quickstart, advanced, manual, or import.
--reset Reset config + credentials + sessions before onboarding (workspace only with --reset-scope full).
--reset-scope <scope> Reset scope: config, config+creds+sessions, or full.
--import-from <provider> Migration provider to run during onboarding.
--import-source <path> Source agent home for --import-from.
--import-secrets Import supported secrets during onboarding migration.
--remote-url <url> Remote Gateway WebSocket URL.
--remote-token <token> Remote Gateway token (optional).
--remote-password <password> Remote Gateway password (optional).
--json Configured system: Apus overview. Onboarding route: onboarding summary.

--classic and --non-interactive are mutually exclusive: classic opens the prompted wizard, while noninteractive setup uses the automation path. In interactive onboarding, --remote-url, --remote-token, and --remote-password prefill the remote Gateway step and take precedence over stored remote values for that run. Pass either a token or a password, not both. Changing the URL does not reuse stored credentials unless you also provide a new token or password. The interactive step asks for one Gateway secret and stores it as gateway.remote.token; either field is accepted by the Gateway. The credential remains masked and uses the wizard's selected plaintext or SecretRef storage mode. --gateway-token, --gateway-token-ref-env, and --gateway-password configure a local Gateway and are not valid in remote mode. For remote token SecretRefs, set APUS_GATEWAY_TOKEN and use --remote-token with --secret-input-mode ref.

Baseline mode

apus setup --baseline preserves the older baseline-only behavior: it creates the config, workspace, and session directories, then exits without running onboarding. It accepts --workspace, --skip-bootstrap, and harmless output controls, but rejects explicit onboarding, Gateway, auth, reset, or daemon options instead of silently ignoring them. If an existing config is invalid, baseline setup preserves it and asks you to run apus doctor --fix to apply supported repairs before retrying.

Use apus setup --baseline --skip-bootstrap to create the directories without generating workspace bootstrap files. This persists agents.defaults.skipBootstrap: true as a local config override, preserves existing workspace files and included config files, and remains enabled on later baseline runs that omit the flag. If the skipBootstrap value itself comes from an $include, edit that included file directly instead of replacing its pointer through baseline setup. When also changing --workspace, update an included per-agent workspace or an exact workspace-file include first; baseline setup rejects that combined change before writing either config or workspace files.

Examples

apus setup
apus setup -m "status"
apus setup -m "restart gateway" --yes
apus setup --json
apus setup --wizard
apus setup --baseline
apus setup --workspace ~/.apus/workspace
apus setup --import-from hermes --import-source ~/.hermes
apus setup --non-interactive --accept-risk --mode remote --remote-url wss://gateway-host:18789 --remote-token <token>
apus setup --non-interactive --accept-risk --mode remote --remote-url wss://gateway-host:18789 --remote-password <password>

Notes

Related