docs(security): Docker network isolation for co-located self-hosted Postgres (#3270)

OAuth/source scoping only guards the serve --http path; a container
sharing Docker's default bridge with the brain's Postgres can open a
direct DB session without a token. Adds a 'Co-located Docker workloads'
subsection to docs/mcp/DEPLOY.md with the operator checklist, a
trust-boundary paragraph in SECURITY.md, and an ops note + cross-link
in the company-brain tutorial.

Fixes #3270

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

SECURITY.md

@@ -135,6 +135,18 @@ the PGLite schema. Local agents continue to use stdio (`gbrain serve`).
 Running `--http` against a PGLite-backed install fails fast with a clear
 error message at startup.
 
+### Docker network isolation (self-hosted Postgres)
+
+OAuth and source scoping enforce isolation on the `serve --http` path only.
+Raw Postgres reachability bypasses both: a container that shares Docker's
+default `bridge` network with the brain's Postgres can open a direct DB
+session without any token and read every source. Put the brain's Postgres on
+a user-defined Docker network with nothing untrusted on it, publish its port
+loopback-only (if at all), and never put `DATABASE_URL` or a Postgres
+password in untrusted agent containers — those should reach the brain
+exclusively via OAuth against `serve --http`. Full operator checklist:
+[docs/mcp/DEPLOY.md — Co-located Docker workloads](docs/mcp/DEPLOY.md#co-located-docker-workloads-self-hosted-postgres).
+
 ### CORS
 
 Default-deny: no `Access-Control-Allow-Origin` header is sent unless an

docs/mcp/DEPLOY.md

@@ -258,6 +258,43 @@ the user owns the machine.
 See [ALTERNATIVES.md](ALTERNATIVES.md) for a comparison of ngrok, Tailscale
 Funnel, and cloud hosts (Fly.io, Railway).
 
+### Co-located Docker workloads (self-hosted Postgres)
+
+OAuth scopes and source scoping guard the `gbrain serve --http` path. They do
+NOT guard raw Postgres. If the brain's Postgres runs as a container on the same
+Docker host as other workloads (agent runtimes, n8n, staging fixtures), any
+container sharing Docker's default `bridge` network can open a direct DB
+session — no OAuth token required — and read every source. That silently
+recreates a privileged path underneath the isolation you configured at the MCP
+layer.
+
+Network-zone the host so untrusted containers can never reach Postgres:
+
+```
+Docker host
+├── gbrain-net          ← ONLY the brain's Postgres (+ gbrain serve, if containerized)
+├── agent-<id>-net      ← each untrusted agent runtime, isolated
+└── default bridge      ← no secret-bearing databases
+```
+
+Operator checklist:
+
+```text
+[ ] Postgres is on a user-defined Docker network, not the default bridge
+    (or nothing else runs on that bridge)
+[ ] If Postgres publishes a host port at all, it binds loopback only
+    (`-p 127.0.0.1:5432:5432`, never `0.0.0.0`)
+[ ] Untrusted agent containers have no DATABASE_URL or Postgres password
+[ ] Untrusted agents reach the brain via OAuth/Bearer against serve --http only
+    (host loopback via host.docker.internal / host gateway — never gbrain-net)
+[ ] OAuth clients are least-privilege: scoped --source / --federated-read,
+    pre-minted short-lived tokens preferred over long-lived client secrets
+[ ] Isolation verified: a team-scoped client cannot read internal-only sources
+```
+
+Optional defense-in-depth: a dedicated Postgres role (or RLS) limited to the
+allowed `source_id`s, so even a leaked connection string can't read everything.
+
 ## Troubleshooting
 
 **"missing_auth" error**

docs/tutorials/company-brain.md

@@ -484,6 +484,10 @@ Returns a per-source dashboard: when each source last synced, how many pages, ho
 
 The admin dashboard at `https://brain.acme-co.com/admin` shows live request volume, registered OAuth clients, recent activity, and brain stats. Use the admin bootstrap token from Part 4 to log in the first time, then register additional admin users from inside the dashboard.
 
+### If agents run as containers on the same Docker host
+
+OAuth source scoping only guards the HTTP MCP path. If the brain's Postgres and your teammates' agent runtimes are containers on the same Docker host, make sure the agents can't reach Postgres directly over Docker's default bridge network — a direct DB session skips OAuth entirely. Put Postgres on its own user-defined network, publish it loopback-only if at all, and never hand agent containers a `DATABASE_URL`. The copy-paste operator checklist lives in [docs/mcp/DEPLOY.md — Co-located Docker workloads](../mcp/DEPLOY.md#co-located-docker-workloads-self-hosted-postgres).
+
 ---
 
 ## Part 13: Cost and speed expectations

llms-full.txt

@@ -3905,6 +3905,43 @@ the user owns the machine.
 See [ALTERNATIVES.md](ALTERNATIVES.md) for a comparison of ngrok, Tailscale
 Funnel, and cloud hosts (Fly.io, Railway).
 
+### Co-located Docker workloads (self-hosted Postgres)
+
+OAuth scopes and source scoping guard the `gbrain serve --http` path. They do
+NOT guard raw Postgres. If the brain's Postgres runs as a container on the same
+Docker host as other workloads (agent runtimes, n8n, staging fixtures), any
+container sharing Docker's default `bridge` network can open a direct DB
+session — no OAuth token required — and read every source. That silently
+recreates a privileged path underneath the isolation you configured at the MCP
+layer.
+
+Network-zone the host so untrusted containers can never reach Postgres:
+
+```
+Docker host
+├── gbrain-net          ← ONLY the brain's Postgres (+ gbrain serve, if containerized)
+├── agent-<id>-net      ← each untrusted agent runtime, isolated
+└── default bridge      ← no secret-bearing databases
+```
+
+Operator checklist:
+
+```text
+[ ] Postgres is on a user-defined Docker network, not the default bridge
+    (or nothing else runs on that bridge)
+[ ] If Postgres publishes a host port at all, it binds loopback only
+    (`-p 127.0.0.1:5432:5432`, never `0.0.0.0`)
+[ ] Untrusted agent containers have no DATABASE_URL or Postgres password
+[ ] Untrusted agents reach the brain via OAuth/Bearer against serve --http only
+    (host loopback via host.docker.internal / host gateway — never gbrain-net)
+[ ] OAuth clients are least-privilege: scoped --source / --federated-read,
+    pre-minted short-lived tokens preferred over long-lived client secrets
+[ ] Isolation verified: a team-scoped client cannot read internal-only sources
+```
+
+Optional defense-in-depth: a dedicated Postgres role (or RLS) limited to the
+allowed `source_id`s, so even a leaked connection string can't read everything.
+
 ## Troubleshooting
 
 **"missing_auth" error**