Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
44.5 KB
Raw Blame

Deploy GBrain Remote MCP Server

gbrain serve --http ships full OAuth 2.1 (client credentials, auth code + PKCE, refresh rotation, optional DCR), an embedded React admin dashboard at /admin, scoped operations, and a live SSE activity feed. Legacy bearer tokens also work: verifyAccessToken falls back to the access_tokens table; tokens with no scopes grant carry read+write+admin, while tokens minted with gbrain auth create --scopes … (or by gbrain bootstrap harness) are honored at exactly their granted scopes. Both the legacy fallback and the OAuth tables work on PGLite and Postgres (both engine schemas carry access_tokens). See SECURITY.md for env vars and tunable defaults.

Access your brain from any device, any AI client. GBrain ships two transports: gbrain serve (stdio) for local agents, and gbrain serve --http for remote clients over OAuth 2.1. The recommended way to publish serve --http from your own computer is gbrain mcp expose, which puts it on your Tailscale tailnet with HTTPS and keeps it running as a user service — see Use your brain from anywhere over MCP.

Say to your agent: "use my brain over mcp" — "put my brain on tailscale" — the remote-mcp skill runs gbrain mcp expose for you after you confirm the printed plan.

For owner login, client registration, setup instructions, permission edits, token invalidation, revocation, or deletion, start with MCP administration. For the connecting harness, use hosted setup. The owner bootstrap credential is separate from OAuth admin scope; only the former authenticates the owner dashboard and client-management API.

Authorization-code connections require owner approval in the admin dashboard. Existing sessions are preserved. Before upgrading an installation with queued work, follow the authorization and worker upgrade guide for the coordinated cutover, consent recovery, and Bun requirements.

The owner-approval step. /authorize never returns an authorization code on its own. It records a pending request and redirects the browser to the admin dashboard (/admin/?oauth_request=…), where the brain owner signs in (bootstrap token or magic link), reviews the client name, redirect URI and requested scopes, and approves or denies. Only an approval mints the code, which is then delivered to the client's registered redirect URI; a denial returns error=access_denied. This applies to every authorization-code client, including clients that self-registered via DCR — self-registration alone never yields a token. Pending requests expire after ten minutes, do not survive a server restart, and are bounded: at most ten awaiting-decision requests per client and a fixed server-wide ceiling. Beyond either, /authorize sends the client back to its registered redirect URI with error=too_many_requests (and no code) until earlier requests are decided or expire; a 429 status on /authorize comes only from the MCP SDK's per-IP rate limit.

Say to the server-hosting harness: "Expose my existing brain over HTTPS, configure a protected owner credential, and help connect my native OAuth client. Use manual registration unless I request self-service registration. Preserve the OAuth request when issuing my owner login link."

Three Paths

Local stdio (zero setup)

gbrain serve --surface starter --advertise verbs   # what new registrations pin; a bare serve defaults to the full catalog

Works with Claude Code, Cursor, Windsurf, and any MCP client that supports stdio. On Claude Code, gbrain setup claude-code writes and verifies this registration for you (setup guide). No server, no tunnel, no token needed. Works on both PGLite and Postgres engines. --surface full serves every operation; --advertise verbs lists only the seven memory verbs and request_tools in tools/list, and request_tools returns any other tool's schema. A bare gbrain serve lists everything. For a client that cannot hold the full catalog, --surface verbs exposes exactly the seven-verb memory protocol (recall, remember, entity, synthesize, forget, context_pack, delta — MEMORY_VERBS v1) and --surface starter sits between (40 ops: the verbs plus the daily-driver set).

On a Postgres brain, gbrain serve --cli-socket (off by default; or gbrain config set serve.cli_socket true) also lets this serve answer the same user's CLI search, query, get and op-backed recall over a private Unix socket, so agents that shell out to the CLI skip a cold database connection per call (warm CLI socket).

--surface is the callable ceiling. To keep every operation callable while listing fewer tools to the agent, set mcp.advertised_surface:

gbrain config set mcp.advertised_surface verbs   # list the 7 verbs; everything else stays callable

Unset is the recommended default. In a held-out agent benchmark, listing only starter or verbs lowered task success by 8–10 points pooled across four frontier models, mostly on tasks that need an unlisted tool (agents rarely reached for request_tools), and saved no tokens. Narrow the list only for a client that cannot hold the full catalog.

