Local quickstart
Short command list to run Brain locally.
Run Brain on your machine for development or evaluation.
For the full install (tools, fork, .env, operator, Ollama, first chat), see Local setup. This page is the short version.
Requirements
- Node.js 24.x (
nvm use— see.nvmrc) - pnpm 11+ (
corepack enable) - Docker (for local Postgres via Compose)
- A model path:
COMMAND_CODE_API_KEYfor built-ins, or a custom model after first sign-in
Steps
# 1. Install (fork https://github.com/akhil-naidu/brain first, then clone YOUR fork)
git clone https://github.com/YOUR_GITHUB_USERNAME/brain.git
cd brain
nvm use # Node 24
corepack enable
pnpm install
# 2. Postgres
docker compose up -d db
# 3. Env
cp .env.example .env
# Required at minimum:
# COMMAND_CODE_API_KEY=... # omit if you only use custom models
# BETTER_AUTH_SECRET=$(openssl rand -base64 32)
# BRAIN_BOOTSTRAP_TOKEN=$(openssl rand -base64 32) # paste on /setup
# BRAIN_DATABASE_URL=postgres://brain:[email protected]:5432/brain
# BRAIN_PUBLIC_URL=http://localhost:3000
# BETTER_AUTH_URL=http://localhost:3000
# Optional (schedules only):
# BRAIN_INTERNAL_TOKEN=$(openssl rand -base64 32)
# BRAIN_INTERNAL_URL=http://127.0.0.1:3000 # default; set if Next is not on :3000
# 4. Dev server (Next + eve)
pnpm devOpen http://localhost:3000.
Next
- Empty database → open
/setupand create the operator account (pasteBRAIN_BOOTSTRAP_TOKENwhen the field appears) - Sign in →
/chat - Continue with First chat or the rest of Local setup
Tips
- Vitest uses a separate database
brain_testsopnpm test/pnpm verifydo not wipe your local operator account onbrain. - If
brain_testis missing on an older volume:
docker compose exec db psql -U brain -d brain -c 'CREATE DATABASE brain_test;'- To reset local auth data entirely:
docker compose down -v && docker compose up -d dbThen open /setup again.