Quickstart

Two commands

From your Carabase Host directory:

pnpm install
pnpm carabase init

pnpm carabase init is an interactive onboarding wizard. Before the steps begin it asks which environment to target — prod is the right choice for a real install. It then walks nine idempotent steps plus a final complete:

1. Environment file — scaffolds .env.<env> from the matching example (for prod that’s .env.production) and fills in the essentials: a fresh 256-bit HOST_MASTER_KEY, a generated OPENCLAW_GATEWAY_PASSWORD, and DATABASE_URL. Both secrets are printed once — save them somewhere safe. You can paste your own values instead of generating them.
2. Database migrate + seed — runs the database migrations against DATABASE_URL and seeds a tiny starter workspace so the Admin SPA isn’t empty on first boot (skip with --no-seed).
3. Start host + resolve workspace — starts the host and polls GET /api/v1/health until it responds, then resolves the workspace id.
4. Timezone — auto-detects your machine’s IANA timezone and confirms it. Daily notes bucket on your local calendar day, so this is worth a glance before data starts flowing.
5. How do you want to think? — configures the LLM provider. The wizard auto-detects local options first — a running Ollama, an installed claude or codex CLI — before asking for a hosted-provider key. If your chat provider can’t also serve embeddings, it prompts inline for a separate embedding key or local URL.
6. What leaves your machine — prints the trust receipt: a sovereignty summary derived from your actual config, never boilerplate. carabase trust shows it again any time.
7. Explore demo data, or start fresh? — optionally seeds the throwaway “Sam Rivera” demo mesh so you can see grounded, cited chat before importing your own data. Delete it any time with carabase demo down.
8. OAuth apps — optional day-2 step; wire up third-party connector credentials now or later from the Admin SPA (skip with --skip-oauth).
9. SOUL.md profile — optional day-2 step; best-effort seeds your owner profile (skip with --skip-soul).
10. Complete — 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 and it won’t rotate HOST_MASTER_KEY unless you ask.

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 TOML config shape is documented in the CLI reference. Useful for automated provisioning; not the path a human typically runs. Add --json (requires --non-interactive) for machine-readable output.

Useful commands after onboarding

pnpm carabase --help            # list every command
pnpm carabase setup status      # system check matrix (same as the SPA wizard's status page)
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 table 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 install the pgvector extension. (Or docker compose up -d if you prefer Docker.)

Optional, recommended:

Thing	Why
An LLM provider	Chat and the agent need a model to talk to. The “How do you want to think?” step configures this; a local Ollama URL or a hosted provider key both work.
OpenClaw	The premium agent runtime. Optional — chat works without it (see below). See OpenClaw for install + config.
Tailscale	Required for the desktop client to reach the host securely. Not required for local-loop use at http://localhost:3000/admin/. See Network model.

Chat works without OpenClaw

Carabase Host ships a multi-engine chat layer, so you are not required to run OpenClaw:

• host_native — the open-source chat floor. Answers turns directly against the model you configured in the provider step, with read-only retrieval over your knowledge graph. This is what a self-host with no gateway uses out of the box.
• openclaw — the premium default when an OpenClaw gateway is configured.
• codex_cli / claude_code — optional read-only bridges to your locally-installed Codex or Claude Code CLI (each authed by your own codex login / claude login).

The runtime defaults to auto, which picks OpenClaw when a gateway is configured and otherwise falls back to host_native — so chat answers from the moment a model provider is set up. (The vendor-CLI bridges are explicit-only and never auto-selected.)

Troubleshooting

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

“pgvector extension not available” — Install the pgvector extension for your Postgres install.

“HOST_MASTER_KEY is not configured” — pnpm carabase init generates this for you. If you’re in a half-set-up state, re-run it — it’s idempotent and won’t rotate the key unless you explicitly ask. Losing this key means losing every encrypted integration credential.

Chat returns an error or 503 — If your runtime resolves to openclaw, the gateway isn’t reachable: check that ~/.openclaw/config.toml’s gateway_password matches your .env.<env>’s OPENCLAW_GATEWAY_PASSWORD (OpenClaw setup). If you’re not running OpenClaw at all, make sure the provider step configured a usable provider — host_native chat needs a model to answer.

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