Self-host GBrain, shared memory for your agents

Create the VM#

On your computer (pick another name if my-gbrain is taken):

ssh exe.dev new --name=my-gbrain
ssh my-gbrain.exe.xyz

Everything else runs on the VM, as exedev.

Install Bun and GBrain#

GBrain runs on Bun. Install it, then GBrain's stable release:

curl -fsSL https://bun.sh/install | bash
export PATH="$HOME/.bun/bin:$PATH"
bun install -g github:garrytan/gbrain#latest-stable
gbrain --version

Expect gbrain 0.60 or later. Bun notes that it blocked a postinstall script; that's fine on a new install.

Start PostgreSQL#

Generate the database password and GBrain's owner token into one private file, and run PostgreSQL with pgvector on localhost only:

mkdir -p ~/gbrain && cd ~/gbrain
if [ ! -e .env ]; then
  install -m 600 /dev/null .env
  cat >> .env <<EOF
# Secrets for PostgreSQL and gbrain.service. Back this file up.
POSTGRES_PASSWORD=$(openssl rand -hex 24)
GBRAIN_ADMIN_BOOTSTRAP_TOKEN=$(openssl rand -hex 32)
EOF
fi
cat > compose.yaml <<'EOF'
services:
  postgres:
    image: pgvector/pgvector:pg16
    restart: unless-stopped
    environment:
      POSTGRES_USER: gbrain
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: gbrain
    ports:
      - "127.0.0.1:5432:5432"
    volumes:
      - ./postgres:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "gbrain"]
      interval: 5s
      retries: 20
EOF
sudo systemctl enable --now docker.service
docker compose up -d --wait

Expect Container gbrain-postgres-1 Healthy.

Create the brain#

Point GBrain at the database. --no-embedding starts it keyless, with keyword search:

. ~/gbrain/.env
gbrain init --url "postgresql://gbrain:$POSTGRES_PASSWORD@127.0.0.1:5432/gbrain" \
  --no-embedding --non-interactive

It ends with suggestions for wiring a local agent; skip those, since agents connect over HTTP here. The configuration is in ~/.gbrain.

Run the server#

exe.dev's proxy forwards https://<vm>.exe.xyz/ to port 8000, so GBrain listens there, on all interfaces, with that address as its public URL (for OAuth and dashboard links):

sudo tee /etc/systemd/system/gbrain.service >/dev/null <<EOF
[Unit]
Description=GBrain MCP server (gbrain serve --http)
After=network-online.target docker.service
Wants=network-online.target docker.service

[Service]
User=exedev
WorkingDirectory=/home/exedev
EnvironmentFile=/home/exedev/gbrain/.env
Environment=PATH=/home/exedev/.bun/bin:/usr/local/bin:/usr/bin:/bin
ExecStart=/home/exedev/.bun/bin/gbrain serve --http --port 8000 --bind 0.0.0.0 --public-url https://$(hostname).exe.xyz
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now gbrain

Its log warns that GBRAIN_HTTP_CORS_ORIGIN is unset. That only matters for MCP clients running in a web page; leave it.

Check it#

Check health, that /mcp refuses a request without a key, and that a key works (a throwaway one, revoked at the end):

sleep 5
curl -s http://localhost:8000/health; echo
curl -s -o /dev/null -w '%{http_code}\n' -X POST http://localhost:8000/mcp
key=$(gbrain auth create setup-check --scopes read | grep -o 'gbrain_[0-9a-f]*')
curl -s -X POST http://localhost:8000/mcp -H "Authorization: Bearer $key" \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"check","version":"1"}}}' |
  grep -o '"serverInfo":{[^}]*}'
gbrain auth revoke setup-check

Expect "status":"ok" with "engine":"postgres", then 401, then "serverInfo":{"name":"gbrain",...}.

Then make a key for each agent, as in Connect your agents:

gbrain auth create laptop-claude --scopes read,write

Back up nightly#

This script dumps the database with pg_dump (safe while GBrain runs) and adds ~/.gbrain and ~/gbrain's compose.yaml and .env. It keeps the 14 newest:

mkdir -p ~/bin ~/backups
cat > ~/bin/gbrain-backup <<'EOF'
#!/bin/bash
# Back up gbrain to ~/backups/gbrain-<time>.tar.gz: a pg_dump of the
# database (safe while the server runs), ~/.gbrain, and ~/gbrain's
# compose.yaml and .env. Keeps the 14 newest.
set -euo pipefail
umask 077
work=$(mktemp -d)
trap 'rm -rf "$work"' EXIT
mkdir -p "$HOME/backups"
docker compose -f "$HOME/gbrain/compose.yaml" exec -T postgres \
  pg_dump -U gbrain -Fc gbrain < /dev/null > "$work/gbrain.dump"
out="$HOME/backups/gbrain-$(date -u +%Y%m%d-%H%M%S).tar.gz"
tar -czf "$out.part" -C "$work" gbrain.dump \
  -C "$HOME" --exclude=.gbrain/run .gbrain gbrain/compose.yaml gbrain/.env
mv "$out.part" "$out"
ls -1t "$HOME"/backups/gbrain-*.tar.gz | tail -n +15 | xargs -r rm --
echo "$out"
EOF
chmod +x ~/bin/gbrain-backup

Run it nightly, around 03:30 UTC:

