Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
10.1 KB
Raw Blame

Warm CLI socket (Postgres)

Agents usually call gbrain by running the CLI once per question. On a Postgres brain each of those calls opens its own database connection, reads config and runs schema checks before it answers, and behind a transaction-mode pooler every one of those steps is a network round trip. A long-running gbrain serve already has all of that warm. The warm CLI socket lets that serve answer this user's CLI reads directly, so gbrain search costs about what the same search costs over MCP.

It is off by default. Nothing listens until you turn it on.

Say to your agent: "Turn on gbrain's warm CLI socket for my running serve so CLI searches stop paying a cold database connection each time."

Say to your agent: "Check whether my gbrain CLI reads are going through the warm serve socket or the cold path."

Turn it on

Start the serve with the flag:

gbrain serve --cli-socket

or set the config key once and restart the serve:

gbrain config set serve.cli_socket true

The serve logs one line on stderr: cli-socket: listening on …/run/cli.sock, or cli-socket: not started: <reason> when it cannot open the socket safely. A serve on a mount brain (gbrain serve --brain <mount>, GBRAIN_BRAIN_ID, a .gbrain-mount file or a mount path) never opens it: the socket serves the host brain only. Turn it off by removing the flag or running gbrain config set serve.cli_socket false, then restarting the serve. The serve reads the key from the config it already loaded when it connected, so a serve with the socket off does no work for it: it loads none of the socket's code and sends the database nothing extra. A serve that started degraded (database unreachable at boot) does not see the key; pass --cli-socket there.

What goes through it

Only reads: gbrain search, gbrain query (and ask), gbrain get, and the gbrain recall forms that run the recall operation (--query, --budget-tokens, --question, --budget-policy). The serve runs them through the same operation handlers with the same trusted local-CLI context, using your CLI's working directory and GBRAIN_SOURCE for source resolution, and the CLI prints the result with its usual renderer: the same stdout, stderr notices, --json documents and exit codes. Everything else, every write included, keeps the normal path.

Some calls take the normal path even with the socket on: --explain, --brain <mount>, query --image, input piped on stdin, the briefing, watch, cursor and rollup forms of recall, and a page large enough that get streams it.

When it is not used

The CLI falls back to its normal path when (silently, except for an identity refusal, which always prints a notice):

  • no serve has the socket open, or the serve died and left a stale socket;
  • the serve does not accept the request within about a second (a wedged serve never stalls the CLI);
  • the serve dies in the middle of the request: the CLI then runs the call itself, once, with its usual timeout and exit codes (it can only be a read, so running it again is safe);
  • the serve answers with a frame the CLI cannot fully read or render (nothing is printed from it);
  • the serve was started for a different brain or environment. The CLI sends its identity and the serve compares it part by part with its own: the brain (host or mount), the gbrain version, the config home, the config file (path and content), the database target and the read-behavior environment. The database target is the host, database, user and options parameter, never the password or driver-only parameters such as prepare=, sslmode or application_name. The port must match too, except on a Supabase Supavisor pooler host (*.pooler.supabase.com), where the same host and user name the same database, so a serve on the session lane (5432) answers CLI calls made on the transaction lane (6543). On any other host another port is another server and is refused. The read-behavior environment is an explicit list of the GBRAIN_* settings that can change an answer or where query text goes (READ_BEHAVIOR_ENV in src/core/cli-socket/identity.ts: models, embeddings, search tuning, visibility, timeouts, schema pack, AI call log, contributor capture and the like), which provider API keys are set (never their values, for every provider), and the values of the provider routing settings (base URLs, endpoints, deployments, API versions, org, project and group ids) of every provider either side can call. A provider neither side can call (one of its required variables is unset in the environment and the config file, and none of its keys is set) cannot reach an answer, so its routing settings may differ: an Azure API version exported in a shell that has no Azure endpoint no longer refuses the call. The identity decides which answer a call may reuse, never who may connect (see Security). Connection sizing and driver settings (GBRAIN_POOL_SIZE, GBRAIN_DIRECT_POOL_SIZE, GBRAIN_PREPARE, ...), the database URL variables and GBRAIN_SOURCE (which every request carries and the serve resolves for that call) may differ. GBRAIN_HOME and GBRAIN_BRAIN_ID count by the config home and brain they resolve to, so a serve that exports GBRAIN_HOME matches a CLI that reaches the same home through HOME. Editing config.json, changing a listed variable or upgrading gbrain while a serve runs sends CLI calls to the normal path until the serve restarts with the same settings. The refusal names the part that differed, never its value: refused (identity_mismatch): database port, env GBRAIN_MODEL, provider key VOYAGE_API_KEY, config contents, and the serve logs each distinct one once. Every refused call also prints a socket_identity_mismatch notice naming the part (an [AGENT] block on a non-TTY stdout, stderr under --json or on a TTY), and the serve counts refusals by part for gbrain doctor --only cli_socket_refusals, which warns while any happened in the last 24 hours;
  • the CLI targets a mount brain (--brain <mount> and the other mount tiers).

