Configuration

Each option is a flag and an environment variable. Flags win. A BRAIN_MAX_* option is a limit Brain enforces with a default it ships; the default is a starting point, not a fact about the machine, and the deployment that knows its machine sets the value. Zero on a limit means no bound, except the three queue capacities marked "at least 1". A limit the model provider enforces, such as its output token ceiling, is not here: Brain neither sets nor overrides it.

For deployment, remote callbacks, backups and upgrades, start with Operate Brain.

An Environment reached over HTTP is addressed by the session that names it: the URL and credential travel in the create request and the credential is sealed beside the model key. The server has no Environment routes, endpoints, or credentials of its own.

The data directory

Brain owns everything under BRAIN_DATA_DIR. Use an empty directory for a new installation; Brain writes the brain-data/1 layout marker on initialization. One server process may own it at a time. A matching marker does not establish compatibility with every earlier contract: pre-1.0 releases can change retained session and executable formats, and Brain does not automatically migrate old data. Follow the upgrade and restore procedure before changing the runtime on existing data.

brain-data/
  .lock                               process-held single-writer lock
  format                              layout marker (`brain-data/1`)
  sessions/{session_id}/journal/      one canonical journal per session
  sessions/{session_id}/checkpoint    disposable current-state/index projection
  agentloops/                         admitted Agentloop and Tool Components
  native-workspaces/{session_id}/{environment}/   retained native Environment workspace
  hosts/hosts.log                     host registrations and token hashes
  requests/requests.log               durable HTTP request claims and answers
  run/{worker_index}/                 separate worker sockets
  server-metadata/                    sealed model and Environment credentials

Session configuration, status, public Events, transcript, and Agentloop kv are projections of the canonical journal. Brain does not keep a second event or state log.

Listening beyond loopback

Brain refuses to start on a non-loopback address without BRAIN_API_TOKEN. Binding 0.0.0.0 with no token is a mistake worth failing on rather than serving.

The three BRAIN_ENV_* allow-lists are the ceiling on what the brain env may grant a Component whose Environment configuration explicitly requests it. Keep them empty in a multi-tenant deployment unless its control plane supplies the corresponding tenant custody, egress, and storage boundary. Never place Brain's own API or cloud credentials in the secret allow-list. A session can make the server call any Environment URL it names with the session's own credential; a hosted multi-tenant deployment may want an egress ceiling on those URLs.

Docker

The image sets BRAIN_DATA_DIR=/var/lib/brain, BRAIN_ENV_WORKER=/usr/local/bin/brain-env-worker, and BRAIN_LISTEN=0.0.0.0:8080, declares /var/lib/brain as a volume, and runs as uid 10001.

docker run --rm -p 127.0.0.1:8080:8080 \
  -e BRAIN_API_TOKEN=local-development \
  -v brain-data:/var/lib/brain ghcr.io/aexhq/brain:latest

This local example uses a development token. For deployment, set a private token and pin the tested image digest or ghcr.io/aexhq/brain:sha-<commit> tag; latest moves between releases. See release matching.

Health

Both health routes are public. GET /health/live returns 204 when the standalone server can answer requests. GET /health/ready returns 204 when the built-in worker pool is ready, or 503 when it is unavailable. Readiness does not validate model keys, remote Environments or free storage space. A successful check is not a guarantee that a particular turn will succeed.