Quickstart

Three commands

git clone https://github.com/carabase/carabase-host && cd carabase-host
pnpm install
pnpm carabase init

pnpm carabase init is an interactive onboarding wizard (source). It walks you through seven idempotent steps:

1. Pick the environment — defaults to prod. Most people want this; pick dev or staging only if you’re developing the host itself.
2. Write .env.<env> — scaffolds from the matching .env.<env>.example.
3. Generate secrets — a fresh 256-bit HOST_MASTER_KEY and OPENCLAW_GATEWAY_PASSWORD, patched into the env file. Both are printed once so you can paste them into OpenClaw’s config.
4. Create + migrate the database — runs the Drizzle migrations against DATABASE_URL from your env file.
5. Seed the starter workspace — a tiny fixture so the Admin SPA isn’t empty on first boot.
6. Start the host + wait for health — polls GET /api/v1/health until it responds 200. Drops you at a clear next step if OpenClaw or model routing still needs attention.
7. Finish configuration — model routing, OAuth apps (optional), SOUL.md, and flips workspace_settings.setup_completed = true so the Admin SPA stops showing the first-run wizard.

Interrupted mid-wizard? Re-run pnpm carabase init — completed steps are skipped.

After the wizard completes, open http://localhost:3000/admin/ to land on the Admin SPA dashboard.

Non-interactive mode (CI)

pnpm carabase init --env prod --non-interactive --config carabase.init.toml

The config file shape is documented in the CLI reference. Useful for automated provisioning; not the path a human typically runs.

Useful commands after onboarding

pnpm carabase --help            # list every command
pnpm carabase setup status      # system check matrix (same as the SPA wizard's page 2)
pnpm carabase workspace list    # enumerate workspaces on this install
pnpm carabase env show          # which .env file is loaded + sanity checks
pnpm carabase health            # ping the running host
pnpm carabase version           # same as GET /api/v1/version

After pnpm build + pnpm link --global, the bare carabase (or short alias cb) works from any directory.

Prerequisites

The wizard’s pre-flight checks verify these for you — the section below is what to install BEFORE running pnpm install.

Thing	How
Node 22+	brew install node@22
pnpm 9+	corepack enable && corepack prepare pnpm@latest --activate
PostgreSQL 16 + pgvector	brew install postgresql@16 && brew services start postgresql@16 then ./scripts/setup-native-db.sh to install pgvector. (Or docker compose up -d if you prefer Docker.)

Optional, recommended:

Thing	Why
OpenClaw CLI	The agent runtime. Without it, the host runs fine but chat returns 503. See OpenClaw for install + config.
Tailscale	Required for the desktop client to reach the host securely. Not required for local-loop dev at http://localhost:3000/admin/. See Network model.

Dev and staging (for host contributors)

If you’re modifying Carabase Host itself — writing tests, adding routes, rebuilding the MCP surface — you want dev or staging instead of prod:

pnpm carabase init --env dev          # local-loop iteration, safe to reset
pnpm carabase init --env staging      # realistic sam-rivera corpus, safe to reset
pnpm dev:dev                          # run against dev with file-watching
pnpm dev:staging                      # run against staging with file-watching

The reset guardrail (src/db/reset.ts) classifies by db-name suffix: *_dev / *_staging → safe to wipe, *_prod / *_production → refuses without CARABASE_I_KNOW=1. See Environments for the full per-env pnpm-script matrix.

Legacy bootstrap script

A pre-CLI bash script (pnpm bootstrap) still lives in the repo for users on older branches or CI systems that can’t run interactive tools. It does the same idempotent pipeline non-interactively and defaults to dev:

pnpm bootstrap                   # defaults to --env dev
pnpm bootstrap --env prod        # explicit prod target
pnpm bootstrap --env prod --skip-seed

Implementation: scripts/install.sh.

Troubleshooting

“psql not found” — Install Postgres: brew install postgresql@16 && brew services start postgresql@16.

“pgvector extension not available” — Run ./scripts/setup-native-db.sh to build pgvector from source for your Postgres install.

“HOST_MASTER_KEY is not configured” — pnpm carabase init should generate this for you. If you’re running from a half-set-up state, re-run pnpm carabase init — it’s idempotent and won’t rotate the key unless you explicitly ask.

Agent chat returns 503 — OpenClaw isn’t reachable. Check ~/.openclaw/config.toml for the same gateway_password value as your .env.<env>’s OPENCLAW_GATEWAY_PASSWORD. See OpenClaw setup.

The Admin SPA shows “no workspace” — The seed didn’t run. pnpm carabase workspace list to check, pnpm db:seed:<env> to create the default workspace.