Self-hosting the server

• Somewhere to run Docker. A small VPS is plenty.
• A brain repository. Start from the template, keep it private.
• A Claude credential. An API key, or a token from a Claude subscription you already pay for. No API billing either way.
• A domain, if you want this reachable from anywhere but your desk.

Two variables are required. That is the whole list:

POSTGRES_PASSWORD=<any long random string>
ALLOWED_HOSTS=brain.example.com

ALLOWED_HOSTS takes no scheme and no slashes. Comma separate it if you have more than one name. It stays in the environment rather than in the settings UI on purpose. Getting it wrong returns 400 on every request, including the page that would let you fix it.

Four more get created for you on first boot and written to the state volume: SECRET_KEY, FIELD_ENCRYPTION_KEY, MCP_LOOPBACK_SECRET, and the admin URL path. Setting any of them yourself still wins.

Worth setting once you are past first boot:

Five containers: web, mcp, worker, Postgres, Redis. Four named volumes, so a redeploy never wipes them.

docker compose up -d --build

A cold first build takes 121 to 126 seconds on a laptop, and the setup page answers about 23 seconds after up. A small VPS will be slower. The build is the slow part, and it happens once per version.

Coolify clones the repo and builds the image itself. There is no published image yet, so it needs a repository it can reach.

Do not look for a Docker Compose option in the resource picker. The one that is there, Docker Compose Empty, is for pasting a compose file with no git behind it, and this stack builds from source. The route is:

1. New Resource, then Public Repository under Git Based. Private repos have their own options there, one for a GitHub App and one for a deploy key.
2. Paste the repository URL and press Check repository. Nothing else appears until you do.
3. Set Build Pack to Docker Compose. The branch fills itself in and goes read only.
4. Set the compose file path. The field suggests /docker-compose.yaml and this repo ships /docker-compose.yml, so type it.

Coolify then reads the compose file and gives you a Generate Domain button for every service: web, mcp and worker. Only web gets one. It is the only service the compose file publishes, and the other two are reachable on the internal network. Coolify terminates TLS itself.

Add the two environment variables from above, then deploy. A deploy with the image layers already cached finished in 40 seconds.

For the health check use /healthz, which answers as soon as the app is up. Do not use /readyz. It returns 503 until a valid brain is cloned, so a blank instance would never come up healthy and you would never reach the wizard.

Then open your domain. It redirects to /setup/, and the six steps are walked through in Getting started.

This is the one most deploys get wrong, and the failure is nasty rather than cosmetic.

Coolify fronts the app with Traefik, and plenty of deploys put Cloudflare on top of that. In that shape, the address the app sees is the proxy, not the caller. Every per IP control then treats the whole internet as one address. The admin login lockout is per IP, so an attacker's failed attempts trip the sentinel on that shared address and lock you out of your own admin, while they keep going from another edge node.

Set both, never one:

TRUSTED_PROXY_IP_HEADER=CF-Connecting-IP
TRUSTED_PROXY_IPS=10.0.0.0/8

TRUSTED_PROXY_IPS is the address your proxy connects from, which is the hop next to this app. Behind Coolify that is the Traefik container on the Docker network, a private address. It is not Cloudflare's published ranges. Do not guess it. The health page prints the address the app actually observes, and which of the three states you are in.

The header is trusted only when the peer is in that list, so a caller reaching your origin directly cannot forge it. Setting one without the other refuses to boot in production, because a half configuration looks exactly like a working one while every per IP control sits inert.

ADMIN_IP_ALLOWLIST compares against the resolved address, so configure this section first. Otherwise you are allowlisting your proxy, and the first request 404s you out of your own server.

The ops UI can approve feeds and read every private note. It is staff only, but put a network boundary in front of it as well. It lives at the path in ADMIN_PANEL_URL_PATH, which defaults to /ops/.

Pick one:

• Tailscale on the box, with ADMIN_IP_ALLOWLIST set to your tailnet range. The middleware returns 404 to everyone else.
• Cloudflare Access covering the ops path, /setup/ and /login/.

The open internet should reach only /, /api/, /mcp, /webhooks/github, and the health endpoints. Putting Access in front of those breaks your agents and quietly kills the webhook.

The dashboard warns you when the ops UI is unrestricted and reachable from a non local address.

In your brain repo: Settings, Webhooks. Point it at https://your-domain/webhooks/github, content type JSON, secret matching GITHUB_WEBHOOK_SECRET, push events only.

Two things, nightly, on the host:

docker exec <postgres> pg_dump -U brain brain \
  | gzip > /backups/brain-$(date +%F).sql.gz

docker run --rm -v <project>_brain-state:/s -v /backups:/b alpine \
  tar czf /b/brain-state-$(date +%F).tgz -C /s .

Work out what you need by asking what your repo can rebuild. Entities, sync runs and the per tier snapshots all come back from a rebuild. Feeds, events, the token ledger and chat history do not. Nor does boot-secrets.json, which is why the state volume is on the list.

Do a restore drill into a scratch Postgres once. A backup you have never restored is a guess.

Pull the new version and rebuild. Migrations and collectstatic run in the web container on start, so there is no separate migrate step.

git pull
docker compose up -d --build

The volumes are named, so your database, your clone, your snapshots and your generated secrets all survive. Take the database and state backup first anyway.

One thing that does not update itself: your brain repo is a copy of the template made at a point in time. Updating the server does not touch it, and it is your repo, so nothing is going to reach in and migrate it.

The contract in CLAUDE.md carries a contract-version field, currently 1.0, so a later version can tell a stale contract from a current one. Today nothing checks it for you. What the server does check on every boot is that the contract paths are all present, and it refuses to serve a clone that is missing any of them.