--- title: "Self-host GBrain, shared memory for your agents" description: "Run GBrain on an exe.dev VM: one private MCP memory server that OpenClaw, Hermes, Claude Code and Codex share, with a key per agent and nightly backups." url: https://exe-staging.dev/deploy/gbrain category: "AI agents" updated: 2026-10-30 --- # Self-host GBrain, shared memory for your agents One memory for every agent you run, behind two locks. - **Software:** GBrain (https://github.com/garrytan/gbrain) - **Source:** https://github.com/garrytan/gbrain - **License:** MIT - **Time:** 10 minutes - **Example VM name:** `my-gbrain` (yours will differ; on the VM, `hostname` prints it) - **Machine-readable:** https://exe-staging.dev/deploy/gbrain/manifest.json ## What you get - GBrain's MCP server at `https://my-gbrain.exe.xyz/mcp` on PostgreSQL, as `gbrain.service`, restarted on failure and after a reboot. - Two locks on every request: exe.dev lets in only your login or a VM token, then GBrain checks a key that belongs to one agent. - A read-write GBrain key for each agent you named, revocable one at a time. - The admin dashboard at `/admin`, and an owner token kept in `~/gbrain/.env`. - Nightly backups of the database and settings in `~/backups`, with a restore tested. Running on the VM: - **GBrain**: `gbrain serve --http` on Bun, as `gbrain.service`: MCP, OAuth and the admin dashboard, port 8000, data in `~/.gbrain` - **PostgreSQL 16 with pgvector**: pgvector/pgvector:pg16 in Docker Compose, on 127.0.0.1 only, data in `~/gbrain/postgres` - **Nightly backup**: pg_dump plus settings, a systemd timer; keeps two weeks, data in `~/backups` How it is reached: - https://my-gbrain.exe.xyz/mcp (private): the MCP endpoint; agents send an exe.dev VM token and their own GBrain key - https://my-gbrain.exe.xyz/admin (private): GBrain's dashboard, behind your exe.dev login and GBrain's owner token ## Deploy with Shelley Open https://exe-staging.dev/new?prompt=AGENTS%3D%3Cfill-this-in%3E%0A%0ASet%20up%20GBrain%20on%20this%20VM%20by%20following%20the%20exe.dev%20recipe%20at%20https%3A%2F%2Fexe-staging.dev%2Fdeploy%2Fgbrain.md%20from%20top%20to%20bottom.%0A%0AThe%20values%20at%20the%20top%20of%20this%20message%20are%20mine%3A%0A-%20AGENTS%3A%20the%20agents%20that%20will%20share%20the%20brain%2C%20as%20short%20names%20such%20as%20%60laptop-claude%2C%20laptop-codex%2C%20openclaw%2C%20hermes%60%3B%20Shelley%20makes%20a%20GBrain%20key%20for%20each%0AAsk%20me%20for%20any%20that%20still%20say%20%3Cfill-this-in%3E%20before%20you%20need%20them.%0A%0AThe%20recipe%27s%20example%20VM%20name%20is%20my-gbrain.%20This%20VM%27s%20name%20is%20the%20output%20of%20%60hostname%60%3A%20use%20it%20wherever%20the%20recipe%20writes%20my-gbrain.%20Skip%20the%20step%20that%20creates%20the%20VM%3B%20you%20are%20on%20it.%0A%0AYou%20are%20done%20when%20all%20of%20these%20are%20true.%20Check%20each%20one%20yourself%3A%0A-%20GBrain%27s%20MCP%20server%20at%20%60https%3A%2F%2Fmy-gbrain.exe.xyz%2Fmcp%60%20on%20PostgreSQL%2C%20as%20%60gbrain.service%60%2C%20restarted%20on%20failure%20and%20after%20a%20reboot.%0A-%20Two%20locks%20on%20every%20request%3A%20exe.dev%20lets%20in%20only%20your%20login%20or%20a%20VM%20token%2C%20then%20GBrain%20checks%20a%20key%20that%20belongs%20to%20one%20agent.%0A-%20A%20read-write%20GBrain%20key%20for%20each%20agent%20you%20named%2C%20revocable%20one%20at%20a%20time.%0A-%20The%20admin%20dashboard%20at%20%60%2Fadmin%60%2C%20and%20an%20owner%20token%20kept%20in%20%60~%2Fgbrain%2F.env%60.%0A-%20Nightly%20backups%20of%20the%20database%20and%20settings%20in%20%60~%2Fbackups%60%2C%20with%20a%20restore%20tested.%0A%0ARead%20the%20whole%20recipe%2C%20closed%20details%20included%2C%20and%20follow%20%22Set%20up%20by%0Ahand%22%20in%20order%2C%20skipping%20VM%20creation%3B%20the%20walkthrough%20above%20it%20is%20for%0Athe%20owner.%20Ask%20for%20AGENTS%20if%20it%20still%20says%20%3Cfill-this-in%3E.%20Make%20one%20key%0Aper%20agent%20with%20%60gbrain%20auth%20create%20%3Cname%3E%20--scopes%20read%2Cwrite%60%2C%20using%0Ashort%20lowercase%20names.%20Never%20make%20the%20VM%20public%20or%20bind%20Postgres%20beyond%0A127.0.0.1.%20On%20an%20existing%20VM%2C%20ask%20before%20replacing%20anything%20on%20port%208000%0Aor%205432.%20Don%27t%20reboot.%20Test%20the%20backup%20in%20a%20scratch%20directory%20only%3B%20never%0Arestore%20over%20the%20live%20database.%20The%20VM%20can%27t%20reach%20its%20own%0Ahttps%3A%2F%2F%3Cvm%3E.exe.xyz%2C%20so%20checks%20use%20localhost.%0AFinish%20with%20the%20MCP%20URL%2C%20each%20agent%27s%20key%2C%20the%20owner%20token%20from%0A%60~%2Fgbrain%2F.env%60%20for%20%2Fadmin%2C%20and%20the%20%60ssh-key%20generate-api-key%60%20command%0Afor%20the%20owner%20to%20run%20on%20their%20computer%2C%20then%20point%20them%20to%20%22Connect%0Ayour%20agents%22.%20This%20conversation%20is%20private%20to%20the%20owner.%0A%0AFinish%20with%20the%20URLs%20I%20should%20open%20and%20these%20commands%2C%20which%20only%20I%20can%20run%2C%20from%20my%20own%20computer%20%28with%20this%20VM%27s%20name%20in%20them%29%3A%0A%20%20ssh%20exe.dev%20ssh-key%20generate-api-key%20--vm%3Dmy-gbrain%20--label%3Dgbrain-agents%20--exp%3D90d%0A to create a VM whose agent, Shelley, follows this recipe. From a terminal: ```sh curl -fsSL https://exe-staging.dev/deploy/gbrain/prompt.txt | ssh exe.dev new --prompt=/dev/stdin ``` Then, on your own computer: ```sh ssh exe.dev ssh-key generate-api-key --vm=my-gbrain --label=gbrain-agents --exp=90d ``` Or follow the steps below by hand. [GBrain](https://github.com/garrytan/gbrain) is a memory for AI agents: they save facts, people, decisions and notes into it and search it before they answer. On one computer, each agent keeps its own memory. Served over MCP, one brain is shared: tell Claude Code something on your laptop, and Codex, OpenClaw, and Hermes know it too. That needs a server that's always on, at an HTTPS address, and not open to the world. An exe.dev VM is all three. GBrain runs there on PostgreSQL, and every request passes two locks: exe.dev's proxy lets in only you and holders of a VM token, then GBrain checks the agent's own key. Each agent gets its own key, so you can see who wrote what and cut one off without touching the rest. ## Connect your agents Each agent sends two headers: - `X-Exedev-Authorization: Bearer exe1.…`, a [VM token](/docs/https-tokens-for-vms) that gets it through exe.dev's proxy, which removes it before GBrain sees the request. - `Authorization: Bearer gbrain_…`, the agent's GBrain key. Make the VM token on your computer (`--exp` sets when it expires; one token can serve all your agents, or make one per machine): ```bash ssh exe.dev ssh-key generate-api-key --vm=my-gbrain --label=gbrain-agents --exp=90d ``` Shelley made a GBrain key for each agent you named. To make another, on the VM: ```bash gbrain auth create laptop-claude --scopes read,write ``` It prints the key once. Below, replace `exe1.paste-yours-here` and `gbrain_paste-yours-here` with yours. **Claude Code**, on your computer or a VM like the one in [Claude Code on exe.dev](/deploy/claude-code) (saves both in `~/.claude.json`): ```bash claude mcp add --transport http --scope user gbrain https://my-gbrain.exe.xyz/mcp \ --header "X-Exedev-Authorization: Bearer exe1.paste-yours-here" \ --header "Authorization: Bearer gbrain_paste-yours-here" claude mcp list ``` Expect `gbrain: https://my-gbrain.exe.xyz/mcp (HTTP) - ✔ Connected`. **Codex**, on your computer or a [Codex VM](/deploy/codex), in `~/.codex/config.toml`: ```toml [mcp_servers.gbrain] url = "https://my-gbrain.exe.xyz/mcp" http_headers = { "X-Exedev-Authorization" = "Bearer exe1.paste-yours-here", "Authorization" = "Bearer gbrain_paste-yours-here" } ``` **OpenClaw**, on its VM (from [Self-host OpenClaw](/deploy/openclaw)). It checks the connection before saving: ```bash openclaw mcp add gbrain --url https://my-gbrain.exe.xyz/mcp --transport streamable-http \ --header "X-Exedev-Authorization=Bearer exe1.paste-yours-here" \ --header "Authorization=Bearer gbrain_paste-yours-here" openclaw gateway restart ``` **Hermes**, on its VM (from [Self-host Hermes Agent](/deploy/hermes-agent)). The headers name variables that Hermes keeps in `~/.hermes/.env`: ```bash hermes config set mcp_servers.gbrain.url https://my-gbrain.exe.xyz/mcp hermes config set mcp_servers.gbrain.headers.X-Exedev-Authorization 'Bearer ${EXE_GBRAIN_TOKEN}' hermes config set mcp_servers.gbrain.headers.Authorization 'Bearer ${MCP_GBRAIN_API_KEY}' hermes config set EXE_GBRAIN_TOKEN exe1.paste-yours-here hermes config set MCP_GBRAIN_API_KEY gbrain_paste-yours-here hermes mcp test gbrain ``` Expect a list of GBrain's tools. Restart the gateway (`systemctl --user restart hermes-gateway`) so scheduled jobs and chat apps get them too. **Other clients:** any MCP client that speaks Streamable HTTP and can send headers works the same way. > [!TIP] > For agents on your other exe.dev VMs, a > [VM-to-VM integration](/docs/integrations-vm-to-vm) can add both locks at > exe.dev's edge, so neither token is stored on the agent's VM. On your > computer, for an agent on `my-hermes-agent`: > `ssh exe.dev integrations add http-proxy --name gbrain-hermes --target https://my-gbrain.exe.xyz/ --peer --bearer gbrain_paste-yours-here --attach vm:my-hermes-agent`. > Then the agent's URL is `https://gbrain-hermes.int.exe.xyz/mcp`, with no > headers. ## Try it Tell Claude Code: > Remember with gbrain: the team offsite is in Lisbon on November 20. Then ask Codex, OpenClaw, or Hermes: > What do you know about the team offsite? They find it in the brain, with where it came from. Hermes can add to it ("the hotel is the Memmo Alfama"), and the others see that next. Agents use memory more when they're told to. Add a line like this to `CLAUDE.md`, `AGENTS.md`, or Hermes's `SOUL.md`: > Before answering, search gbrain for what you already know. When I tell > you a lasting fact or decision, save it to gbrain with where it came > from. ## Manage access On the VM, list the keys, with when each was last used, and revoke one: ```bash gbrain auth list gbrain auth revoke laptop-claude ``` A revoked key gets `401 Invalid token` at once. `--scopes read` makes a key that can search but not save. On your computer, `ssh exe.dev ssh-key list` shows VM tokens, and `ssh exe.dev ssh-key remove` takes one away. **The dashboard** is at `https://my-gbrain.exe.xyz/admin`: open it signed in to exe.dev, then paste the owner token, which is in `~/gbrain/.env` on the VM: ```bash grep GBRAIN_ADMIN_BOOTSTRAP_TOKEN ~/gbrain/.env ``` It shows live requests, the agents and their keys, and makes and revokes keys. Keep the owner token to yourself; agents never need it. ## Cloud agents claude.ai, ChatGPT, and agents that run in their makers' clouds can't send an exe.dev token, so they can only reach a public VM. GBrain then is the only lock. It's a real one: `/mcp` refuses requests without a key or OAuth token, and every OAuth connection waits for you to approve it in the dashboard. To open it, on your computer: ```bash ssh exe.dev share set-public my-gbrain ``` Then follow GBrain's guide for the app, such as [ChatGPT](https://github.com/garrytan/gbrain/blob/master/docs/mcp/CHATGPT.md), with `https://my-gbrain.exe.xyz/mcp` as the URL. Agents with keys keep working, and can drop the exe.dev header. > [!WARNING] > Public means the dashboard's sign-in page and OAuth endpoints face the > internet. Keep the owner token secret, approve only connections you > just started, and go back with `ssh exe.dev share set-private my-gbrain` > when you're done. ## The nuts and bolts Happy with what Shelley set up? Stop here. Below are the steps it followed, and maintenance for later.
Set up by hand ### Create the VM On your computer (pick another name if `my-gbrain` is taken): ```bash 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](https://bun.sh). Install it, then GBrain's stable release: ```bash 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: ```bash mkdir -p ~/gbrain && cd ~/gbrain if [ ! -e .env ]; then install -m 600 /dev/null .env cat >> .env < 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: ```bash . ~/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://.exe.xyz/` to port 8000, so GBrain listens there, on all interfaces, with that address as its public URL (for OAuth and dashboard links): ```bash sudo tee /etc/systemd/system/gbrain.service >/dev/null < ~/bin/gbrain-backup <<'EOF' #!/bin/bash # Back up gbrain to ~/backups/gbrain-
Back up and restore 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: ```bash scp 'my-gbrain.exe.xyz:backups/gbrain-*.tar.gz' . ``` ### Restore On a new VM, first follow [Set up by hand](#create-the-vm) through "Install Bun and GBrain", then copy the archive over from your computer: ```bash 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: ```bash 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](#run-the-server) and the backup timer; on the old one, `sudo systemctl start gbrain`. Then [check it](#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.
Update GBrain, Bun, and PostgreSQL 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: ```bash 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](https://github.com/garrytan/gbrain/blob/master/CHANGELOG.md) 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`.
Something not working? On the VM, GBrain's and PostgreSQL's logs: ```bash 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](#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](#try-it). In Claude Code, `/mcp` lists its tools.
## Frequently asked questions ### What does it cost to self-host GBrain? GBrain is MIT-licensed, so just your [VM plan](https://exe.dev/pricing). Memory works without any model key: agents save facts and GBrain finds them by keyword. Optional features such as semantic search and automatic fact extraction call a model provider and bill there. ### Who can reach my brain? Only callers that pass both locks: exe.dev's proxy admits you (signed in) and anything holding a VM token for this VM, and GBrain then wants a key of its own. A leaked GBrain key is useless without a VM token, and the reverse. Revoke either on its own. ### What about `gbrain mcp expose`? It gives a brain on your own computer an HTTPS address through a tunnel and keeps the server running. A VM already has an HTTPS address with a login in front, so this page runs the same `gbrain serve --http` that `expose` would, as a systemd service, with `--public-url https://my-gbrain.exe.xyz`. ### Why PostgreSQL instead of the default PGLite? PGLite lets one process open the brain at a time. With the server running, `gbrain` commands on the VM (making keys, searching, importing notes) are refused. PostgreSQL takes them all at once, and `pg_dump` backs it up while it runs. ### Can claude.ai or ChatGPT use it? Only if you make the VM public, since they connect from their makers' servers. GBrain then is the only lock: OAuth with your approval for each app, and its keys. See [Cloud agents](#cloud-agents). ### Does every agent see every memory? By default, yes: that's the point of a shared brain. GBrain can split memories into sources and limit a key to some of them; see its [administration guide](https://github.com/garrytan/gbrain/blob/master/docs/mcp/ADMIN.md). ## Related - [Host OpenClaw](https://exe-staging.dev/deploy/openclaw.md): An AI sidekick with its own computer. Your laptop can take a nap. - [Self-host Hermes Agent](https://exe-staging.dev/deploy/hermes-agent.md): An agent that remembers you, on a computer that never sleeps. - [Run Claude Code on a remote server](https://exe-staging.dev/deploy/claude-code.md): A computer for Claude. A breather for your laptop. - [Run Codex on a remote server](https://exe-staging.dev/deploy/codex.md): A computer for Codex. An early night for your laptop. - [Host a remote MCP server](https://exe-staging.dev/deploy/mcp-server.md): Tools for all your agents, on a computer of their own. Private until you say. - [Run the Pi coding agent on a remote server](https://exe-staging.dev/deploy/pi.md): An agent that doesn't ask first, on a computer that can take it.