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, seven steps, happy path for most installs. This is what the Quickstart page covers.
2. Admin SPA wizard — http://localhost:3000/admin/setup. Five-step browser UI that picks up from wherever the CLI wizard left off. /admin/ auto-redirects here when 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 better 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,
    "openclaw_reachable": false,
    "openclaw_auth": false,
    "model_routing": false,
    "workspace": true
  },
  "version": "0.1.0",
  "setup_completed": false,
  "setup_completed_at": null,
  "next_step": "configure_openclaw"
}

The wizard polls this every 2 seconds while you’re on the steps that depend on external state, so when you fix something in another tab the tick flips green immediately.

The five steps

1. Welcome

What Carabase is, what’s about to happen, and links to the OpenClaw + Tailscale docs (the two things you likely don’t have installed yet).

2. System checks

Live red/green list of:

Check	What it means
HOST_MASTER_KEY configured	Your .env.<env> has a 256-bit AES key. pnpm bootstrap generates this automatically.
Database reachable	The host can connect to Postgres.
OpenClaw gateway reachable	The agent runtime is responding on localhost:18789 (or wherever OPENCLAW_GATEWAY_URL points).
OpenClaw bearer-token auth working	The host’s OPENCLAW_GATEWAY_PASSWORD matches the gateway’s config. Only shown when the gateway is reachable — “I can’t reach it” is a different fix from “I can reach it but the password’s wrong”.
Model routing configured	A model-routing row exists in the integrations table for this workspace.

The Continue button is gated on master_key + db being green. OpenClaw and model_routing can stay amber and you can still proceed (chat won’t work, but everything else does).

3. Model routing

Carabase splits background AI calls into two tiers:

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

The wizard links to AI Engine (/admin/model-routing) where you configure providers. v0.1 ships OpenClaw for the chat path, but utility-* tiers still need a real provider — Ollama (free, local) is the easiest pick if you don’t have an API key handy.

You can skip this step and configure later; the agent just won’t have functional reasoning capabilities until you do.

4. OAuth apps (optional)

If you plan to use the GitHub or Google connectors, you’ll need an OAuth app for each:

• GitHub — for syncing PRs and issues. Uses device-flow OAuth, so you only need a Client ID (no secret).
• Google — for Calendar + Gmail. Needs both a Client ID and Client Secret.

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

5. Done

Click Mark setup complete to flip the workspace_settings.setup_completed flag and head to the dashboard. After this, /admin/ lands you on Connections instead of bouncing back to the wizard.

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

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.