/setup

name: setup
description: Set up GBrain with auto-provision Supabase or PGLite, AGENTS.md injection, first import
triggers:
  - "set up gbrain"
  - "initialize brain"
  - "gbrain setup"
tools:
  - get_stats
  - get_health
  - sync_brain
  - put_page
mutating: true

Setup GBrain

Set up GBrain from scratch. Target: working brain in under 5 minutes.

Contract

• Setup completes with a working brain verified by `gbrain doctor --json` (all checks OK).
• The brain-first lookup protocol is injected into the project's AGENTS.md or equivalent.
• Live sync is configured and verified (a test change pushed and found via search).
• Schema state is tracked in `~/.gbrain/update-state.json` so future upgrades know what the user adopted or declined.
• No Supabase anon key is requested; GBrain uses only the database connection string.

Install (if not already installed)

bun add github:garrytan/gbrain

How GBrain connects

GBrain connects directly to Postgres over the wire protocol. NOT through the Supabase REST API. You need the **database connection string** (a `postgresql://` URI), not the project URL or anon key. The password is embedded in the connection string.

Use the **Transaction pooler** connection string (port 6543), not the direct connection (port 5432). The direct hostname resolves to IPv6 only, which many environments can't reach. Find it: click **Connect** in the top navigation bar, then **Connection String** > **Transaction pooler**, and copy the string.

**Do NOT ask for the Supabase anon key.** GBrain doesn't use it.

Why Supabase

Supabase gives you managed Postgres + pgvector (vector search built in) for $25/mo:

• 8GB database + 100GB storage on Pro tier
• No server to manage, automatic backups, dashboard for debugging
• pgvector pre-installed, just works
• Alternative: any Postgres with pgvector extension (self-hosted, Neon, Railway, etc.)

Prerequisites

• A Supabase account (Pro tier recommended, $25/mo) OR any Postgres with pgvector
• An OpenAI API key (for semantic search embeddings, ~$4-5 for 7,500 pages)
• A git-backed markdown knowledge base (or start fresh)

Available init options

• `gbrain init --supabase` -- interactive wizard (prompts for connection string)
• `gbrain init --url <connection_string>` -- direct, no prompts
• `gbrain init --non-interactive --url <connection_string>` -- for scripts/agents
• `gbrain doctor --json` -- health check after init

There is no `--local`, `--sqlite`, or offline mode. GBrain requires Postgres + pgvector (local PGLite or remote Supabase / self-hosted).

Phase A.5: Choose Topology (run BEFORE Phase A)

GBrain supports three deployment shapes. Pick the right one before installing, because picking wrong creates contention or duplicate work that's painful to unwind. Read `docs/architecture/topologies.md` for the full picture; the short version:

Ask the user this BEFORE running `gbrain init`:

> "Three deployment shapes: > 1. **Single brain (default)** — one machine, one DB, one agent. Pick this if > unsure. > 2. **Cross-machine thin client** — your brain lives on another machine > (e.g. brain-host) running `gbrain serve --http`, and this install just > calls it over MCP. No local DB on this machine. > 3. **Per-worktree code + shared remote artifacts** — Conductor users with > multiple worktrees indexing the same code repo. Each worktree owns its > own code engine; artifacts live on a shared remote brain. For code > engines, configure Voyage's code-tuned model: > `gbrain init --pglite --embedding-model voyage:voyage-code-3 --embedding-dimensions 1024` > (full guidance in `docs/architecture/topologies.md` Topology 3). > > Which fits?"

If the user picks 1 (single brain) — proceed to Phase A

Continue with the existing `gbrain init --supabase` / `--pglite` setup below.

If the user picks 2 (cross-machine thin client)

1. **Confirm a host already exists.** Ask: "Is the remote `gbrain serve --http` already running on the host machine?" If no, the user needs to set up the host first (Phases A-C on the host, then `gbrain serve --http`). Don't try to run init on this machine until the host is up.

2. **Get OAuth credentials from the host operator.** Ask the user to run on the host:

   gbrain auth register-client <name> \
     --grant-types client_credentials \
     --scopes read,write,admin

The `admin` scope is required because `gbrain remote ping` and `gbrain remote doctor` (Tier B convenience commands) call MCP ops with `admin` scope. `read,write` alone breaks ping/doctor.

3. **Run thin-client init on this machine:**

   gbrain init --mcp-only \
     --issuer-url https://<host>:<port> \
     --mcp-url https://<host>:<port>/mcp \
     --oauth-client-id <id> \
     --oauth-client-secret <secret>

Or set `GBRAIN_REMOTE_CLIENT_SECRET` env var instead of the flag (preferred for headless / scripted setup). Pre-flight runs three smoke probes; any failure surfaces an actionable error.

4. **Configure your agent's MCP client.** Add a server entry pointing at `<mcp_url>` with the bearer token. See `docs/mcp/CLAUDE_DESKTOP.md`, `docs/mcp/CLAUDE_CODE.md`, etc. for per-client snippets.

5. **Verify with `gbrain doctor`.** Thin-client doctor runs OAuth discovery, token round-trip, and MCP smoke against the host. Should report `mode: thin-client` with all checks green.

6. **Skip Phases B, C, C.5, and H entirely.** They're for local engines. The host's autopilot handles sync/extract/embed. Thin clients consume only.

7. **Continue to Phase D (brain-first lookup).** It works identically over MCP — the agent uses the same brain-ops skill to query/search/get_page, they just round-trip through the host's `gbrain serve --http`.

If init reports "thin-client config already present", a previous setup already configured this machine. Refusing without `--force` is the correct behavior; either acce