A warm call that takes longer than 30 seconds, or than its --timeout when that is shorter, does not start over on the cold path. The serve cancels the request's remaining work (its open read transactions are cancelled and their connections discarded, and its later statements are refused) and the CLI prints a retryable timeout error and exits 124: the envelope on stdout under --json, the human line on stderr, and without --json an [AGENT] block on stdout as well, so a caller that discards stderr still sees why. The CLI does the same when the serve never answers in time. A client that disconnects before its answer (killed by its own timeout) cancels the request the same way, and the serve logs it.

While warm CLI calls flow, the serve's idle maintenance sweep does not start: a socket request counts as activity, as MCP stdin data does. The serve logs idle sweep: started and idle sweep: finished in <n> ms around each sweep.

GBRAIN_DEBUG=1 prints one [cli-socket] cold path: <reason> line on stderr whenever a call falls back, including when no socket exists (no socket at <path>, with how to start one), and one [cli-socket] warm: <command> answered by the serve socket at <path> line when the serve answers. GBRAIN_CLI_SOCKET=0 makes a CLI call skip the socket entirely, for comparisons and benchmarks.

Caller timeouts

A call that falls back to the cold path pays the full start (3–6 s on a pooled Postgres brain) before it reads anything. Give gbrain calls from scripts and agent runtimes a timeout of at least 10 s, and set it in every layer that has one: a language runtime's exec timeout (Node's child_process, Python's subprocess, a harness tool timeout) can end the call before a longer shell timeout ever applies, and the kill reads as an empty result. Scheduled callers go through one wrapper (cron-schedule.md).

Security

  • Unix domain socket only, at $GBRAIN_HOME/.gbrain/run/cli.sock; never TCP.
  • The run directory is created 0700 and must be owned by your uid; the socket is 0600. Both the serve (before binding) and the CLI (before connecting) refuse a symlink, a directory or socket owned by another uid, or open permissions. GBRAIN_HOME and .gbrain above it must be yours too and writable by no one else (a sticky directory excepted); the serve refuses otherwise and never repairs them. The serve binds under umask 0177, so the kernel creates the socket 0600; it then checks the path is its own private socket and never changes permissions through it.
  • On every connection the serve reads the peer's uid from the kernel (SO_PEERCRED on Linux, getpeereid on macOS) and drops any other uid before reading the request. The CLI checks the serve's uid the same way. Where peer credentials cannot be read (another operating system, or a runtime that hides the socket descriptor), the serve refuses to open the socket and says why, and the CLI never connects.
  • One serve per GBRAIN_HOME holds the socket; requests and responses are size-bounded and each connection carries exactly one request. At most 8 requests run at once; a request that timed out keeps its slot until its cancelled work actually finishes, so slow requests cannot pile up.
  • The identity comparison is not an access check: who may connect is decided only by the file permissions and the peer uid above, and narrowing which provider settings must match never lets a call use a credential or a provider its own environment does not configure.
  • Postgres brains only. A PGLite brain's CLI calls already reach its running serve through the persistence socket.

Differences from a cold call

A warm call skips the cold path's connect-time work, so one-time startup notices (pending-migration warnings, upgrade disclosures) appear only on cold calls. Each warm request reads the DB-plane config once, in one statement, and answers every later config read in that request from it; nothing carries over to the next request, so a gbrain config set reaches the next warm call.