Local setup

Install the tools, fork and clone the repo, then keep going in this terminal or in VS Code. After each command, run the Check. Skip a step if that check already passes.

Pick macOS, Windows, or Linux in the OS tabs. After you clone, pick This terminal or VS Code. Both choices stick for the rest of this page.

No Vercel account, Neon, or Vercel AI Gateway.

What Brain needs

Brain runs with these four.

To follow this guide

These are for installing and cloning. They are not part of Brain.

1. Open a terminal

2. Compiler tools and Git

xcode-select --install

xcode-select -p

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile

eval "$(/opt/homebrew/bin/brew shellenv)"

brew --version

brew install git

git --version

Tell Git who you are (once)

Use your real name and the email on your GitHub account. Replace the quoted text, then paste.

git config --global user.name "Your Name"

git config --global user.email "[email protected]"

git config --global init.defaultBranch main

Check

git config --global --get user.name

git config --global --get user.email

Those two lines should print the name and email you just set.

3. nvm (Node Version Manager)

nvm installs a specific Node.js version. Brain requires Node 24. Other versions (18, 20, 22) will fail.

brew install nvm

mkdir -p ~/.nvm

echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc

echo '[ -s "$(brew --prefix)/opt/nvm/nvm.sh" ] && . "$(brew --prefix)/opt/nvm/nvm.sh"' >> ~/.zshrc

command -v nvm

source ~/.zshrc

Check the nvm version

nvm --version

You should see a number like 0.40.3.

4. Node 24

Install Node 24, make it the default, and turn it on:

nvm install 24

nvm alias default 24

nvm use 24

Check

node -v

Must start with v24. — for example v24.19.0. If you see v18, v20, or v22, run nvm use 24 again.

5. pnpm

pnpm installs the project’s JavaScript dependencies. Brain blocks npm and yarn — if you run npm install it will error on purpose.

brew install pnpm

Check

pnpm --version

You need 11 or higher. On macOS, if brew gave an older pnpm: brew upgrade pnpm.

6. Docker

Docker runs Postgres (Brain’s database) in a container. You do not install Postgres by hand.

Check

docker version

docker compose version

Each should print a version. If you see Cannot connect to the Docker daemon, Docker is not running yet — wait and try again.

7. openssl

Used to generate login secrets.

openssl version

8. Fork, then clone

Do not clone akhil-naidu/brain directly. Fork it to your GitHub account, then clone your fork.

Fork on GitHub

1. Open https://github.com/akhil-naidu/brain in a browser
2. Sign in to GitHub if asked
3. Click Fork (top right)
4. Keep yourself as the owner and click Create fork
5. Wait until the URL looks like https://github.com/YOUR_GITHUB_USERNAME/brain

Clone your fork

On Windows, stay in Ubuntu. Do not clone into /mnt/c or C:\.

mkdir -p ~/dev

cd ~/dev

Replace YOUR_GITHUB_USERNAME with the GitHub username from the fork URL. You can also copy the URL from the green Code button on your fork.

HTTPS (works for most people):

git clone https://github.com/YOUR_GITHUB_USERNAME/brain.git

Or SSH (only if you already use GitHub SSH keys) — skip this if you used HTTPS:

git clone [email protected]:YOUR_GITHUB_USERNAME/brain.git

If GitHub asks you to sign in, use your GitHub login, a personal access token, or an SSH key.

cd brain

Point upstream at the original repo so you can pull updates later:

git remote add upstream https://github.com/akhil-naidu/brain.git

Check

pwd

The path should end with /brain.

git remote -v

origin should be your fork. upstream should be akhil-naidu/brain.

cat .nvmrc

Must print 24.

git status

Should mention On branch main.

9. Continue here, or open VS Code

The next commands (pnpm install, Docker, .env, pnpm dev) run in a terminal inside the brain folder. You can stay in this terminal, or open the folder in an editor for a better view of the files.

Cursor, Antigravity, Windsurf, Zed, and similar editors work like VS Code: open the folder, then use the built-in terminal.

Stay in this terminal

You should already be in the repo from step 8. If the prompt is somewhere else:

cd ~/dev/brain

Check

pwd

The path should end with /brain. Skip to step 10.

Install VS Code

Skip this if code --version already works.

brew install --cask visual-studio-code

code --version

Open in VS Code

From inside ~/dev/brain:

code .

That opens this repo in VS Code.

Then open VS Code’s terminal:

1. Click the terminal icon in the top-right (panel layout), or click Terminal in the bottom panel
2. Or press Control+` (Control and the backtick key, under Escape)
3. Or menu Terminal → New Terminal

A prompt appears at the bottom. It should already be in brain.

Check

pwd

The path should end with /brain. Then go to step 10 and paste the rest of the commands in this VS Code terminal.

For a second long-running command (the Ollama SSH tunnel later), use Terminal → New Terminal again.

If code . fails, use File → Open Folder and pick ~/dev/brain.

10. Install JavaScript packages

Use the same terminal you chose in step 9. Pick This terminal or VS Code in the tabs — the choice sticks. pwd must end with /brain.

cd ~/dev/brain

nvm use

node -v

Must still be v24.x. Then:

pnpm install

This can take several minutes. Lines about Fumadocs / postinstall are normal.

Check: the command ends with no error, and this prints a path:

ls node_modules

If you see Use pnpm to install, you used npm install. Stop. Use pnpm install only.

11. Start Postgres

Docker must be running. Same terminal as step 10 (pwd still ends with /brain). Do not cd again if you are already there.

docker compose up -d db

Wait a few seconds.

docker compose ps

The db row should look running or healthy.

docker compose exec db pg_isready -U brain -d brain

Should print accepting connections.

This creates:

• Database brain — user brain, password brain (the app)
• Database brain_test — for automated tests only (will not wipe your login)

If port 5432 is already used by another Postgres: stop that other Postgres, or change the host port in docker-compose.yml and use the new port in BRAIN_DATABASE_URL.

12. Create .env

This file holds secrets. It is not committed to Git.

Same folder as step 10:

cp .env.example .env

Generate a session secret. Copy the whole line of output (letters, numbers, +, /, =):

openssl rand -base64 32

Generate a bootstrap secret. Run this again so you get a different string:

openssl rand -base64 32

Pick This terminal (edit with nano) or VS Code (click .env in the sidebar). Same tab as step 9.

nano .env

These next boxes are lines to put in that file, not commands for the shell. If a key is already there with a # in front, delete the # and set the value. Paste your two openssl outputs. Do not reuse one string for both secrets.

BETTER_AUTH_SECRET=paste-first-openssl-output

BRAIN_BOOTSTRAP_TOKEN=paste-second-openssl-output

BRAIN_DATABASE_URL=postgres://brain:[email protected]:5432/brain

BRAIN_PUBLIC_URL=http://localhost:3000

BETTER_AUTH_URL=http://localhost:3000

Leave COMMAND_CODE_API_KEY= empty if you will use Ollama only.

Do not send these values in Slack or email.

Check — all five lines should print with values after =:

grep -E '^(BETTER_AUTH_SECRET|BRAIN_BOOTSTRAP_TOKEN)=' .env

grep -E '^(BRAIN_DATABASE_URL|BRAIN_PUBLIC_URL|BETTER_AUTH_URL)=' .env

Optional later (not needed for first chat)

13. Run Brain

Same terminal as step 10. Do not cd if pwd already ends with /brain.

nvm use

pnpm dev

Leave this Terminal running. You should see Next.js ready on port 3000.

Open a browser:

http://localhost:3000

• Empty database → you go to setup
• Operator already exists → sign-in

If the page errors, read the pnpm dev window: Docker not running, empty BETTER_AUTH_SECRET, or wrong BRAIN_DATABASE_URL are the usual causes.

14. Create the operator account

1. Open http://localhost:3000/setup
2. Title should be Create operator
3. Fill in:
   • Name — how you want to appear
   • Email — you will sign in with this
   • Password — at least 8 characters
   • Bootstrap token — paste BRAIN_BOOTSTRAP_TOKEN from .env (exact match)
4. Click Create account

You land on /chat. Brain creates a personal workspace. You are the instance admin. Other people stay invite-only until you change policy — Accounts and sign-in.

If you see Setup closed, someone already created the operator. Use http://localhost:3000/sign-in.

To wipe local users and start /setup again:

docker compose down -v

docker compose up -d db

Then open /setup again.

15. Ollama on a VPS (the model)

Brain sends chat to an OpenAI-compatible URL. Ollama provides that at http://HOST:11434/v1.

Your laptop must reach Ollama (discovery waits only 4 seconds).

15.1 On the VPS

From your laptop, log into the server (replace user and host):

ssh YOUR_USER@YOUR_VPS_HOST

Install Ollama:

curl -fsSL https://ollama.com/install.sh | sh

Download a model that fits the VPS RAM. Example:

ollama pull llama3.2

Smaller if RAM is tight: llama3.2:1b, qwen2.5:3b, phi4-mini.

Check on the VPS

ollama list

curl -sS http://127.0.0.1:11434/api/tags

You should see the model name in the JSON. Stay logged in or keep Ollama running as a service, then you can leave this SSH session.

15.2 On the laptop — SSH tunnel

This makes the VPS look like 127.0.0.1:11434 on your machine.

Open a new terminal (Ubuntu on Windows). Do not stop pnpm dev.

Paste (same user and host as above):

ssh -N -L 11434:127.0.0.1:11434 YOUR_USER@YOUR_VPS_HOST

-N means “forward ports only, no remote shell”. Leave this window open.

Open another terminal window and check:

curl -sS http://127.0.0.1:11434/api/tags

You should see the same JSON as on the VPS.

If that fails: tunnel window closed, Ollama down, or something else already using 11434 on this machine.

If 11434 is already used on the laptop, forward a different local port:

ssh -N -L 11435:127.0.0.1:11434 YOUR_USER@YOUR_VPS_HOST

Then in Brain use base URL http://127.0.0.1:11435/v1.

15.3 Alternative: public URL

Only if you cannot use a tunnel: bind Ollama to 0.0.0.0:11434 (OLLAMA_HOST), firewall only your laptop IP, and use http://VPS_PUBLIC_IP:11434/v1 (or HTTPS). Prefer HTTPS + an allowlist.

16. Add Ollama in Brain

Stay signed in as the operator.

1. In the left sidebar click Models, or open http://localhost:3000/models
2. Under Start with a model, click the Ollama card (subtitle Running locally — that is correct with the tunnel). If you already have models, the header button is Add model.
3. The Add model dialog opens with Ollama defaults already filled. Adjust if needed:

4. Click Fetch models (next to Base URL)
5. Click the id you pulled (for example llama3.2) so Model id fills in
6. Click Save

The model appears under Your models with All workspaces or This workspace, and No key.

If Fetch models fails: is the tunnel window still open? Did laptop curl to /api/tags work? Does the URL end with /v1? You can type Model id by hand from ollama list and still Save.

More: Custom models.

17. Send a test chat

1. Sidebar New chat, or http://localhost:3000/chat
2. In the composer, open the model menu and pick the display name you saved (for example Ollama VPS)
3. Set mode to Ask (plain reply, no tools) or leave Agent. Shift+Tab switches modes — Ask vs Agent
4. Paste this into the box:

Reply with exactly: Brain is running.

5. Press Enter

A streamed reply means install worked. Next: First chat.

Chat isn't available means no custom model and no COMMAND_CODE_API_KEY. Finish section 16, or add a Command Code key and restart pnpm dev.

Turn errors usually mean the tunnel dropped, the model id is wrong, the VPS is out of memory, or the base URL is missing /v1.

18. Quick tour of the rest of the app

You do not need to configure these on day one. Click each once so you know where it lives:

When you connect tools later: /tools → Connect (Notion, ClickUp, …) or admin Set up then Connect (GitHub, Slack). Turn the app on for the chat. Use Agent. Writes may ask for approval. Local OAuth callback origin is http://localhost:3000.

Optional playbook test: /playbooks → add a prompt Say hello from a playbook. → click that playbook’s name.

Local pnpm dev does not run the minute cron. Use Run now (playbook schedules) or Run once (morning brief) on /schedules. Production unattended runs need BRAIN_INTERNAL_TOKEN — Schedules.

19. Next time you open the laptop

Start Docker (Docker Desktop on macOS/Windows) and wait until the engine is running.

Pick This terminal or VS Code, same as before.

cd ~/dev/brain

Then:

nvm use

docker compose up -d db

pnpm dev

Sign in at http://localhost:3000/sign-in.

If you use VPS Ollama, in a second terminal (Terminal → New Terminal in VS Code), before chatting:

ssh -N -L 11434:127.0.0.1:11434 YOUR_USER@YOUR_VPS_HOST

Stop Brain with Ctrl+C in the pnpm dev window. Postgres can stay running.

20. Troubleshooting

If brain_test is missing (old Docker volume):

docker compose exec db psql -U brain -d brain -c 'CREATE DATABASE brain_test;'

Optional quality gate:

export BRAIN_DATABASE_URL=postgres://brain:[email protected]:5432/brain

pnpm run verify

More: Self-hosting troubleshooting.

21. Optional: Command Code built-in models

If you have a Command Code API key, add this line to .env (not in Terminal):

COMMAND_CODE_API_KEY=paste-your-key

Stop pnpm dev with Ctrl+C, then:

pnpm dev

Open /models. Your models lists custom endpoints first. Built-in models lists each Command Code model with an In chat switch. Turn one off to hide it from this workspace's composer.

You can use Command Code and Ollama. Chat does not require Command Code when a custom model exists. Models overview.

Checklist

• Terminal opens
• git --version works, name and email set
• nvm --version works after a new Terminal
• node -v is v24.x
• pnpm --version is 11+
• Docker running; docker compose version works
• Repo forked; cloned your fork; pwd ends with /brain
• Still in this terminal or repo open in VS Code with pwd ending /brain
• pnpm install finished
• docker compose up -d db healthy
• .env has the five required values
• pnpm dev → http://localhost:3000
• /setup with bootstrap token → /chat
• VPS Ollama + laptop tunnel + curl to /api/tags
• /models → Ollama → Fetch models → Save
• /chat → that model → a reply

Next

• Local quickstart (short command list)
• Accounts and sign-in
• First chat
• Settings map
• Production deploy