sudo tee /etc/systemd/system/gbrain-backup.service >/dev/null <<'EOF'
[Unit]
Description=Back up gbrain to ~/backups

[Service]
Type=oneshot
User=exedev
ExecStart=/home/exedev/bin/gbrain-backup
EOF
sudo tee /etc/systemd/system/gbrain-backup.timer >/dev/null <<'EOF'
[Unit]
Description=Back up gbrain nightly

[Timer]
OnCalendar=*-*-* 03:30:00 UTC
RandomizedDelaySec=15m
Persistent=true

[Install]
WantedBy=timers.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now gbrain-backup.timer

Make one now and check that it restores, into a scratch database:

backup=$(~/bin/gbrain-backup)
rm -rf /tmp/restore-check && mkdir /tmp/restore-check
tar -xzf "$backup" -C /tmp/restore-check
ls -A /tmp/restore-check
cd ~/gbrain
docker compose exec -T postgres createdb -U gbrain restore_check < /dev/null
docker compose exec -T postgres pg_restore -U gbrain -d restore_check < /tmp/restore-check/gbrain.dump
docker compose exec -T postgres psql -U gbrain -d restore_check -tAc 'select count(*) from access_tokens' < /dev/null
docker compose exec -T postgres dropdb -U gbrain restore_check < /dev/null
rm -rf /tmp/restore-check

Expect .gbrain gbrain gbrain.dump, then the number of keys made so far. Copy ~/backups off the VM now and then; otherwise the VM's disk holds the only copy.

On the VM, ~/bin/gbrain-backup backs up now and prints the archive's path. Each holds gbrain.dump (the whole database: memories, keys, OAuth clients), .gbrain/ (GBrain's configuration), and gbrain/.env (the database password and owner token). To copy them to your computer:

scp 'my-gbrain.exe.xyz:backups/gbrain-*.tar.gz' .

Restore#

On a new VM, first follow Set up by hand through "Install Bun and GBrain", then copy the archive over from your computer:

scp gbrain-20261030-033012.tar.gz my-gbrain.exe.xyz:

On the VM (or on the old one, to roll back), stop GBrain, put the settings back, start PostgreSQL, and load the dump over whatever is there:

backup=~/gbrain-20261030-033012.tar.gz
sudo systemctl stop gbrain 2>/dev/null || true
[ -d ~/.gbrain ] && mv ~/.gbrain ~/.gbrain.before-restore-$(date +%s)
rm -rf /tmp/restore && mkdir /tmp/restore && tar -xzf "$backup" -C /tmp/restore
mkdir -p ~/gbrain
install -m 600 /tmp/restore/gbrain/.env ~/gbrain/.env
cp /tmp/restore/gbrain/compose.yaml ~/gbrain/
cp -a /tmp/restore/.gbrain ~/
sudo systemctl enable --now docker.service
cd ~/gbrain && docker compose up -d --wait
docker compose exec -T postgres pg_restore -U gbrain -d gbrain --clean --if-exists < /tmp/restore/gbrain.dump
rm -rf /tmp/restore

On a new VM, continue with Run the server and the backup timer; on the old one, sudo systemctl start gbrain. Then check it. Agents keep their keys, since those are in the database; on a VM with another name, point them at its URL and make them a VM token for it.

On the VM. GBrain won't upgrade under a running server it didn't start, so stop it first. The two variables keep the upgrade from installing GBrain's own background services or re-embedding anything:

backup=$(~/bin/gbrain-backup)
sudo systemctl stop gbrain
GBRAIN_NO_AUTOPILOT_INSTALL=1 GBRAIN_NO_REEMBED=1 gbrain upgrade --no-autopilot-install
sudo systemctl start gbrain
gbrain --version

It applies database migrations too. If it says the new release needs a newer Bun, run bun upgrade and the upgrade again. Read the changelog first if you're far behind.

• PostgreSQL: cd ~/gbrain && docker compose pull && docker compose up -d --wait updates within 16. A new major version needs a dump and restore.
• Ubuntu: sudo apt-get update && sudo apt-get upgrade -y.

On the VM, GBrain's and PostgreSQL's logs:

journalctl -u gbrain -n 100 --no-pager
systemctl status gbrain --no-pager
cd ~/gbrain && docker compose logs --tail 50 postgres

401 invalid or missing authentication, or an exe.dev login page. The VM token didn't reach exe.dev: check the header name (X-Exedev-Authorization), the Bearer before it, and that the token is for this VM and unexpired.

401 Missing Authorization header or Invalid token. exe.dev let the request in and GBrain refused it. The Authorization: Bearer gbrain_… header is missing, or the key was revoked (gbrain auth list).

502 Bad Gateway. Nothing answers on port 8000: the service is stopped or failed at start (see its log), often because PostgreSQL isn't up. curl -s localhost:8000/health on the VM tells you which.

OpenClaw says SSE error: Non-200 status code (405). Add --transport streamable-http; GBrain doesn't serve the older SSE transport.

gbrain commands fail with pglite_busy. The brain is on PGLite, not PostgreSQL: ~/.gbrain/config.json should say "engine": "postgres". Rerun Create the brain with --force.

Agents never use the brain. Check claude mcp list (or hermes mcp test gbrain, openclaw mcp probe) shows it connected, then add the instruction from Try it. In Claude Code, /mcp lists its tools.