Garry's Opinionated OpenClaw/Hermes Agent Brain
Use your brain from anywhere over MCP
Your brain runs on your own computer. gbrain mcp expose publishes its MCP
server on your Tailscale tailnet with HTTPS, keeps
it running as a user service, and prints the URL your other devices, apps and
cloud agents connect to. Tailscale is the recommended path; ngrok and cloud
hosts stay as alternatives.
Rather not keep a computer online? gbrain.io is hosted GBrain: always on, and reachable from ChatGPT, Claude and Cursor without Tailscale or a user service.
Say to your agent: "use my brain over mcp" — "put my brain on
tailscale" — "connect grok bot to my brain" / "connect claude desktop to
my brain" — "reach my brain from my phone". The remote-mcp skill
(skills/remote-mcp/SKILL.md) walks the agent through publishing, choosing
native OAuth or a private machine handoff, and verifying the intended client;
the exact commands are below.
Who reaches what
| Client | Shape | Why |
|---|---|---|
| Your own devices — Claude Desktop, Claude Code / Codex / opencode on another laptop, phone apps on the tailnet | tailscale serve (tailnet-only HTTPS) — the default |
Nothing on the public internet; Tailscale ACLs plus gbrain auth |
| Cloud agents that run in a vendor's cloud — Grok Bot, Muse, ChatGPT connector, Claude.ai / Cowork, Perplexity Computer | tailscale funnel (public HTTPS on the same *.ts.net name) — explicit --funnel |
Their runtime is not on your tailnet; gbrain's OAuth/bearer auth plus scoped grants protect the endpoint |
A cloud agent whose runtime you can join to your tailnet (userspace tailscaled, ephemeral auth key) |
tailnet-only | Advanced; not automated and not verified against a real vendor runtime |
gbrain mcp expose never publishes to the public internet unless you pass
--funnel. Both shapes keep gbrain serve --http on its default loopback
bind (127.0.0.1); Tailscale terminates TLS and forwards to it. The
"--public-url is set but --bind is not" warning at startup is expected
in this shape.
What gbrain mcp expose does
gbrain mcp expose # tailnet-only, port 3131, full surface listing the memory verbs, service installed
gbrain mcp expose --funnel # also reachable by cloud agents (public HTTPS)
gbrain mcp expose --dry-run # print the plan, change nothing
Run it on the brain host (a thin client is refused: "run on the brain
host"). It never opens the database, so it works while gbrain serve holds a
PGLite brain's single-writer lock. Every step is reported as a named check
(--json lists them):
| Step | What happens |
|---|---|
plan |
Resolves options; detects platform, execution environment and engine kind (PGLite vs Postgres); prints what will be installed or changed. A host with no brain config (no gbrain init yet, or an unreadable config) is refused here with no_brain_config — a service there would only crash-loop — unless you pass --no-service to publish a server you run yourself (--dry-run still prints the plan, with the refusal marked, and exits 0). On a PGLite brain it also reads the lock file: a live process that is not gbrain's own running service adds a Lock line and a pglite_lock warning (the service cannot start until that process exits — stop it, or move to Postgres); the run proceeds. --no-tailscale while the receipt says the brain is published on the tailnet (it records a MagicDNS name) is refused with tailscale_receipt_present — rewriting the receipt to loopback would leave the live Serve/Funnel mapping unfindable; run gbrain mcp expose --remove --yes first, or drop the flag. Then it probes 127.0.0.1:<port>: anything listening there — a TCP connect that is accepted (a non-HTTP service too) or an HTTP answer of any status on /health (a 404 or 500 counts — the port is occupied) — with no receipt claiming that port stops the run with foreign_listener ("Something already answers on 127.0.0.1: and no expose receipt claims it. Stop it, pick another --port, or pass --no-service to only publish it. If this is a gbrain server left behind by an interrupted gbrain mcp expose, run gbrain mcp expose --remove --yes first.") before anything is published. --dry-run stops here. |
consent |
Installing Tailscale, running tailscale up, writing the serve/funnel config and creating a user service change system state (effects persistent_install, plus egress unless --no-tailscale). Interactive: one y/N prompt; declining is pending / exit 2 with "Nothing changed: the confirmation was declined." Non-interactive without --yes (no terminal, CI, or an agent process): prints the plan and an [AGENT] block with the words to ask the user, and exits 2; under --json the pending document also carries the consent fields (code: confirmation_required, effects, user_message, fix with next: ask_user). |
tailscale.binary |
Finds tailscale on PATH or in the usual macOS/Homebrew/Linux locations. Missing: macOS installs brew install --cask tailscale-app; Linux runs the official curl -fsSL https://tailscale.com/install.sh | sh installer (it prompts for sudo itself). --no-install prints the plan and exits 1 instead. Other platforms: exit 1 with https://tailscale.com/download. |
tailscale.login |
Reads tailscale status --json. Not logged in: Linux runs sudo tailscale set --operator=$USER first (so you can run serve without root afterwards; a failure is noted, not fatal) and then a flagless sudo tailscale up; macOS runs the app CLI's tailscale up (after a fresh brew install it opens the app and gives it a moment first). Linux puts sudo in front of the binary only when it is a system install (/usr/bin, /usr/local/bin, /opt/homebrew/bin, or a symlink resolving there); a tailscale found elsewhere on PATH (say ~/.local/bin) is never run as root — the step stops with tailscale_login_manual (exit 2) and, if you trust that binary, asks you to run sudo <that path> set --operator=$USER && sudo <that path> up yourself (the full path, because a binary outside sudo's secure_path is exactly this case), then re-run. Shows the login URL. Waits up to five minutes; still not running: exit 2 (tailscale_login_pending) with the exact re-run command. |
tailscale.identity |
Takes your MagicDNS name → https://your-machine.your-tailnet.ts.net, then pre-checks the tailnet features serve/funnel need — the Tailscale CLI does not fail when they are missing, it prints an enablement URL and waits for you interactively, so expose never starts it blind. CertDomains empty (HTTPS certificates not enabled) → pending, exit 2, reason tailscale_https_not_enabled, with https://login.tailscale.com/admin/dns and the re-run command. --funnel on a node without the Funnel capability → pending, exit 2, reason tailscale_funnel_not_enabled, with https://login.tailscale.com/admin/acls and the Funnel docs. In both cases nothing has been published yet. |
tailscale.publish |
Reads tailscale serve status --json — including other terminals' foreground serve sessions and a raw TCP forward on :443 — and refuses to overwrite a / handler that already proxies a different local port unless --force (foreign_serve_config; a foreground session has to be stopped in its own terminal, --force cannot replace it). That read fails closed: a non-zero or killed exit, or output that is not a JSON object, is never treated as "nothing configured" — the run stops with the classified reason (tailscale_needs_operator, tailscale_daemon_not_running, tailscale_unknown, …) and nothing is published; only an empty document from a clean exit is an empty config. Then tailscale serve --bg <port> (or tailscale funnel --bg <port>) with a 60s timeout; a hang is reported as unknown with the command to run by hand. Stderr failures are classified as a second line of defense (see Troubleshooting). Re-reads the status to confirm the port is proxied. Switching your own handler from Funnel back to tailnet-only turns Funnel off first (tailscale funnel --https=443 --set-path=/ off — --set-path=/ scopes off to gbrain's one mount; without it the CLI removes every mount under :443 and prompts when several exist); if the following serve --bg then fails, times out or cannot be confirmed, the previous Funnel handler is re-published and the check says whether that restore worked, and the existing receipt is kept. The other direction is one atomic funnel --bg. |
admin_token |
Ensures ~/.gbrain/serve/admin-token (0600, 64 hex chars). Reused on later runs; never printed. The expose-managed service wrapper loads it as GBRAIN_ADMIN_BOOTSTRAP_TOKEN, so gbrain mcp admin and gbrain mcp grant --admin-token-file work headlessly. With --no-service, the independently running server must already use the matching credential; creating this file does not configure that process. |
service |
Writes the wrapper ~/.gbrain/serve/gbrain-serve.sh, then installs a launchd user agent (com.gbrain.serve; launchctl bootout gui/$(id -u) then launchctl bootstrap gui/$(id -u), so a re-run relaunches the regenerated wrapper — a bootstrap that fails while launchd is still unloading the previous job ("Input/output error", "already in progress") is retried up to five times a second apart; the legacy unload/load pair is used only when that launchctl does not know the modern verbs) on macOS or a systemd user unit (gbrain-serve.service) on Linux with a user bus (daemon-reload → enable → restart, so a re-run's regenerated wrapper takes effect) and starts it. The receipt is written right after this step (before verify), so an interrupted run always leaves something --status / --remove can find. No supervisor (cloud sandbox, ephemeral container): service: manual — the wrapper is written and the exact foreground and nohup … & commands are printed. --no-service only publishes an already-running server; on a re-run it keeps the service block of the existing receipt and leaves the wrapper alone. If the install fails (service_install_failed, exit 1) the receipt is still written with service.state: stopped so --status and --remove can see and clean up the published handler. |
verify.local / verify.tailnet |
verify.local polls http://127.0.0.1:<port>/health (20s wall clock; a timeout is a warn and exit 2 with verify.tailnet skipped). verify.tailnet polls https://<your name>/health (30s); pending is exit 2 (first certificate issuance can take a while), never a hard failure. When this host cannot resolve its own MagicDNS name the check is a warn, not pending, and the run exits 0: MagicDNS is probably off on this machine (tailscale set --accept-dns=true), and devices that do resolve the name may already reach the server. Bun's fetch reports an unresolvable name and a refused connection with the same error, so after a rejected probe expose asks the system resolver directly — ENOTFOUND, EAI_AGAIN, EAI_NONAME, EAI_NODATA mean "unresolved here" (a rejection whose message already names one of those counts too); a name that resolves but does not answer stays pending. |
receipt |
Rewrites ~/.gbrain/serve/expose.json (0600) with the settled service state (the early copy from the service step is updated; created_at is kept): port, URLs, mode, surface, service target and paths, engine kind. No secrets. |
Exit codes: 0 done, 1 failed, 2 needs confirmation (--yes, or you
declined the prompt) or a step is still pending (a tailnet feature to enable,
Tailscale login, certificate issuance). Exit 2 for "needs confirmation" is a documented
contract v1 legacy: every other gbrain command uses exit 3 for
confirmation_required (exit codes), and mcp expose moves to 3
in a future contract version. Read the JSON reason rather than the exit code
alone. Which exit 2 it is matters:
- A pre-check exit 2 —
consent(confirmation_required,declined),tailscale.login(tailscale_daemon_not_running,tailscale_login_manual,tailscale_login_pending) ortailscale.identity(tailscale_https_not_enabled,tailscale_funnel_not_enabled) — happens before anything is published, so it adds no serve/funnel handler, no service and no receipt. The login step may already have changed node state on the way there, though: on Linuxsudo tailscale set --operator=$USERrecords a persistent preference (your user may configureservewithout root from then on;--removedoes not revoke it —sudo tailscale set --operator=resets it) andsudo tailscale upmay have joined the machine to your tailnet. - A
pendingexit 2 fromverify.local/verify.tailnet(local_health_timeout,tailnet_health_pending) happens AFTER the handler was published, the service installed and the receipt written. Nothing is missing — the server just has not answered yet;--statusre-probes it and--removefinds everything.
The wrapper reads the admin token from its file at run time, sources your
shell profile and ~/.gbrain/env, prepends the Bun directory to PATH, and
execs gbrain serve --http --port N --public-url URL [--surface X] [--advertise verbs] [--enable-dcr]. The token never lands in the plist, unit or wrapper.
Paths above use the default GBrain home. Use the receipt's admin_token_file
and mcp_url for the intended server, especially with a custom GBRAIN_HOME.
The owner credential authorizes administration; an ordinary MCP token, client
secret, or OAuth admin scope does not. For --no-service, use that existing
server's actual protected owner credential, or follow its normal maintenance
procedure to configure one. A generated file or healthy endpoint alone does
not prove owner access.
Success output
Example for a managed service; command paths use the actual resolved home:
GBrain MCP server published on your tailnet
MCP URL https://your-machine.your-tailnet.ts.net/mcp
Admin https://your-machine.your-tailnet.ts.net/admin (owner session required)
Owner ~/.gbrain/serve/admin-token (protected service credential)
Reach tailnet only — your devices. Cloud agents (Grok Bot, Muse, ChatGPT) need `--funnel`.
Service launchd com.gbrain.serve, running (log: ~/.gbrain/serve/serve.log)
Engine PGLite (single-writer): host-side commands that open the database fail with `live_serve` —
administer through the running server (--admin-token-file; `gbrain sync` delegates to it),
or move to Postgres for concurrent local use.
Next — choose the connection method supported by the intended client
Owner login gbrain mcp admin login-link --url https://your-machine.your-tailnet.ts.net/mcp --admin-token-file '/home/example/.gbrain/serve/admin-token'
Native OAuth gbrain mcp admin register --help (public/confidential PKCE; exact client redirect URIs)
The native client starts authorization; the owner separately reviews consent.
Machine client gbrain mcp grant <name> --harness <id> --profile memory-writer --source default \
--url https://your-machine.your-tailnet.ts.net/mcp \
--admin-token-file '/home/example/.gbrain/serve/admin-token' --credentials-out /private/<name>.json
Machine install gbrain connect https://your-machine.your-tailnet.ts.net/mcp --harness <id> --credentials-file /private/<name>.json --install
Local agents PGLite: mint before the service runs (gbrain auth create local-agents --scopes read,write),
then gbrain bootstrap harness --yes --port 3131 --token <value>; or grant a scoped client with
gbrain mcp grant … --url http://127.0.0.1:3131/mcp --admin-token-file ~/.gbrain/serve/admin-token
and gbrain connect http://127.0.0.1:3131/mcp --harness <id> --credentials-file … --install
Cursor cursor://anysphere.cursor-deeplink/mcp/install?name=gbrain&config=eyJ1cmwiOiJodHRwczovL3lvdXItbWFjaGluZS55b3VyLXRhaWxuZXQudHMubmV0L21jcCJ9
Opens Cursor's MCP install prompt with this URL filled in; the Cursor machine must be on your tailnet.
Check gbrain mcp expose --status
The Cursor line is a one-click link: it opens Cursor's install prompt with
this MCP URL filled in. With --funnel, a Claude line comes first, which
opens claude.ai's add-connector form the same way. Tailnet-only publishes get
no Claude line, because claude.ai connects from Anthropic's servers. You still
confirm and sign in inside the client. --status repeats the links and
--json returns them as install_links. See one-click client
links.
The Engine and Local agents lines depend on the engine the receipt
recorded: a Postgres brain prints Local agents gbrain bootstrap harness --yes --port 3131 because minting works while the server runs.
The displayed machine grant/connect example is the private machine handoff path. For a native OAuth client, use the registration/setup path below instead. Tailnet versus Funnel controls reachability, not which authentication flow a client supports. The printed admin URL opens a login page; it does not sign in.
Command surface
gbrain mcp expose [--port N] [--funnel] [--surface verbs|starter|full] [--enable-dcr]
[--no-tailscale] [--no-service] [--no-install] [--force]
[--dry-run] [--yes] [--json]
gbrain mcp expose --status [--json]
gbrain mcp expose --remove [--yes] [--json]
| Flag | Meaning |
|---|---|
--port N |
Local port for gbrain serve --http (default 3131). Tailscale proxies :443 on your MagicDNS name to it. With --status or --remove and no receipt, the port whose leftover :443 handler is looked for and cleaned up. |
--funnel |
Public HTTPS via Tailscale Funnel instead of tailnet-only Serve. Required for cloud agents. |
--surface verbs|starter|full |
Tool surface, listed in full. Default: full with --advertise verbs (lists the memory verbs and request_tools; all stays callable). Older exposures keep their listing. |
--enable-dcr |
Turn on self-service client registration on the served server (off by default; every self-registered connection still stops for your approval in the admin dashboard). |
--no-tailscale |
Skip Tailscale entirely: install the service on loopback only, publish nothing. Exclusive with --funnel. |
--no-service |
Do not create a user service; only publish a server you run yourself. Also the way to publish from a host with no brain config (no_brain_config). |
--no-install |
Never install Tailscale; print the install plan and exit 1 when it is missing. |
--force |
Replace a / handler on :443 that already proxies another local port. With --remove: also delete the admin token file, and — without a receipt — turn off a :443 handler for --port that no wrapper, unit or service of gbrain's corroborates. |
--dry-run |
Print the plan and stop (exit 0). Exclusive with --status. |
--yes |
Skip the consent prompt (required for non-interactive runs). |
--json |
One JSON document on stdout: { status, receipt, checks: [{name, status, detail}], next_actions, reason?, message? }; prose goes to stderr. |
--status and --remove are exclusive with each other. Defaults: port
3131, tailnet-only, --surface full --advertise verbs, DCR off, service installed whenever a
supervisor exists.
--status
Reads the receipt, re-probes the Tailscale serve/funnel config, the service
state (launchctl print gui/$(id -u)/com.gbrain.serve or systemctl --user is-active gbrain-serve.service) and the local and tailnet health endpoints.
Exit 0 when everything verifies, 1 otherwise. A tailscale serve status that
cannot be read (non-zero exit, killed, or non-JSON output) is a failed
tailscale.publish check, never "handler present". A tailnet /health that
fails only because this host cannot resolve the name is a warn, not
pending, and still exits 0 (see verify.tailnet above).
No receipt: --status does not just say "not exposed" — it looks for the
leftovers an interrupted run can leave behind (the wrapper, a
com.gbrain.serve / gbrain-serve.service unit or live service, a :443
handler proxying --port, default 3131). Anything found is one warn check
per artifact, the recovery command goes into next_actions
(gbrain mcp expose --remove --yes, plus --force when only a handler stands
and nothing else of gbrain's corroborates it), and the exit is 1 with reason
leftovers_without_receipt (also under --json). Nothing found: "not
exposed", exit 0 — with --json exit 2 so scripts can tell.
--remove
Asks for consent (or --yes; declining is pending / exit 2, nothing
changed), then stops and removes the user service (it probes the supervisor
and removes a com.gbrain.serve / gbrain-serve.service that exists even
when the receipt says the service was skipped), clears only gbrain's own
serve/funnel handler (the one whose proxied port matches the receipt; Funnel
is switched off first when it was on) with
tailscale serve --https=443 --set-path=/ off — the --set-path=/ scopes the
command to gbrain's one mount, so other mounts under :443 are never touched
and the CLI never falls into its several-mounts prompt — and deletes the
wrapper and receipt. It never runs tailscale serve reset, never uninstalls
Tailscale and never logs you out; the Linux operator preference the login step
set stays as well (sudo tailscale set --operator= resets it). The admin
token file is kept unless you pass --force (a dashboard session may still be
using it). It prints what was left in place. On macOS a launchctl bootout
that fails for a reason other than "not loaded" is a service warn and
"the launchd job (bootout failed)" is named as left in place — check
launchctl print gui/$(id -u)/com.gbrain.serve.
If tailscale serve status cannot be read, --remove fails closed: the
tailscale.publish check fails with "could not read tailscale serve status;
handler left as is", the receipt and the wrapper are kept so a re-run can
finish the job, and the exit code is 1. The same holds after the off
attempt: --remove never reports success while gbrain's handler survives.
When the re-read still shows the handler (or cannot be read at all), the
service is already uninstalled but the receipt and the wrapper are kept, the
exit is 1 with reason handler_not_removed, and the message tells you to run
tailscale serve status and re-run gbrain mcp expose --remove --yes.
No receipt (an interrupted gbrain mcp expose — killed between
tailscale serve --bg and the receipt write): --remove recovers from what
is on disk. It looks for the wrapper, the launchd plist / systemd unit (or a
loaded service) and a / handler on :443 that proxies to --port (default
3131 — pass the port you published with), prints a "Recovering without a
receipt" plan, asks for consent as usual, and removes exactly those artifacts
(Funnel off first when it was on). The handler is turned off only when
something else of gbrain's corroborates it — the wrapper, the unit/plist, or
the supervisor reporting the service — because another tool may proxy :443
to the same port; a handler standing alone is reported and left in place
(exit 0) until you pass --force. A handler that survives the off attempt
is handler_not_removed here too (exit 1); the wrapper is kept as the
corroboration the re-run needs. When tailscale serve status cannot be read
while the wrapper or the service is there, this path fails closed exactly like
the receipt path: the service (when found) is still stopped and removed, but
the wrapper is kept — it is the corroboration the re-run needs — the
tailscale.publish check fails with "could not read tailscale serve status;
handler state unknown", and the exit is 1 with reason
tailscale_serve_status_unreadable; fix Tailscale and re-run the printed
command to finish. The admin token file is left alone. When nothing of
gbrain's is found the answer stays "not exposed — nothing to remove", exit 0
(reason not_exposed; an unreadable serve status is then only a caveat, since
there is nothing to keep and a handler alone would not be touched anyway). A
completed recovery exits 0 with reason recovered_without_receipt.
Grant, connect, verify
The published server accepts the same clients as any gbrain serve --http.
Choose the connection method supported by the intended harness before creating
its least-privilege registration. Native OAuth/PKCE and private machine
handoffs are different paths. A cloud/tailnet choice or vendor name does not
select between them.
Run owner actions on the host or in a separately authorized administrator harness through the running server's API. This uses the existing connection while a PGLite service holds its lock. The default expose credential file below is valid for the expose-managed service; substitute the actual receipt path and configured URL. An ordinary connecting client without owner authority must hand these actions to that administrator, not request broader OAuth scopes.
Open the owner panel
gbrain mcp admin login-link \
--url https://your-machine.your-tailnet.ts.net/mcp \
--admin-token-file ~/.gbrain/serve/admin-token --json
Deliver the returned single-use link privately without fetching or opening it
to test it. The plain admin URL does not authenticate the browser. During
native OAuth, preserve the exact opaque pending request with
login-link --oauth-request REQUEST_ID. The owner then reviews and approves
consent separately. Expired requests or a server restart require restarting
authorization in the native client. See MCP administration
for owner login, client inspection, permission edits, and lifecycle actions.
Native OAuth/PKCE
Get the exact callback and token authentication method from the native client's
settings or guide. Public PKCE uses none and has no secret; confidential PKCE
uses the client's actual client_secret_post or client_secret_basic method.
Replace CLIENT_REDIRECT_URI below with that actual callback, then preview:
gbrain mcp admin register native-example --redirect-uri 'CLIENT_REDIRECT_URI' \
--token-endpoint-auth-method none --profile memory-writer --source default \
--url https://your-machine.your-tailnet.ts.net/mcp \
--admin-token-file ~/.gbrain/serve/admin-token --dry-run --json
Use memory-reader when only reading is requested. Review the result and repeat
without --dry-run. Confidential creation uses the actual POST/Basic method
and requires --credentials-out /absolute/private/oauth-setup.json; keep that
export private. Registration creates authorization-code and refresh grants
without minting a machine token. Retrieve setup using the returned client ID:
gbrain mcp admin setup CLIENT_ID --harness generic --flow authorization-code \
--url https://your-machine.your-tailnet.ts.net/mcp \
--admin-token-file ~/.gbrain/serve/admin-token --json
Use the actual supported adapter when known; generic supplies manual native
settings guidance. Enter the registration's live method, callbacks, and client
metadata in the intended harness. The native client starts OAuth and retains
its PKCE verifier; the owner signs in and approves its consent request. An
OAuthClientSetup document is not a private machine handoff for
gbrain connect or gbrain mcp verify. If manual client configuration is not
available, follow that client's guide; do not substitute machine credentials.
DCR remains opt-in, and manual owner registration works with DCR disabled.
Private machine handoff
For a harness using machine credentials or managed bearer configuration, preview a scoped grant through the owner API:
# On the authorized host/admin harness — one grant per client
gbrain mcp grant bot-example --harness grok-bot --profile memory-writer --source default \
--url https://your-machine.your-tailnet.ts.net/mcp \
--admin-token-file ~/.gbrain/serve/admin-token \
--credentials-out /private/bot-example.json --dry-run --json
After reviewing it, repeat without --dry-run. Then, inside the client's
environment after moving the machine credential file through a private channel:
gbrain connect https://your-machine.your-tailnet.ts.net/mcp --harness grok-bot \
--credentials-file /private/bot-example.json --install --root /workspace/gbrain
gbrain mcp verify --client CLIENT_ID --harness grok-bot \
--url https://your-machine.your-tailnet.ts.net/mcp \
--credentials-file /private/bot-example.json --json
Profiles (memory-reader, memory-writer, coding-agent, operator,
delegating-agent, full), private handoff, repair and the honest
verification bar are in hosted harness access.
Per-client notes:
- Grok Bot / Muse — the runtime lives in the vendor cloud, so publish
with explicit
--funnel. Select native OAuth when that is the intended connector; the commands above apply to the separate private machine path. For that path, Grok Bot's root is/workspace/gbrain; Muse needs a verified durable root first. See the Grok Bot and Muse guides. - Claude Desktop — follow its current connection guide for the supported native OAuth or local adapter mode. Native settings need a native registration, not credentials from a machine grant. Tailnet-only is enough when the actual connection runs on your tailnet laptop.
- Local coding agents on the host — on a Postgres brain,
gbrain bootstrap harness --yes --port 3131wires Claude Code / Codex / opencode to the running server. On a PGLite brainbootstrap harnessrefuses to mint while the service holds the database: either mint before the service runs (gbrain auth create local-agents --scopes read,write, run ahead ofgbrain mcp exposeor while the service is briefly stopped) and passgbrain bootstrap harness --yes --port 3131 --token <value>, or grant a scoped client through the running server —gbrain mcp grant <name> --harness <id> --profile memory-writer --source default --url http://127.0.0.1:3131/mcp --admin-token-file ~/.gbrain/serve/admin-token --credentials-out /private/<name>.jsonthengbrain connect http://127.0.0.1:3131/mcp --harness <id> --credentials-file /private/<name>.json --install(MCP wiring only, no per-turn hooks;http://is accepted on loopback). - Coding agents on another tailnet machine — for the private machine
path, use
gbrain connect <url> --harness <id> --credentials-file <private-file> --install. Native OAuth uses the native registration/settings path instead (Claude Code, Codex). - ChatGPT, Perplexity, Claude Cowork — cloud connectors:
--funnel, then the client guide (ChatGPT, Perplexity, Cowork).
Verify the selected connection
A passing gbrain mcp verify checks the private machine handoff's permitted
server access; writable grants also exercise write/readback and cleanup. For
native OAuth, use the intended harness's authenticated MCP connection to read
gbrain://capabilities and perform an allowed call. Do not feed the OAuth setup
export to the machine verifier. Registration, configuration delivery, server
probes, and observed native activation remain separate results.
Inspect advertised tool schemas before proposing a memory test. For an
authorized writable grant, use a harmless synthetic fact with provenance and
explicit visibility: "world" within the client's source grant. Keep its ID,
observe recall in a fresh conversation, correct it, then withdraw it and check
active recall. Private facts cannot be recalled or withdrawn by these remote
operations; never widen real private content to pass a test. Read-only clients
verify authenticated read access without adding write permission. Keep failed
cleanup visible, and do not promise erasure from history or backups.
Removing the exposure/service does not revoke client registrations or erase brain data. To end one client's access, follow the distinct preview/revision flows for token invalidation, revocation, or deletion in MCP administration.
Writing many pages
Say to your agent: "When you save more than three pages to gbrain, use put_pages with one request_id per batch and wait_ms 25000."
put_pageswrites 1-50 complete pages (8 MB of content at most) in one call. Every page is an ordinaryput_pagewrite with the same fences, revision checks and receipts; the pages are admitted together, so the writer queue has room for the whole batch or the call refuses withqueue_capacityand admits none of them. Keep 5-8 large pages per call: the model has to write every page into the tool arguments.- One receipt per batch. The reply lists each page's state, revision or
error (with its own
fix), counts, andnext:done,pollorfix_pages. A page refused for its own reason (an invalid slug, a slug outside the grant, a revision conflict) does not stop the others. - Replays and progress. Replaying the identical call with the same
request_idnever writes twice. Callingput_pageswith only therequest_idreads the batch's progress without resending the pages. A replay with different pages refuses withidempotency_conflictand names the pages that changed. wait_ms(put_page and put_pages, 0-30000 ms) holds the reply until the commit. It is not part of the write, so changing it on a replay is safe. When a reply is still pending, follownextno sooner thanretry_after_ms.- Links. For remote writes,
[[wikilinks]]in a page body that point at pages already in the same source become plainmentionslinks after the commit, and a batch links pages to each other once its last page commits.append_pagelinks what the appended text mentions the same way, without re-reading the rest of the page. The batch receipt'slinksfield shows when they have landed; agents do not add them by hand. Typed links still needadd_link. Turn this off withgbrain config set mcp.remote_auto_links false. - Embedding runs after the commit. New text is searchable by keyword immediately and by meaning once its embedding effect finishes.
- Request size. HTTP carries less than the 24 MiB page ceiling:
gbrain serve --httpreads at most 4 MiB per request (the MCP SDK default) and the simpler HTTP transport 1 MiB;GBRAIN_HTTP_MAX_BODY_BYTESsets either cap. A batch goes in smallerput_pagescalls; a page over the transport limit goes by file on the brain host (sync,gbrain importorgbrain put), never split by hand. Every limit is in limits per entry point.
PGLite brains
PGLite is single-writer. While the service runs, host-side commands that open
the database (gbrain doctor, gbrain import, gbrain auth create, a second
gbrain serve) fail fast with live_serve — they do not wait. gbrain sync
and gbrain sweep --once are the exceptions: they delegate into the live
serve automatically. Administer the brain through the running server instead
(gbrain mcp admin … --admin-token-file, gbrain mcp grant … --admin-token-file,
or an authenticated owner dashboard), or move to
Postgres for concurrent local use (ENGINES.md). The success
banner says which engine the receipt recorded.
Local agents on a PGLite host: gbrain bootstrap harness refuses to mint
under the live serve. Mint before the service runs
(gbrain auth create local-agents --scopes read,write — run it ahead of
gbrain mcp expose, or stop the service briefly) and pass
gbrain bootstrap harness --yes --port 3131 --token <value>; or skip
bootstrap and use the scoped grant path against the loopback URL
(gbrain mcp grant … --url http://127.0.0.1:3131/mcp --admin-token-file ~/.gbrain/serve/admin-token
then gbrain connect http://127.0.0.1:3131/mcp … --install). Postgres
brains mint fine while the server runs: gbrain bootstrap harness --yes --port 3131.
Troubleshooting
A served gbrain serve --http that cannot open its brain stays up in
status-only mode: /health answers 503
with Retry-After: 5, remote clients get a serve_status_only envelope whose
fix is gbrain doctor on this host, and the server opens the brain on the same
port once the cause is fixed. --fail-fast (or GBRAIN_SERVE_FAIL_FAST=1)
exits instead.
gbrain mcp expose --status re-runs the probes; --json names the failing
check. Logs: ~/.gbrain/serve/serve.log and serve.err. Serve rotates each
of them at 10 MiB and keeps 5 copies (serve.log.1 to serve.log.5), and a
line repeated within 10 minutes is written once, followed by one
[gbrain serve-log] repeated N more time(s) line. The same applies to any
gbrain serve whose output you redirect to a file with >>. Tune it with
GBRAIN_SERVE_LOG_MAX_BYTES (0 turns rotation off),
GBRAIN_SERVE_LOG_MAX_FILES and GBRAIN_SERVE_LOG_DEDUPE_SECONDS (0 turns
dedupe off) in the serve wrapper's environment.
| Symptom / classified error | Fix | Who acts | Consent | Verify |
|---|---|---|---|---|
tailscale_https_not_enabled (exit 2, tailscale.identity pending) — the tailnet has no HTTPS certificates (CertDomains empty); nothing was published |
Enable MagicDNS and HTTPS Certificates for your tailnet at https://login.tailscale.com/admin/dns, then run the printed re-run command. | user | none | gbrain mcp expose --status --json |
tailscale_funnel_not_enabled (exit 2, tailscale.identity pending) — the node lacks the Funnel capability; nothing was published |
Enable the funnel node attribute in your tailnet policy at https://login.tailscale.com/admin/acls (Funnel docs), then re-run with --funnel. |
user | egress (Funnel makes the server public) |
gbrain mcp expose --status --json |
tailscale_https_not_enabled / tailscale_funnel_not_enabled / tailscale_needs_login (exit 1) — the classified kinds: a tailscale serve status read or the tailscale serve / funnel call itself refused after the pre-checks passed |
Same fixes as the rows above (for tailscale_needs_login: finish the login, macOS via the Tailscale app); the classifier reads the CLI's stderr as a second line of defense. tailscale_unknown (exit 1) after 60s means the CLI is waiting on you — run the printed tailscale serve --bg <port> by hand to see its prompt. |
user | none | gbrain mcp expose --status --json |
tailscale_needs_operator (exit 1) — "Access denied" from tailscale serve (or its status read) on Linux |
sudo tailscale set --operator=$USER, then re-run. expose runs that set --operator itself before its flagless sudo tailscale up (a failure there is noted, not fatal); a tailnet joined earlier by other means may not have it. |
user | none | gbrain mcp expose --status --json |
tailscale_login_pending (exit 2) — after the login URL, tailscale status still is not Running |
Finish the login in the browser (macOS: open the Tailscale app and sign in), then run the printed re-run command. Nothing was published. | user | credentials (Tailscale login) |
gbrain mcp expose --status --json |
tailscale_login_manual (exit 2) — "tailscale at |
The tailscale on your PATH lives outside the system install locations, and gbrain never hands root to a user-writable binary. If you trust that binary, sign in yourself with the printed command — sudo <that path> set --operator=$USER && sudo <that path> up, the full path because sudo's secure_path would not find it — then re-run the printed command. |
user | none | gbrain mcp expose --status --json |
tailscale_receipt_present (exit 1, plan fails) — "This brain is already published on your tailnet at " |
You passed --no-tailscale while the receipt records a live Serve/Funnel mapping. Run gbrain mcp expose --remove --yes first, or re-run without --no-tailscale. |
agent, after the user agrees | none | gbrain mcp expose --status --json |
tailscale_daemon_not_running — "failed to connect to local Tailscale service" (exit 2 from the login step, nothing published; exit 1 when a serve status read or the publish itself is classified this way) |
macOS: open -a Tailscale. Linux: sudo systemctl enable --now tailscaled. Then re-run. |
user | none | gbrain mcp expose --status --json |
confirmation_required / declined (exit 2, consent pending) |
Not a TTY without --yes, or you answered no at the prompt. Nothing changed; relay user_message and run fix.command (it adds --yes) once the user agrees to the printed plan. |
agent, after the user agrees | persistent_install; egress unless --no-tailscale |
gbrain mcp expose --status --json |
invalid_arguments (exit 1) |
An unknown, duplicate, conflicting or malformed flag; the message names it. gbrain mcp expose --help. |
agent | none | gbrain mcp expose --help |
tailscale_missing (exit 1, --no-install) / tailscale_unsupported_platform (exit 1) / tailscale_install_failed (exit 1) |
Tailscale is not installed and expose would not (or could not) install it: run the printed install command, or install from https://tailscale.com/download, sign in, then re-run. |
user | persistent_install (installs Tailscale) |
gbrain mcp expose --status --json |
tailscale_no_dns_name (exit 1, tailscale.identity fails) — the node has no MagicDNS name |
Enable MagicDNS and HTTPS Certificates at https://login.tailscale.com/admin/dns, then re-run. Nothing was published. | user | none | gbrain mcp expose --status --json |
tailscale_publish_unconfirmed (exit 1) — tailscale serve --bg exited 0 but the re-read does not show the handler (or could not be read) |
Run tailscale serve status to see what Tailscale holds; gbrain mcp expose --remove --yes clears a handler for the port without a receipt (add --force when no wrapper or service of gbrain's is on the host yet), then re-run. |
agent | none | gbrain mcp expose --status --json |
service_install_failed (exit 1) — the supervisor refused the unit |
The handler IS published and the receipt written with service.state: stopped. Read the error (and ~/.gbrain/serve/serve.err), fix it, and re-run; or gbrain mcp expose --remove --yes to take the handler down. |
brain host | persistent_install |
gbrain mcp expose --status --json |
verify.tailnet: pending / tailnet_health_pending (publish exit 2; --status exit 1) |
The first certificate for your MagicDNS name is being issued. The handler, the service and the receipt are already in place — gbrain mcp expose --status in a minute. Local health ok means the server itself is fine. |
agent | none | gbrain mcp expose --status --json |
status_unhealthy (--status, exit 1) — one of the checks failed |
The failing check is named (tailscale.publish, service, verify.local); apply its row here and re-run gbrain mcp expose --yes to repair. |
agent, after the user agrees | persistent_install |
gbrain mcp expose --status --json |
not_exposed (--status / --remove without a receipt and without leftovers; exit 0, --status --json exit 2) / recovered_without_receipt (--remove, exit 0) |
Informational: nothing of gbrain's is published on this host, or the receipt-less recovery removed what an interrupted run left behind. | agent | none | gbrain mcp expose --status --json |
mcp_expose_failed (exit 1) — an unexpected error |
The internal check carries the message, and it says whether a handler published by this run was turned off again or left in place (a written receipt is never torn down — --status / --remove --yes). Re-run; report it if it repeats. |
agent | none | gbrain mcp expose --status --json |
verify.tailnet: warn — "this host cannot resolve your-machine.your-tailnet.ts.net" (exit 0) |
The brain host itself cannot resolve its MagicDNS name, usually because MagicDNS is off on this machine: tailscale set --accept-dns=true, then gbrain mcp expose --status. Devices that do resolve the name may already reach the server; this is not a certificate wait. |
user | none | gbrain mcp expose --status --json |
Another device cannot resolve your-machine.your-tailnet.ts.net |
Resolution needs MagicDNS on the tailnet (https://login.tailscale.com/admin/dns) and "Use Tailscale DNS settings" turned on in that device's Tailscale client. Reaching the name over HTTPS additionally needs the tailnet's HTTPS Certificates toggle on the same page (the tailscale_https_not_enabled pre-check catches that on the host). |
user | none | the other device resolves the name |
Service not starting (--status reports the service stopped) |
Read ~/.gbrain/serve/serve.err. Typical causes: gbrain not on PATH for a login-less shell (the wrapper falls back to type -P gbrain; install into ~/.bun/bin or reinstall), a key missing from ~/.gbrain/env, or the port already taken. launchctl print gui/$(id -u)/com.gbrain.serve / systemctl --user status gbrain-serve.service show the supervisor's view. |
brain host | none | gbrain mcp expose --status --json |
foreign_listener — "Something already answers on 127.0.0.1: and no expose receipt claims it. Stop it, pick another --port, or pass --no-service to only publish it. If this is a gbrain server left behind by an interrupted gbrain mcp expose, run gbrain mcp expose --remove --yes first." |
Anything listening on 127.0.0.1:<port> counts as occupied — an accepted TCP connect (a database, a non-HTTP service) as much as a 404 or 500 on /health — and no receipt claims that port. Refused during plan, before anything is published. Stop it, choose another --port, or pass --no-service to only publish the server you already run. A gbrain server left behind by an interrupted run is cleaned up by gbrain mcp expose --remove --yes (receipt-less recovery, see --remove). |
user | none | gbrain mcp expose --status --json |
no_brain_config (exit 1, plan fails) — "No brain is configured on this host (gbrain init first), so a service would only crash-loop; pass --no-service to publish a server you run yourself." |
This host has no gbrain config (or it cannot be read), so gbrain serve would have nothing to open and the supervisor would restart it forever. Run gbrain init on this host first, then re-run; or pass --no-service to only publish a server you start yourself. --dry-run still shows the plan. |
agent, after the user agrees | none | gbrain doctor --only connection --json |
pglite_lock warn — "a live process holds this PGLite brain (pid N, …): the service cannot start until it exits" |
PGLite is single-writer and a process other than gbrain's own running service holds the lock, so the freshly installed service will crash-loop until it exits. Stop that process (or let it finish), then gbrain mcp expose --status; for concurrent local use move to Postgres (ENGINES.md). The publish itself still completes. |
user | none | gbrain mcp expose --status --json |
"could not read tailscale serve status" — tailscale.publish fails during publish (exit 1, reason tailscale_<kind>), --status (exit 1) or --remove (exit 1, tailscale_serve_status_unreadable: with a receipt, receipt and wrapper kept; without one, the service is still removed but the wrapper is kept as the corroboration the re-run needs) |
tailscale serve status --json exited non-zero, was killed, or printed something that is not JSON. The command fails closed rather than guess: nothing is published over, removed from, or reported about a config it could not read. Run tailscale serve status --json by hand and apply the classified fix (operator, daemon, login), then re-run the same command. |
user | none | gbrain mcp expose --status --json |
An interrupted gbrain mcp expose (no receipt, but a handler / service / wrapper is left behind) — gbrain mcp expose --status reports leftovers_without_receipt (exit 1) naming each artifact |
Run the command --status prints: gbrain mcp expose --remove --yes (add --port N if you published a non-default port; --force when only a handler stands) recovers without a receipt: it removes the service, the wrapper and the :443 handler proxying that port, and leaves the admin token. A handler with no wrapper, unit or service next to it is left in place until you add --force. See --remove. |
agent, after the user agrees | none | gbrain mcp expose --status --json |
handler_not_removed (exit 1) — "--remove" stopped with "the tailscale handler for port is still present" (or "could not be confirmed gone") |
tailscale serve --https=443 --set-path=/ off ran but the re-read still shows gbrain's handler (or the serve status could not be re-read). The service was already uninstalled; the receipt and the wrapper were kept on purpose so the re-run finds everything. Run tailscale serve status, fix what it reports (operator, daemon), then gbrain mcp expose --remove --yes again. |
user | none | gbrain mcp expose --status --json |
foreign_serve_config — "tailscale serve already proxies :443 to . Re-run with --force to take it over, or pick another local port for that service." |
A / handler on :443 (a background config, another terminal's foreground tailscale serve session, or a raw TCP forward) already points somewhere else. Inspect it with tailscale serve status (the suggested next action), move that service, or — for a background handler only — re-run with --force; a foreground session must be stopped in its own terminal. |
user | none | gbrain mcp expose --status --json |
verify.local warn — "status-only (): the server runs but cannot open its brain" (publish exit 2; --status exit 1) |
The served gbrain serve --http is up on the port but in status-only mode: /health answers 503 and clients get the serve_status_only envelope. gbrain doctor --only harness_wiring names the reason's fix (for lock_held, stop the other process holding the PGLite brain). The server opens the brain within 5 s of the fix; no restart. |
brain host | none | gbrain mcp expose --status --json |
verify.local warn / local_health_timeout (exit 2) |
The service was installed but http://127.0.0.1:<port>/health did not answer within 20s; verify.tailnet is skipped. Read ~/.gbrain/serve/serve.err, then gbrain mcp expose --status. |
brain host | none | gbrain mcp expose --status --json |
service: manual (cloud sandbox, ephemeral container, no user bus) |
There is no supervisor to keep the server alive. Run the printed foreground command, or the nohup ~/.gbrain/serve/gbrain-serve.sh & line, and re-run --status. On Linux without a user bus, loginctl enable-linger $USER may enable one. |
brain host | none | gbrain mcp expose --status --json |
thin_client (exit 1) — "run on the brain host" |
This install is a thin client; expose publishes the machine that holds the database. Run it there. |
brain host | none | run --status --json on the brain host |
Clients see needsAuth while tool calls succeed |
Spec discovery, not a failed login — see DEPLOY.md troubleshooting. | agent | none | one tool call through the client |
A connector (ChatGPT, claude.ai) keeps asking to reconnect, or OAuth returns invalid_target naming an accepted URL |
The connector's MCP URL does not match the server's /mcp resource, which comes from the published URL (expose sets --public-url to your MagicDNS name). Use the accepted URL from the message, then reconnect once. Details in CHATGPT.md troubleshooting. |
user | none | one tool call through the connector |
Security posture
- Tailnet-only is the default. Only devices in your tailnet, subject to your Tailscale ACLs, can reach the name at all; every request still needs a gbrain OAuth token or bearer.
- Funnel is public exposure. Use it only for clients that cannot join
your tailnet, and give each one its own least-privilege grant (a
memory-writerprofile scoped to one source, notoperator). Revoke the client on the host when it should stop. Self-service registration stays off unless you pass--enable-dcr, and even then every new connection waits for your approval in the admin dashboard. - Remote
thinkruns your think model. Everythinkanswer is a paid call on the host's key, so a connected client'smodelis used only when it is your think model (models.think) or you allow it withgbrain config set think.remote_models <model>,<model>. Any other model answers on your think model, with amodel_override_ignorednotice instead of an error. - Loopback bind. The server keeps
127.0.0.1; never pass--bind 0.0.0.0for this shape. Tailscale is the only way in. - No secrets in chat or config. The admin token lives in a 0600 file the
wrapper reads at run time; the receipt carries none. Credential handoffs go
through private files (
--credentials-out), never pasted into a conversation. - Removal is scoped.
--removetouches only gbrain's own handler (the--set-path=/mount) and service; your Tailscale login, other serve configs and the Linux operator preference the login step set stay as they were (sudo tailscale set --operator=resets the latter). - Keep
GBRAIN_HTTP_TRUST_PROXYat its default for this shape. Tailscale is a loopback proxy and the default (loopback) trusts exactly that hop, so every tailnet or Funnel client keeps its own rate-limit bucket; turning trust off makes every request look like127.0.0.1and collapses the per-client limits into one bucket, and a wider setting trusts hops Tailscale does not vouch for.
See SECURITY.md for the HTTP server's hardening knobs (CORS allowlist, trust-proxy, rate limits, body cap).
Alternatives
ngrok. Public tunnel with a fixed domain on the paid tier. Run the server
yourself and point --public-url at the ngrok domain:
gbrain serve --http --port 3131 --public-url https://your-brain.ngrok.app
ngrok http 3131 --url your-brain.ngrok.app
ngrok connects to loopback on the same machine, so the default bind is right. The ngrok-tunnel recipe covers the auth token and fixed domain; ALTERNATIVES.md compares the options.
Cloud hosts (Fly.io, Railway, your own VM). For a brain that must answer
while your laptop is closed, run gbrain serve --http on the host with a
Postgres engine and a real HTTPS front, and set GBRAIN_ADMIN_BOOTSTRAP_TOKEN
through the platform's secret store (DEPLOY.md). The
owner-administration and native-OAuth/private-machine paths above still apply;
use that host's configured URL and owner credential.
No Tailscale, no tunnel. gbrain mcp expose --no-tailscale installs the
user service on loopback only. Local agents on the same machine use
gbrain bootstrap harness --yes --port 3131 on a Postgres brain; on PGLite,
pre-mint before the service runs and pass --token <value>, or use the scoped
gbrain mcp grant … --url http://127.0.0.1:3131/mcp --admin-token-file … +
gbrain connect … --install path (see PGLite brains).