tools/list then shows the advertised surface, and the initialize instructions tell the agent how many more tools are callable. On stdio, request_tools with tools: [names] returns their schemas and adds them to that session's list (the server sends tools/list_changed). On the OAuth HTTP server, a client that set its own surface (request_tools with surface, or gbrain auth rescope-client) has that surface listed in full, and a client an install default set up (gbrain auth clients shows full (set by install)) lists the memory verbs and request_tools whatever the server's --advertise or mcp.advertised_surface says; gbrain auth rescope-client <client_id> --surface full lists everything for it. Unset advertises the whole callable set.

Stdio source binding

Do not inherit GBRAIN_SOURCE=__all__ from a trusted CLI session into a stdio MCP server. It does not grant all-source access: the server keeps a fail-closed scope, so searches can return healthy empty results even when the trusted CLI finds pages. Startup stderr warns about this binding before the MCP handshake; it does not inspect or reveal private pages.

In the MCP host's server environment, set GBRAIN_SOURCE to the intended registered source id, or remove it to use normal source resolution and its configured federation rules. Inspect registered ids with gbrain sources list on the brain host, then restart the MCP server and check a known world-visible page in the intended source. Removing the variable is not unrestricted access: dotfiles and other source-resolution settings still apply. No memory writes or index repair are needed to correct this environment binding.

This differs from the per-call source_id: "__all__" argument, which searches only the caller's granted sources. MCP callers also exclude private pages by default; a private-only miss is not evidence of a broken index. For a concrete source binding that still misses a known visible page, retain the version, engine, schema pack, effective source/grants, and retrieval metadata for a sanitized reproduction rather than broadening permissions.

Tailscale (recommended): gbrain mcp expose

gbrain mcp expose            # tailnet-only HTTPS: your own devices
gbrain mcp expose --funnel   # public HTTPS on the same name: cloud agents (Grok Bot, Muse, ChatGPT, …)
gbrain mcp expose --status   # re-probe the receipt, service and health

