First-run setup

There are two surfaces for the first-run setup, both backed by the same GET /api/v1/setup/status state machine:

1. CLI wizard — pnpm carabase init. Interactive, nine idempotent steps plus a final complete (env file → database → start host → timezone → provider — with auto-detect of a running Ollama or an installed claude/codex CLI — → trust receipt → demo fork → OAuth apps → SOUL.md → complete; the last two are skippable day-2 steps), the happy path for most installs. This is what the Quickstart page covers. Resuming is automatic — re-run pnpm carabase init after an interruption and completed steps are skipped — or use --non-interactive --config carabase.init.toml to drive it from a config file.
2. Admin SPA wizard — http://localhost:3000/admin/setup. A five-step browser UI that picks up from wherever the CLI wizard left off. /admin/ auto-redirects here while workspace_settings.setup_completed = false.

Both flip the same flag when complete. Run either one (or both in sequence — the SPA wizard is often the nicer surface for fiddling with model routing since it’s form-heavy).

How the wizard knows what to ask

A single endpoint, GET /api/v1/setup/status, powers both the wizard and the host’s terminal startup banner. Same source, same answer:

{
  "healthy": true,
  "checks": {
    "master_key": true,
    "db": true,
    "workspace": true,
    "openclaw_reachable": false,
    "openclaw_auth": false,
    "model_routing": false,
    "chat_capable": false,
    "soul_profile": false,
    "services_linked": false,
    "owner_passkey_registered": false,
    "oauth_enforcement_enabled": false
  },
  "version": "0.1.0",
  "setup_completed": false,
  "setup_completed_at": null,
  "next_step": "configure_model_routing"
}

The wizard polls this every 2 seconds while you’re on a step that depends on external state (System checks, Model routing), so when you fix something in another tab the tick flips green immediately.

next_step is the first failing check you can act on. It’s runtime-aware: depending on which chat runtime is resolved, an incapable-chat workspace points you at the gateway (configure_openclaw), a vendor CLI (configure_codex / configure_claude_code), or a model provider (configure_model_routing).

The five steps

1. Welcome

What Carabase is, what’s about to happen, and links to the Tailscale and (optional) OpenClaw docs.

2. System checks

Live red/green list of the checks GET /setup/status returns:

Check	What it means	Counts toward healthy?
master_key	Your .env.<env> has a 256-bit AES HOST_MASTER_KEY. pnpm bootstrap generates this automatically.	yes
db	The host can connect to Postgres (SELECT 1 succeeds).	yes
workspace	A workspace exists for this host.	yes
chat_capable	The host can actually answer a chat turn — either via OpenClaw, or via the host-native runtime against a configured provider (e.g. Ollama).	no (drives next_step)
model_routing	A model-routing row exists in the integrations table for this workspace (background AI tiers are configured).	no (drives next_step)
openclaw_reachable	The OpenClaw gateway is responding (only relevant if you’ve chosen the OpenClaw chat runtime).	informational
openclaw_auth	The host’s OPENCLAW_GATEWAY_PASSWORD matches the gateway’s config.	informational
soul_profile	The owner has authored SOUL.md beyond the pristine template seed.	informational
services_linked	This host is linked to Carabase Services (always false when SERVICES_BASE_URL is unset).	informational
owner_passkey_registered	At least one owner passkey is registered. Enrollment isn’t a wizard step — it runs through the claim code printed on the host console and Settings → Access & security.	informational
oauth_enforcement_enabled	Workspace-wide OAuth enforcement is on. Off is the default until every client signs in with a credential.	informational

healthy is intentionally just master_key && db && workspace — the three cheapest, most catastrophic signals. Everything else can stay amber and you can still proceed; the dashboard surfaces the same warnings afterward.

The OpenClaw checks are informational unless OpenClaw is your resolved chat runtime. A self-host with only a local Ollama URL is fully healthy with zero gateway — OpenClaw is no longer a hard requirement.

3. Model routing

Chat is multi-engine. You pick a chat runtime plus the provider it uses:

• host-native — the open-source chat floor. Runs against the provider you configure (Ollama is the easiest free, local pick). No gateway required.
• OpenClaw — the premium chat runtime. Optional. Skip it entirely and use host-native instead.
• codex_cli / claude_code — vendor-CLI bridges (read-write by default) that run through your local codex login / claude login. They don’t use model routing — they need the binary on PATH and an operator login.

Separately, Carabase splits background AI calls into two tiers, configured in AI Engine (/admin/model-routing):

• utility-high — where reasoning quality matters (hypothesis verification, tool-argument extraction). OK to be a bit slow or expensive.
• utility-low — high-volume, latency-sensitive work (compaction, hint generation, curation). Usually a smaller / cheaper model.

chat_capable goes green once the resolved runtime can really serve a turn — for host-native that means a provider with a working key (or a no-key provider like Ollama), not merely a model-routing row that would 503 on the first turn. You can skip this step and configure later; the agent just won’t have functional reasoning until you do.

4. OAuth apps (optional)

Open Integrations and select GitHub or Google. When hosted sign-in is available for your linked Host, choose Connect and complete the provider consent flow; you do not need an OAuth app of your own. Availability depends on your entitlement and the provider configuration published by Carabase Services. The CLI wizard skips the app prompt for each available hosted provider.

If hosted sign-in is unavailable, or you choose Advanced: use your own OAuth app, configure your own app:

• GitHub — for syncing PRs and issues. Uses device-flow OAuth, so you only need a Client ID (no secret).
• Google — for Calendar, Gmail and Drive. Needs both a Client ID and Client Secret. Your own app is also required for the Google Analytics and YouTube connector permissions.

Skippable — you can come back any time via OAuth Apps in the sidebar.

5. Done

Click Mark setup complete to POST /api/v1/setup/complete. This flips workspace_settings.setup_completed = true (idempotently — re-flipping preserves the original setup_completed_at) and best-effort seeds a template SOUL.md so the Owner Profile editor opens on a real file from day one. After this, /admin/ lands you on the dashboard instead of bouncing back to the wizard.

The seeded SOUL.md is a pristine template until you edit it, and pristine seeds are never injected into prompts — so completing setup before authoring your profile is safe. Fill it in afterward via the Owner Profile page in the Admin SPA.

If any non-critical check is still amber when you mark complete, the dashboard surfaces the same warnings — you don’t have to fix everything before continuing.

The Done step also points at Settings → Access & security (/admin/owner-auth) while no owner passkey is registered: enter the claim code from the host console there, register a passkey and save the recovery codes. That passkey is how you — and the CLI, via carabase auth login — sign in from then on. The CLI wizard prints the same pointer as a Secure it: line in its completion output.

Re-running the wizard

The flag is just a boolean in the database. To re-show the wizard for any reason:

psql $DATABASE_URL -c \
  "UPDATE workspace_settings SET setup_completed = false WHERE workspace_id = 'YOUR-WORKSPACE-ID'"

Then refresh /admin/ — the redirect logic will take you back to the wizard.