A step-by-step walkthrough for deploying a personal AI brain, then growing it into a company brain — built to be run on your own, with every known pothole flagged before you reach it.
GBrain is a memory system for AI agents. Before you touch a terminal, understand the three things that make it different from "a vector database with extra steps":
works_at, invested_in, attended) are extracted without LLM calls, so multi-hop questions ("who at Acme did we meet through the YC batch?") actually resolve.The other load-bearing idea: the brain is a git repository. Markdown pages in a repo are the system of record; Postgres holds the index and embeddings. Any agent with repo access can participate, and multiple agents can share one brain through ordinary git push/pull.
Never npm install gbrain — the npm package with that name is unrelated. Install only from GitHub:
bun install -g github:garrytan/gbrainThere are three on-ramps. Start on the lightest one that proves value to you — you can graduate later, and nothing you build is thrown away.
| Path | Time | Cost | What you get | Start here if… |
|---|---|---|---|---|
| Local bootstrap | ~15 min | $0 | PGLite brain on your laptop, identity files, MCP wired into Claude Code / Codex, private GitHub repo | You want to learn the system or demo it. No server, no Docker. |
| Personal brain (Track A) | ~2 hrs | $100–150/mo | Always-on agent on Render, Telegram interface, Supabase-backed memory, overnight enrichment | You want a real assistant that works while you're away. |
| Company brain (Track B) | +90 min | <$100/mo for 25 users | Multi-source shared brain, per-person OAuth scoping enforced in SQL, HTTP MCP any client can connect to | A working Track A exists and a 10–50 person team should share it. |
The local bootstrap is one paste into Claude Code or Codex in an empty folder:
Read and follow every step of:
https://raw.githubusercontent.com/garrytan/gbrain/latest-stable/BOOTSTRAP_FOR_AGENTS.md
Goal: set yourself up as my persistent personal agent in this folder, with gbrain
as your memory. Interview me before writing any identity file — never invent
answers. Ask before anything destructive. You are not done until
`gbrain bootstrap verify` exits 0.The agent interviews you (6 questions), writes SOUL.md / USER.md / MEMORY.md from your answers, initializes a PGLite brain, wires MCP, and creates a private repo. Done means gbrain bootstrap verify exits 0.
An always-on agent on Render, talked to over Telegram, remembering everything in a git-backed brain. Eight steps, ~2 hours. Steps 1–3 are pure account setup — batch them.
Goal: separate the agent's configuration from its knowledge
your-org/myagent — the workspace: skills, crons, config.your-org/myagent-brain — the brain: people, meetings, notes, indexed knowledge.Leave both empty; GBrain populates them on first run.
Why two repos: the workspace is code-like (you edit it), the brain is data-like (the agent writes it). Keeping them separate means you can wipe or share one without the other.
Goal: give the agent write access to exactly those two repos, nothing else
GitHub → Settings → Developer Settings → Personal Access Tokens → Fine-grained tokens. Name it, set a long expiration, select only the two repos, and grant Read + Write on Contents, Metadata, Pull requests. Save the token.
Freshly created repos often don't appear in the token's repo picker until you reload the page. This is the single most fiddly step of the whole setup — expect it, so you don't assume you broke something.
Goal: a chat interface with zero UI work
In Telegram, message @BotFather → send /newbot → pick a name → copy the bot token it returns.
Goal: the agent runtime (OpenClaw) running in the cloud
In AlphaClaw: enter the workspace repo path, choose "Use existing", paste the GitHub token (step 2) and the Telegram token (step 3), deploy. First build takes ~5 minutes.
The base Render tier will run out of memory. Render Pro (~$85/mo) is the minimum viable spec for GBrain + OpenClaw. Don't try to save money here — the failure mode (the install just dies mid-way) doesn't look like a memory problem, and it will cost you an evening.
Goal: the agent can think (Anthropic) and embed (OpenAI or Voyage)
In the AlphaClaw Providers tab: OpenAI and Anthropic keys are required. Voyage is optional but recommended — GBrain defaults to voyage-4 embeddings + rerank-2.5, one key covers both, and it's roughly half the cost of OpenAI embeddings. Perplexity adds web search.
Goal: initialized brain + full skill library
# in the brain repo directory
gbrain init --supabase
# in the workspace repo directory
gbrain skillpack scaffold --allinit --supabase launches a wizard asking for connection details (you get those in step 7). skillpack scaffold --all copies 50+ bundled skills into the workspace as editable files.
Want to defer database spend? gbrain init --pglite gives an embedded zero-config brain now; gbrain migrate --to supabase upgrades later with no data loss.
Goal: production-scale embeddings + search. This step is where 90% of failed setups fail
7a — Enable pgvector. Create the project (region nearest your Render deploy), then Dashboard → Database → Extensions → enable vector. Skipping this makes every embedding write fail with type "vector" does not exist. Five seconds here saves hours later.
7b — Use the Transaction pooler connection string. Supabase shows three near-identical connection strings. The Direct connection (port 5432, host db.PROJECT.supabase.co) is IPv6-only and fails on most Render hosts. Pick Transaction pooler (port 6543, host aws-0-….pooler.supabase.com) — IPv4-safe and storm-resilient. GBrain detects port 6543 and adapts automatically.
gbrain config set database_url \
"postgresql://postgres.PROJECT:PASSWORD@aws-0-us-west-1.pooler.supabase.com:6543/postgres"7c — Fix the IPv4 hole for migrations. GBrain runs schema migrations and worker locks on a direct connection it derives itself — which is IPv6-only. On IPv4-only hosts the symptom is nasty: reads work, migrations hang silently. Two fixes:
# Free: route DDL through the Session pooler (port 5432, pooler host)
export GBRAIN_DIRECT_DATABASE_URL="postgresql://postgres.PROJECT:PASSWORD@aws-0-us-west-1.pooler.supabase.com:5432/postgres"
# Or paid: Supabase IPv4 add-on (~$4/mo, Pro tier)7d — Verify.
gbrain doctorAll green (schema, connectivity, pgvector, embedder) = done. Any yellow points back at 7a/7b/7c.
Remember the three gotchas as a story, not a checklist: "the extension that isn't on, the wrong one of three identical strings, and the connection that half-works." Failure narratives stick. Also: as ingestion scales, the Supabase DB becomes the bottleneck before CPU or LLM cost — upgrade the instance before the symptoms (silent inserts, sync timeouts, backfill stalls) appear.
Goal: proof of life, then real memories
Message your Telegram bot. A context-aware reply that can search the brain means OpenClaw + GBrain + integration all work. Then run the cold-start skill ("fill my brain") to import Gmail, calendar, and contacts.
| Component | Monthly |
|---|---|
| Render Pro | ~$85 |
| Supabase (small) | $0–25 |
| Embeddings | $5–20 (Voyage ≈ half) |
| Anthropic API | $50+ usage-dependent |
| Sustainable total | ~$100–150 |
Extends a working Track A install to a 10–50 person team. ~90 minutes. Nothing gets redesigned — same runtime, same Supabase, same CLI. You add three things: multiple sources, per-person OAuth scoping, and per-person infrastructure (folders, crons, skills).
Goal: a database multiple users can reach
gbrain migrate --to supabase
gbrain doctor
gbrain stats # page/chunk counts should match pre-migrationAlready on Supabase from Track A? Skip.
Goal: distinct pools of knowledge with distinct audiences
sudo mkdir -p /srv/brain-repos && sudo chown $USER /srv/brain-repos
cd /srv/brain-repos
git clone git@github.com:your-org/shared-wiki.git shared
git clone git@github.com:your-org/customers.git customers
git clone git@github.com:your-org/internal-docs.git internal
gbrain sources add shared --path /srv/brain-repos/shared --name "Shared company wiki"
gbrain sources add customers --path /srv/brain-repos/customers --name "Customer notes"
gbrain sources add internal --path /srv/brain-repos/internal --name "Internal-only"
gbrain sync --all
gbrain sources status # page counts + last-sync per sourceInside a source, give each person their own folder (customers/alice/…) plus a mutual-visibility folder (customers/shared-customers/…) — this prevents write collisions without more infrastructure.
The design question to answer before typing anything: "who should never see what?" That answer defines the sources. Typical trio: shared (everyone), customers (sales), internal (legal/HR). Scoping is enforced at the SQL layer, not by prompt engineering — that's the point of the whole exercise.
Goal: any teammate's AI client can connect
# dev: tunnel with ngrok
gbrain serve --http --port 3131 --bind 0.0.0.0
ngrok http 3131 --domain your-brain.ngrok.app
# production: real hostname + TLS (public URL must match, for OAuth metadata)
gbrain serve --http --port 3131 --bind 0.0.0.0 \
--public-url https://brain.acme-co.com
curl https://brain.acme-co.com/health # → {"status":"ok"}The first server start prints an admin bootstrap token to stderr. Save it — it's your first login to the admin dashboard at /admin.
Goal: each person writes to one source, reads a defined set
# Alice (sales): writes customers, reads customers + shared
gbrain auth register-client alice \
--grant-types client_credentials \
--scopes "read write" \
--source customers \
--federated-read customers,shared
# Bob (ops): writes internal, reads internal + shared
gbrain auth register-client bob \
--grant-types client_credentials \
--scopes "read write" \
--source internal \
--federated-read internal,sharedEach command prints a client_id + client_secret — save both. Flag grammar: --scopes is space-separated and quoted; --source is the single write target; --federated-read is the comma-separated read set, enforced in SQL.
Shortcut for agent harnesses: gbrain agent register <name> --harness claude-code --preset coding-agent --url https://brain.acme-co.com/mcp mints a scoped client + 30-day token and prints a paste block. Presets: daily-driver (personal assistant) and coding-agent (write-isolated project work).
Goal: demonstrated, not assumed, privacy
From a machine that is not the brain host, impersonate each client and search for something they must not see:
gbrain init --mcp-only \
--issuer-url https://brain.acme-co.com \
--mcp-url https://brain.acme-co.com/mcp \
--oauth-client-id <alice_id> --oauth-client-secret <alice_secret>
gbrain whoami
gbrain search "performance review" # Alice: must return NOTHING from internal
# re-init as Bob with --force, repeat — Bob sees internal+shared, no customersThis is the moment the company brain earns trust — run it before anyone else connects, and again in front of the team. Searching for the sensitive thing as the wrong person and getting nothing back converts "we promise it's private" into "watch."
Goal: scheduled work that runs as the right person
Crons are markdown files in the workspace repo, one folder per person; the client: field decides whose OAuth credential runs the task — so a cron can never write across boundaries:
# crons/alice/07am-customer-digest.md
---
schedule: "0 7 * * *"
client: alice
---
# Customer pipeline digest
Pull every customer page in customers/alice/ with activity in the last
7 days. Summarize changes and next actions, post to Slack, save a copy.Skills live in skills/<name>/SKILL.md (scaffold with gbrain skillify scaffold <name>). Gate a skill with allowed_clients: [carol] frontmatter — and remember the real guardrail is still the data layer: even if a skill runs, the caller's OAuth scope limits what it can touch.
Shared rule files at skills/_*-rules.md (filing rules, output rules, excluded-people privacy gate) are read by every skill — edit once, applied everywhere.
Goal: adoption, not just access. ~45 min per person
Credentials first → generic query → generic answer → they bounce and never come back. Pre-populate → walkthrough → credentials is the sequence that produces adoption.
Goal: everyone plugged in; the brain maintains itself
Teammates connect however they already work: thin-client CLI (gbrain init --mcp-only … routes search/query/think through the server), Claude Code/Codex via gbrain agent register, Claude Desktop via Settings → Integrations (never claude_desktop_config.json for remote servers — it fails silently), ChatGPT/Perplexity via the OAuth credentials.
gbrain think "What's the latest update from acme-co? When did we last talk?"
# → synthesized answer, every claim cited, gaps admitted
gbrain autopilot # enrichment daemon, all sources, sleeps when healthy
gbrain doctor --remediate --yes --target-score 90 --max-usd 5 # self-healing, capped spend
gbrain sources status # per-source dashboardOAuth only guards the HTTP MCP path. If agent containers sit next to Postgres, they can skip OAuth entirely by dialing the DB directly. Isolate Postgres on its own network, publish loopback-only, and never hand agents the DATABASE_URL.
Once a track is running, three tests show you — and anyone watching over your shoulder — what the brain actually does. Each takes a minute; run them in order.
Five potholes account for most lost evenings. When something feels wrong, check this list before anything else:
--scopes "read write" is space-separated and quoted; commas are rejected.| Symptom | Cause | Fix |
|---|---|---|
| Install dies on Render | Memory too small | Upgrade to Render Pro |
| "type vector does not exist" | pgvector not enabled | Supabase → Database → Extensions → enable vector |
| Reads work, migrations hang | Direct connection is IPv6-only | Set GBRAIN_DIRECT_DATABASE_URL to Session pooler, or buy the IPv4 add-on |
| Teammate sees nothing | --source unset → falls to empty default | gbrain auth list; re-register with explicit --source |
| Teammate sees a restricted page | Possible scoping leak | gbrain search "…" --json, inspect source_id; if truly cross-boundary, file an issue |
| OAuth /token returns 401 | Secret lost (server stores only a hash) | gbrain auth revoke-client <id>, re-register |
| Postgres connections exhausted | Parallel syncs × workers > pool | gbrain sync --all --parallel 2 --workers 2, or raise max_connections |
| First sync feels stuck | Every page embeds on first pass | Watch page count in gbrain sources status; check embedder throttling |
# install (never from npm)
bun install -g github:garrytan/gbrain
# brains
gbrain init --pglite # local, zero-config
gbrain init --supabase # production wizard
gbrain migrate --to supabase # upgrade path
# sources & sync
gbrain sources add <name> --path <path> --name "<label>"
gbrain sync --all
gbrain sources status
# serve & auth
gbrain serve --http --port 3131 --bind 0.0.0.0 --public-url https://brain.example.com
gbrain auth register-client <name> --grant-types client_credentials \
--scopes "read write" --source <src> --federated-read <src1,src2>
gbrain agent register <name> --harness claude-code --preset daily-driver --url …/mcp
# thin client (teammate machine)
gbrain init --mcp-only --issuer-url … --mcp-url …/mcp \
--oauth-client-id … --oauth-client-secret …
# daily use & health
gbrain search "<query>" gbrain think "<question>" gbrain whoami
gbrain doctor gbrain autopilot gbrain statsDeep docs in the repo: docs/INSTALL.md · docs/tutorials/personal-brain.md · docs/tutorials/company-brain.md · docs/mcp/ per-client setup · SECURITY.md trust model. Issues: github.com/garrytan/gbrain/issues
Or
Everything on this page is work ANDAO does for companies that want it governed, audited, and running daily operations. One conversation — direct, calm, exact.
Write to us