One command on the brain host: installs Tailscale if needed (after a consent prompt), signs in, publishes gbrain serve --http on your MagicDNS name with Tailscale-terminated TLS, provisions the admin bootstrap token in a private file, installs a launchd / systemd user service so the server survives reboots, and prints the MCP URL (https://your-machine.your-tailnet.ts.net/mcp) plus separate owner-login, native OAuth, and machine-client next steps. Engine-free — it works while a PGLite brain's serve holds the write lock. Default reach is your tailnet only; --funnel is the explicit opt-in for agents that run in a vendor's cloud. Steps, flags, --remove, and the troubleshooting table: remote MCP guide.

Your AI client
  → https://your-machine.your-tailnet.ts.net/mcp   (Tailscale terminates TLS)
  → gbrain serve --http on 127.0.0.1:3131           (user service)
  → Postgres or PGLite

Then choose the intended client's connection method. Native OAuth/PKCE uses owner registration. For a private machine handoff, provision through the running server (the only way on PGLite while serve is live):

gbrain mcp grant agent-example --harness codex --profile memory-writer --source default \
  --url https://your-machine.your-tailnet.ts.net/mcp \
  --admin-token-file ~/.gbrain/serve/admin-token --credentials-out /private/agent-example.json

Other tunnels and cloud hosts

Any HTTPS front works: ngrok, Cloudflare Tunnel, or a cloud host (Fly.io, Railway) for a brain that must answer while your laptop is closed — ALTERNATIVES.md compares them. You run gbrain serve --http yourself and pass --public-url whenever the server is reachable at anything other than http://localhost:<port> so the OAuth issuer in discovery metadata matches what clients hit (RFC 8414 §3.3).

Remote over OAuth 2.1

ngrok http 3131 --url your-brain.ngrok.app

Keep the tunnel running in its own terminal, then start the brain server once:

gbrain serve --http --port 3131 --public-url https://your-brain.ngrok.app

Built-in HTTP transport with OAuth 2.1, scoped operations, an admin dashboard at /admin, and a live SSE activity feed. Zero external dependencies. This is the only auth shape that works with ChatGPT (OAuth 2.1 + PKCE is required by the ChatGPT MCP connector).

Supported clients:

  • ChatGPT — requires OAuth 2.1 + PKCE. Works natively with --http.
  • Claude Desktop / Cowork — OAuth 2.1 or legacy bearer tokens.
  • Perplexity — OAuth 2.1 client credentials grant.
  • Claude Code, Cursor, Windsurf — can use OAuth or legacy bearer.

See the OAuth 2.1 setup section below.

Remote with legacy bearer tokens (simplest)

Your AI client (Claude Desktop, Perplexity, etc.)
  → HTTPS front (Tailscale name, ngrok domain, or cloud host)
  → gbrain serve --http  (MCP bearer access; separate owner administration)
  → Postgres or PGLite

This requires:

  1. A machine running gbrain serve --http (works on both PGLite and Postgres brains)
  2. An HTTPS front (Tailscale via gbrain mcp expose, ngrok, or a cloud host)
  3. A bearer token created via gbrain auth create <name>

Bearer tokens created without a scopes grant carry read+write+admin on the HTTP server; gbrain auth create --scopes read,write mints narrowed tokens.

OAuth 2.1 Setup

1. Start the HTTP server

If gbrain mcp expose already started the service, keep using it and its configured MCP URL. Continue to owner login or client registration; do not start another server or repeat the publishing step.

For a manually managed server, choose the HTTPS front and --public-url from step 3 before starting it. This local-only example starts one foreground process:

gbrain serve --http --port 3131

On first start in an interactive terminal, the server prints an admin bootstrap token to stderr:

Admin bootstrap token: 3a1f9c...
Open http://localhost:3131/admin and paste it to log in.

On a non-TTY start (systemd, Docker, any piped or captured logs) the generated token is hidden so it never lands in log storage. For headless deploys, set GBRAIN_ADMIN_BOOTSTRAP_TOKEN through the service's protected environment before starting. --print-admin-token can force printing at that process's startup on a trusted terminal; starting a separate process with this flag does not recover the existing server's token. If the existing process's generated credential was lost, restart that service through the normal maintenance path with a configured credential. See owner credential recovery.

Save this token. Open http://localhost:3131/admin and paste it to access the dashboard. The dashboard shows live activity, registered clients, request logs, and per-client config export.

mcp_request_log.params and the live SSE activity feed default to a redacted summary {redacted, kind, declared_keys, unknown_key_count, approx_bytes}. Declared param keys are kept (intersected against the operation's spec); unknown keys are counted but never named, and byte sizes round up to 1KB so size-probe attacks can't binary-search secret content. Operators on a personal laptop who want raw payloads back can pass gbrain serve --http --log-full-params (loud stderr warning fires at startup). Multi-tenant deployments should leave it on the redacted default.

Owner login links for AI agents

Say to the server-hosting or authorized administrator harness: "Give me the GBrain admin login link". The recommended command wraps the existing HTTP mint endpoint:

gbrain mcp admin login-link --url https://brain.example.com/mcp \
  --admin-token-file /absolute/private/admin-token --json

During OAuth connection, add --oauth-request REQUEST_ID from the pending browser URL. This preserves consent when the owner opens the login link in a fresh tab or browser. Expired/restarted requests require a new connection from the native client; its PKCE verifier stays in that client. Full commands and recovery instructions: MCP administration.

When an authenticated owner asks "Give me the GBrain admin login link", use the existing single-use login flow. A static /admin/ URL opens the login page; it does not authenticate the owner.

  1. Use the requesting owner's authorization and a private destination for the login link.
  2. Obtain the running server's bootstrap credential through the host's existing protected credential mechanism. GBRAIN_ADMIN_BOOTSTRAP_TOKEN is the supported deployment setting. Never expose its value in chat, logs, shell arguments, or a URL. If the credential is unavailable, report that specific setup blocker; do not claim the login-link capability is missing.
  3. Send POST /admin/api/issue-magic-link to the running server, with the bootstrap credential in the Authorization: Bearer header through that protected mechanism. An MCP client bearer token or client secret is not the server bootstrap credential.
  4. The response contains url and expires_in (300 seconds). The returned URL uses the server's configured --public-url; without it, the fallback is localhost. Ensure the deployment has an owner-reachable public URL rather than substituting a remembered tunnel address.
  5. Deliver the returned short-lived login link only to the requesting owner in private. In a shared channel, acknowledge private delivery without reproducing the link. Never put it into a public issue or commit.

Do not GET or fetch the generated login URL to verify it. That redeems the single-use nonce before the owner can use it. Check the base /admin/ page and non-secret response metadata separately. The link expires after five minutes, cannot be replayed, and is invalidated by a server restart. Successful redemption establishes the admin browser session and redirects to /admin/.

This logs the owner into the dashboard; it does not create, reveal, or rotate an MCP client credential. Register the intended OAuth client separately on the Agents page, then use its setup instructions and explicit private download when needed. For unattended deployments, provision the bootstrap credential through the operator's protected configuration before starting the server; generated secrets are deliberately hidden in captured logs.

2. Register OAuth clients

Register from the /admin dashboard's Agents page. Choose machine credentials, public PKCE (none), or confidential PKCE (POST/Basic) according to the intended harness. Native OAuth requires its actual redirect URI. Review permissions and connection metadata before registration, then use the setup instructions for that client. Public clients have no secret; confidential delivery is explicit and recoverable from the protected host journal while the live secret still matches.

For a running server, use the owner HTTP CLI:

gbrain mcp admin register agent-example \
  --redirect-uri https://client.example.com/oauth/callback \
  --token-endpoint-auth-method none --scopes read,write --source default \
  --url https://brain.example.com/mcp \
  --admin-token-file /absolute/private/admin-token --dry-run --json

Review and repeat without --dry-run. Machine credentials use gbrain mcp grant … --credentials-out PRIVATE_FILE instead. See registration and setup for both flows. The legacy gbrain auth register-client command remains a local database-maintenance path; do not open an already running PGLite brain through it.

Source-scoped clients. Multi-source brains can scope a client's write authority to one source and its read scope to a curated set with the --source and --federated-read flags:

gbrain mcp grant dept-x-agent --harness generic --profile memory-writer \
  --source dept-x --federated-read dept-x,shared,parent-canon \
  --url https://brain.example.com/mcp \
  --admin-token-file /absolute/private/admin-token \
  --credentials-out /absolute/private/dept-x-agent.json --json

--source controls the write authority — put_page / add_link / etc only land in dept-x. --federated-read controls the read axis independently; queries return rows from any of the listed sources. New registrations that omit both flags use source default; omission does not create an unscoped super-client. A client with no recorded source is backfilled to source_id='default' on gbrain upgrade. Within a source, slug-level write fencing is also available: --bound-slug-prefixes p1/,p2/ rejects slug-mutating writes outside the listed prefixes (update later with gbrain auth rescope-client <id> --bound-slug-prefixes <p1,p2|none>).

Host-repo wrappers can register programmatically:

await oauthProvider.registerClientManual(
  'perplexity',
  ['client_credentials'],
  'read write',
  [],  // redirect_uris, empty for CC
);

Dynamic client registration (DCR)

For self-service client registration (Dynamic Client Registration, RFC 7591), start the server with --enable-dcr. DCR is off by default.

Say to your agent: "Start my brain's MCP server with self-service client registration — your agent runs gbrain serve --http --enable-dcr, and you approve each new connection in the admin UI."

A self-registered client goes through three gates:

  1. Scope ceiling at registration. Dynamic registration may request at most read write. A request naming admin, sources_admin, users_admin, or agent is rejected with HTTP 400 invalid_client_metadata (never silently narrowed), and the error text points at the operator path. Under --enable-dcr-insecure, a client_credentials registration is capped at read — a grant that skips owner approval never carries write. While DCR is enabled (either mode), OAuth discovery advertises the read write self-registration ceiling as scopes_supported (authorization-server and protected-resource metadata alike), so a client that registers with the advertised scopes succeeds; with DCR off, discovery lists every scope an operator-registered client may hold. agent is never advertised — it needs delegation bindings no OAuth request can carry.
  2. Owner approval on /authorize. Every authorization-code connection redirects to the admin dashboard, where you see the client, its redirect URI, and the requested scopes, and approve or deny. No code is minted until you approve. Consent never widens the registered scope. For a newly self-registered client you also choose the source it reads and writes (it registers on default); the choice is recorded in the grant audit (action: consent), and the first approval ends the choice, so later requests show the source read-only. A client_credentials client never gets this choice and stays on default.
  3. Per-request clamp. Issued codes and tokens are re-intersected with the client's current registered scope, so a later rescope-client takes effect on the next request.

To give a self-registered client more than read write, use the owner permission-edit path (or the admin dashboard's Agents page), then reconnect for fresh authorization. Alternatively, pre-register through gbrain mcp admin register with the intended scopes. The legacy gbrain auth rescope-client / register-client commands are local database-maintenance paths; do not open a live PGLite database through them. gbrain doctor warns about active clients that hold a privileged scope but look self-registered.

Native MCP clients register cleanly: redirect_uris may use an app custom scheme (RFC 8252, e.g. myapp://callback) or http:// loopback alongside https://; scopes the server doesn't know are filtered rather than fatal; and malformed registration metadata is rejected with HTTP 400 invalid_client_metadata (never a 500), so a client can correct and retry.

DCR requests may include an optional token_ttl_seconds field (integer, seconds) to request a per-client access-token lifetime. The server clamps the request into an admin-configured window — never rejects over it — persists the effective value as the client's TTL override, and echoes it back as token_ttl_seconds in the registration response. Subsequent /token responses for that client carry the matching expires_in. Clients that omit the field keep the server default (--token-ttl). The window defaults fail-closed: min 300 seconds, max bounded by your --token-ttl — a self-registering client cannot request a longer-lived token than the server default unless you explicitly widen the window:

gbrain config set oauth.dcr_ttl_min_seconds 600
gbrain config set oauth.dcr_ttl_max_seconds 86400

3. Expose the server

Tailscale (recommended). gbrain mcp expose does this whole section for you — Tailscale install/login, tailscale serve (or funnel), the admin token file, a user service, and the health checks — and keeps the server on its default loopback bind, because Tailscale terminates TLS on the tailnet and forwards to 127.0.0.1. The manual equivalent is the Tailnet / LAN-only shape below. Full walkthrough: remote MCP guide.

Choose this managed-service path before starting a manual server. If a server already answers at the intended HTTPS endpoint, use that deployment. Publishing an independently managed server with --no-service requires that server's own configured owner credential; an expose-created file does not change it.

ngrok (alternative). ngrok also connects to loopback on the same machine, so the default bind is right there too:

gbrain serve --http --port 3131 --public-url https://your-brain.ngrok.app

Bind explicitly only when the front is on another host. gbrain serve --http defaults to 127.0.0.1. To accept connections from a reverse proxy or tunnel agent running on a different machine (or a container), restart with --bind:

gbrain serve --http --port 3131 --bind 0.0.0.0 --public-url https://brain.example.com

When --public-url is set without --bind, a stderr WARN fires at startup so a real misconfiguration ("the tunnel is up but my agent gets ECONNREFUSED") is loud; in the Tailscale and same-machine-ngrok shapes the WARN is expected and harmless. Binding 0.0.0.0 without GBRAIN_HTTP_CORS_ORIGIN warns too: browser-based clients get no CORS header until you set the allowlist (see SECURITY.md — CORS).

--source-guard is a stdio-lane flag: with --http it prints a warning and is ignored. HTTP writes are fenced by each token's scopes instead, so operators migrating from stdio mint narrowed tokens (gbrain auth create <name> --scopes read) rather than relying on the guard.

For the ngrok alternative, start the tunnel after the server:

brew install ngrok
ngrok config add-authtoken YOUR_TOKEN
ngrok http 3131 --url your-brain.ngrok.app

Your OAuth issuer URL is whatever --public-url names (https://your-machine.your-tailnet.ts.net under Tailscale, https://your-brain.ngrok.app under ngrok). The MCP SDK's router exposes the spec-compliant discovery endpoint at /.well-known/oauth-authorization-server. The protected resource is the /mcp endpoint itself: its RFC 9728 metadata is served at /.well-known/oauth-protected-resource/mcp (the bare /.well-known/oauth-protected-resource root stays as an alias for older clients), and every 401 carries WWW-Authenticate: Bearer resource_metadata="<that URL>", so an MCP client pointed at https://your-machine.your-tailnet.ts.net/mcp finds the token endpoint from a fresh connection without any pasted URLs.

Dual-mode auth on /mcp. The same route verifies OAuth 2.1 access tokens and gbrain auth create bearers (OAuth first, then the access_tokens fallback). The 401 + resource_metadata challenge is emitted by the MCP SDK middleware for ANY request lacking an Authorization header (RFC 9728 / MCP auth spec §5.1 discovery) and says nothing about whether a configured token works. A client status probe that omits the header will therefore report needsAuth / authentication_required even while the configured bearer succeeds. Judge auth from whoami (transport: legacy|oauth) or gbrain auth test <url> --token <t>; treat a client's needsAuth flag as advisory unless the authenticated call itself returns 401 / invalid_token.

Tailnet / LAN-only (no public tunnel)

Two shapes work without exposing anything to the internet. In both, clients authenticate with gbrain auth create bearer tokens.

Tailscale Serve (HTTPS, tailnet-only). This is what gbrain mcp expose automates (plus the admin token file, the user service and the health checks). By hand: keep the default 127.0.0.1 bind, let Tailscale terminate TLS on the tailnet, and point --public-url at your MagicDNS name:

gbrain serve --http --port 3131 --public-url https://your-machine.your-tailnet.ts.net
tailscale serve --bg 3131

Clients on the tailnet use https://your-machine.your-tailnet.ts.net/mcp. The "--public-url is set but --bind is not" WARN is expected in this shape — Tailscale Serve forwards to loopback. tailscale serve stays inside your tailnet; tailscale funnel (or gbrain mcp expose --funnel) is public exposure for cloud agents (see ALTERNATIVES.md).

Plain HTTP, bearer-only. Bind the tailnet/LAN interface and omit --public-url entirely:

gbrain serve --http --port 3131 --bind 100.x.y.z   # or --bind 0.0.0.0

The OAuth issuer defaults to http://localhost:3131, which the MCP SDK accepts, and bearer-token verification never reads the issuer. Clients connect to http://100.x.y.z:3131/mcp with Authorization: Bearer …. OAuth discovery is the one thing this shape does not offer (the advertised issuer is loopback), so OAuth-only clients such as ChatGPT need the HTTPS shape above. Passing --public-url http://100.x.y.z:3131 instead fails at startup — see Troubleshooting.

4. Scopes and localOnly

Every operation is tagged read | write | admin. Operations flagged localOnly: true in src/core/operations.ts (sync_brain and the file_* ops among them) are rejected over HTTP regardless of scope. Remote agents cannot reach local filesystem surface area.

Scope What it allows
read search, query, get_page, list_pages, graph traversal
write put_page, delete_page, add_link, add_timeline_entry
admin Eligible admin-tagged brain operations; local-only restrictions still apply. Does not grant dashboard or client-management authority.

Write ops can additionally be fenced per client with --bound-slug-prefixes (see Register OAuth clients above).

Legacy Bearer Token Setup

Bearer tokens are the simple path when you don't need per-client scoping. Without a --scopes grant they carry read+write+admin on the HTTP server; pass --scopes read,write at creation to narrow one.

1. Publish the server

Tailscale (recommended): gbrain mcp expose (add --funnel for cloud clients) — remote MCP guide. ngrok alternative, see the ngrok-tunnel recipe; quick version:

gbrain serve --http --port 8787
brew install ngrok
ngrok config add-authtoken YOUR_TOKEN
ngrok http 8787 --url your-brain.ngrok.app  # Hobby tier for fixed domain

2. Create access tokens

These commands open the database. On PGLite, mint the token before publishing the service in step 1, or use the running server's owner API to provision a scoped machine handoff. A second database process fails with live_serve; do not remove its lock. Postgres supports concurrent local maintenance.

# Create a token for each client
gbrain auth create "claude-desktop"

# List all tokens
gbrain auth list

# Revoke a token
gbrain auth revoke "claude-desktop"

Tokens are per-client. Create one for each device/app. Names are not unique: gbrain auth revoke "<name>" revokes EVERY active token carrying that name — use gbrain auth list (shows each token's id and scopes) and gbrain auth revoke --id <uuid> to revoke exactly one. Tokens are stored SHA-256 hashed in your database.

3. Connect your AI client

4. Verify

gbrain auth test \
  https://your-machine.your-tailnet.ts.net/mcp \
  --token YOUR_TOKEN

(Substitute your ngrok domain or cloud host URL when you used one of those.)

Operations

GBrain's operation catalog (100+ operations in src/core/operations.ts) is available subject to the selected surface, scope and operation-specific limits. Operations flagged localOnly: true are rejected over HTTP regardless of scope (see Scopes and localOnly above). Code-inspection operations and stored contradiction reports also have temporary local-only restrictions, even when listed in the catalog. The MCP surface runbook explains these limits and the separate chunk-rebuild requirement. Rebuild indexes from a local installation on the brain host; a thin client cannot rebuild the host's indexes.

Several brains behind one tool catalog? Give each server an identity so a connected agent can tell them apart: gbrain config set mcp.instructions "<identity>" rides the initialize response of every transport (stdio, OAuth HTTP, legacy bearer) under a Deployment identity: banner, appended below the canonical agent contract — no transport can weaken the contract. Restart gbrain serve after setting it (the response is built once per process); GBRAIN_MCP_INSTRUCTIONS in the serve process's environment overrides the configured value for that process, and a blank variable falls back to it. Say to your agent: "Tell connected agents which brain this is" — your agent runs gbrain config set mcp.instructions "<identity>".

Security note on file access: the file_* operations being localOnly is the first line of defense; as defense-in-depth, file_upload also confines any caller that isn't verifiably the trusted local CLI to the working directory where gbrain serve was launched. Symlinks, .. traversal, and absolute paths outside cwd are rejected, and page slugs and filenames are allowlist-validated (alphanumeric + hyphens; no control chars, RTL overrides, or backslashes). Local CLI callers (gbrain files upload ...) keep unrestricted filesystem access since the user owns the machine.

Status-only mode

A gbrain serve --http that cannot open its brain (another serve holds the PGLite lock, no brain is configured yet, the brain is missing or damaged, or the config is unreadable) keeps its port and answers in status-only mode instead of exiting, so a supervisor does not crash-loop it and every client sees the cause:

$ curl -i localhost:3131/health
HTTP/1.1 503 Service Unavailable
Content-Type: application/json
Retry-After: 5

{"status":"unavailable","reason":"unavailable","why":"This gbrain server cannot open its brain; its host operator can see why with `gbrain doctor`.","fix":{"argv":["gbrain","doctor","--json"],"command":"gbrain doctor --json","consent":[],"actor":"host_admin","next":"tell_user_to_run",...},"user_message":"The gbrain memory server is running but cannot open its brain, so memory is offline. ...","retry_after_s":5,"contract_version":1,"instance":"<nonce>"}
  • /mcp offers only gbrain_status; OAuth and admin routes answer 503 with the serve_status_only envelope. Responses never name the reason, a path or a PID: Tailscale Funnel delivers public requests from a loopback address, so every request is treated as remote.
  • On the host, stderr prints the reason and its fix ("Re-checking every 5 s; Ctrl-C to stop; --fail-fast to exit instead"), the marker GBRAIN_HOME/serve-http-status-<port>.json records it, and gbrain doctor --only harness_wiring reports serve_status_only with the fix. gbrain mcp expose reports verify.local as status-only with the reason.
  • The server re-checks every 5 s and, once the brain opens, serves the full app on the same port. Clients reconnect: a client that connected during status mode receives 401 with WWW-Authenticate resource metadata and completes OAuth again.
  • Container health checks that probe /health treat the 503 as unhealthy and restart the container. Pass --fail-fast (or set GBRAIN_SERVE_FAIL_FAST=1) there so the process exits non-zero with the classified envelope on stderr.
  • A supervisor that should also catch a pool that accepts TCP but answers no real request probes /health?deep=1 instead: it runs SELECT 1 through the same pooled dispatch the MCP handlers use, returns the pool block (checked_out, waiters, inflight_oldest_ms, stuck_discards, …) and answers 503 when the probe times out or a statement is past the pool's in-flight budget (pool diagnostics). A two-minute interval is fine; one deep probe runs at a time. Every 503 names a stable code (persistence_restart_required, pool_inflight_over_budget, deep_health_probe_failed) with fix and docs, and both answers carry the transport block (pooler mode, max_pipeline, the server statement_timeout); the probe only reports (serve deep health).
  • To have serve restart itself when it stays unhealthy, set GBRAIN_SERVE_RESTART_REQUIRED_EXIT_SECONDS=<n> (at least 120; in ~/.gbrain/env for the service gbrain mcp expose installs). After n continuous seconds of persistence_restart_required it exits 69 (serve_unhealthy_exit, cleanup bounded at 5 s; at most 3 self-exits per hour) and the supervisor starts a fresh one (unhealthy exit).
  • A second gbrain serve --http on a port another server already holds exits with serve_port_in_use. A Postgres connect failure keeps the degraded-engine path (GBRAIN_DB_ACCESS marker, gbrain db-repair).

Deployment Options

Tailscale via gbrain mcp expose is the recommended shape for a brain on your own computer (remote MCP guide). See ALTERNATIVES.md for how Tailscale Serve / Funnel compare with ngrok and always-on 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:

[ ] 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_ids, so even a leaked connection string can't read everything.

Writer coordination lock in containers

A managed checkout's writers share one native lock file outside the checkout. It lives in $GBRAIN_HOME/.gbrain/persistence/locks unless GBRAIN_HOME is the checkout or lies inside it; then it goes under GBRAIN_COORDINATION_HOME (else ~/.gbrain/persistence). For the lock to survive container recreation, mount the directory that holds it together with the checkout and its parent: mount GBRAIN_HOME, or, when GBRAIN_HOME is inside the checkout, set GBRAIN_COORDINATION_HOME to a mounted absolute path outside the checkout in the container's environment (a .env file in the working directory cannot set it). gbrain sources writer status --json shows the resolved path and the rule that chose it under onboarding.sources[].coordination_lock; the full rule is in topologies.

Run gbrain under a real init (tini / --init)

If gbrain serve is your container's entrypoint, it runs as PID 1 and inherits every orphaned process in the container. Prefer a real init so orphan exits are reaped by something built for the job:

# Dockerfile: wrap the entrypoint with tini
ENTRYPOINT ["/usr/bin/tini", "--", "gbrain", "serve", "--http"]

or at run time:

docker run --init ... gbrain serve --http

Without an init, gbrain installs its own PID-1 orphan reaper (Linux only): a low-frequency /proc scan that waitpid()s zombies re-parented to it, so long-lived containers don't accumulate defunct entries in the PID table. It is fail-open and can be disabled with GBRAIN_PID1_REAP=0 — but tini / --init remains the recommended setup.

Troubleshooting

"missing_auth" error Include the Authorization header: Authorization: Bearer YOUR_TOKEN

"invalid_token" error Run gbrain auth list to see active tokens.

Client status shows needsAuth / authentication_required but tool calls succeed The client probed /mcp without an Authorization header and read the spec-mandated discovery 401 as a failed login. Both OAuth tokens and legacy bearers are accepted on /mcp; confirm with whoami (transport: legacy) or gbrain auth test <url> --token <t> and only re-authenticate if THAT call returns 401. See Dual-mode auth on /mcp.

"service_unavailable" error Database connection failed. Check your Supabase dashboard for outages.

"Issuer URL must be HTTPS" at startup The MCP SDK rejects a non-HTTPS OAuth issuer unless the host is localhost or 127.0.0.1, so --public-url http://<lan-or-tailnet-ip>:3131 exits before the server listens. Either terminate TLS in front (Tailscale Serve, ngrok, Cloudflare Tunnel) and pass the https:// URL, or drop --public-url for a bearer-only LAN endpoint — both shapes are in Tailnet / LAN-only. Last resort, for plain-HTTP OAuth discovery on a private network you fully control: the SDK's own MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL=1 opt-in. Bearer auth works either way; OAuth clients may still refuse a non-HTTPS issuer.

A connector loops back to sign-in, or the token endpoint returns invalid_target Every OAuth authorization, token, refresh and bearer check uses one resource: <origin of --public-url>/mcp. The bare origin is accepted as an alias. A requested resource that is anything else, such as an old tunnel hostname, http for an https server or a query string, gets invalid_target naming the accepted URL. A bearer token bound to another resource gets invalid_token, and a stored grant for a resource this server no longer serves gets invalid_grant on refresh. Point the client at the accepted URL or fix --public-url, then reconnect. ChatGPT specifics are in CHATGPT.md.

A claude.ai connector can search but not save The /mcp challenge hints read write, and each token is capped to the client's registered scope. A connector approved before v0.60.5.0 received a read-only hint and keeps a read-only grant. Remove and re-add the connector, and approve write on the consent screen. If the client is registered with read only, widen it first (ADMIN.md).

serve --http stops answering and spins at full CPU Turn on the loop-stall watchdog so a wedged process exits instead of spinning until the host runs out of memory: export GBRAIN_SERVE_STALL_WATCHDOG_MS=60000 in the serve process's environment (systemd Environment=, launchd EnvironmentVariables), then restart gbrain serve --http. A watchdog thread checks the main event loop; when the loop has not answered for that many milliseconds, it logs and sends SIGTERM, and 30 seconds later, if the loop is still stuck, SIGKILL, so a supervisor restarts the server. It is off by default (unset or 0); values below 15000 are raised to 15000. Large PGLite brains pause the loop for tens of seconds during checkpoints, so keep 60000 or more there. The watchdog covers serve --http only; stdio serve exits with its client. Before every tool call, serve --http writes [gbrain-serve] dispatch op=<name> args_sha256=<16 hex> to stderr, so the last such line before a stall names the request that caused it. The digest is a SHA-256 of the call's JSON arguments (compute it on the client to match); the arguments themselves are never logged.

Claude Desktop doesn't connect Remote servers must be added via Settings > Integrations, NOT claude_desktop_config.json. See CLAUDE_DESKTOP.md.

gbrain mcp expose stops on a Tailscale error or verify.tailnet: pending The pre-checks (tailscale_https_not_enabled, tailscale_funnel_not_enabled — exit 2 with the admin-console URL, nothing published), the classified errors (https_not_enabled, funnel_not_enabled, needs_operator, daemon_not_running, …), the pending-certificate wait, and the service/--status checks are tabled in the remote MCP guide.

Expected Latencies

Operation Typical Latency Notes
get_page < 100ms Single DB query
list_pages < 200ms DB query with filters
search (keyword) 100-300ms Full-text search
query (hybrid) 1-3s Embedding + vector + keyword + RRF
put_page 100-500ms Write + trigger search_vector update
get_stats < 100ms Aggregate query

Note: gbrain serve --http has OAuth 2.1 + the admin dashboard baked into the binary. The custom HTTP wrapper pattern (see voice recipe) is supported for teams that need bespoke middleware, but for most remote deployments the built-in server is the recommended path.