Configuration | Brain Docs

How config resolves

The server reads the TOML file passed via --config (the image defaults to /etc/brain/config.toml).
Any BRAIN__SECTION__FIELD environment variable overrides the matching field. Nesting uses double underscores: [monitoring.tracing] enabled → BRAIN__MONITORING__TRACING__ENABLED.

To replace the whole file rather than individual fields, bind-mount your own over /etc/brain/config.toml.

The one mandatory field: the LLM key

[llm]
api_key = ""            # operator sets at deploy time — never commit a real key
# model = "gpt-4o-mini" # provider is derived from the model id

BRAIN__LLM__API_KEYrequired

Required. brain-server refuses to boot with an empty key. Write-time HyPE and the extraction pipeline are always-on and depend on the LLM, so there is no keyless / substrate-only mode. One provider-agnostic credential is shared by every LLM consumer (HyPE, extraction, disambiguation, summarization).

BRAIN__LLM__MODELdefault gpt-4o-mini

The model id. The provider is inferred from it — claude* routes to Anthropic, otherwise OpenAI. Set the key to match the provider your model implies.

Disabling any extractor tier does not lift the key requirement. The key gates HyPE, which is always-on. Provide a valid key or the server will not start.

Server

[server]
listen_addr  = "0.0.0.0:8080"   # binary wire data plane (clients + SDKs)
metrics_addr = "0.0.0.0:9091"   # public HTTP: /healthz + /metrics
admin_addr   = "127.0.0.1:9092" # admin /v1/* HTTP surface — loopback by default

OptionTypeDefault / Env

server.listen_addrstringdefault: 0.0.0.0:8080

The data plane — the binary wire protocol (CBOR payloads). Publish with -p 8080:8080.

server.metrics_addrstringdefault: 0.0.0.0:9091

Public HTTP: /healthz liveness and /metrics (Prometheus text). Publish with -p 9091:9091.

server.admin_addrstringdefault: 127.0.0.1:9092

The admin HTTP surface (/v1/*). Kept on loopback by default and not published — reach it via docker exec or a token/mTLS proxy.

Storage and shards

[storage]
data_dir    = "/var/lib/brain/data"
shard_count = 1

[shard]
arena_capacity_bytes    = "1GiB"   # ≈ 660K vectors at 1600 B/slot
wal_segment_size_bytes  = "64MiB"
wal_retention_segments  = 16       # ≈ 1 GiB WAL retention per shard

OptionTypeDefault / Env

storage.data_dirstringdefault: /var/lib/brain/data

The persistent data directory — arena, WAL, redb, indexes. Back this up (see Backups).

storage.shard_countnumberdefault: 1

Number of shards. One shard pins one core. Grow this for write throughput on a bigger box — this is Brain's parallelism (see Scaling).

shard.arena_capacity_bytesstringdefault: 1GiB

Per-shard arena size for vectors. Override at runtime with BRAIN__SHARD__ARENA_CAPACITY_BYTES.

shard.wal_segment_size_bytesstringdefault: 64MiB

WAL segment size.

shard.wal_retention_segmentsnumberdefault: 16

How many WAL segments to retain — relevant for point-in-time recovery on top of a snapshot.

Index and embedder

[hnsw]
m               = 16
ef_construction = 200
ef_search       = 64

[embedder]
model           = "bge-small-en-v1.5"  # 384-dim, cached under the models dir
cache_size      = 10000
batch_size      = 32
batch_window_ms = 5

The embedder is bundled — Brain owns the model, so clients send text, not vectors. The model is cached under the models directory after first download. Change the HNSW parameters deliberately; they trade recall against latency and memory.

Rerank (the one deploy-time capability toggle)

[rerank]
enabled = false

OptionTypeDefault / Env

rerank.enabledbooleandefault: false

The cross-encoder reranker on the read path. This is the single load-gated capability. Enabled ⇒ the model loads at shard spawn or the shard hard-fails. Disabled ⇒ silently skipped, and reads return RRF-only ordering (no error). Toggling it changes result ordering, not write/read correctness — which is why it's the one capability that's safe to disable.

Logging (one knob)

[monitoring.logging]
level  = "info"    # error | warn | info | debug | trace
output = "stdout"
format = "json"    # json for aggregators (Loki / Elastic / CloudWatch); pretty for terminals

[monitoring.tracing]
enabled      = false
endpoint     = ""  # e.g. http://your-collector:4318/v1/traces
sampler      = "ratio"
sample_ratio = 0.01
service_name = "brain-server"

Logging has one level knob. Turn tracing on with BRAIN__MONITORING__TRACING__ENABLED=true and point it at an OTLP collector via BRAIN__MONITORING__TRACING__ENDPOINT.

Workers

Background workers run on every shard. Cadences are in seconds; 0 disables a worker where applicable.

[workers]
decay_interval_sec                 = 3600
consolidation_interval_sec         = 600
hnsw_maintenance_interval_sec      = 1800
idempotency_cleanup_interval_sec   = 3600
slot_reclamation_interval_sec      = 3600
wal_retention_interval_sec         = 600
statistics_update_interval_sec     = 60
snapshot_interval_sec              = 21600

[workers.auto_edge]
enabled              = true
similarity_threshold = 0.85
top_k                = 5

[workers.extractor]
interval_ms                    = 1000
drain_per_cycle                = 32
llm_budget_per_cycle_micro_usd = 50000

OptionTypeDefault / Env

workers.snapshot_interval_secnumberdefault: 21600

How often the shard takes an automatic snapshot (see Backups).

workers.auto_edge.enabledbooleandefault: true

Per-shard worker that derives similarity edges from HNSW knn. Maintenance workers default on; destructive GC workers default off.

workers.extractorsection

The extraction worker is always provisioned — extraction is always-on, so there is no enable flag here, only tuning (drain size, LLM budget per cycle).

Most operators only ever set BRAIN__LLM__API_KEY and maybe BRAIN__STORAGE__SHARD_COUNT. The rest of the defaults are production-sane.

Sample production overrides

# The one mandatory field
BRAIN__LLM__API_KEY=sk-...
BRAIN__LLM__MODEL=gpt-4o-mini

# Throughput
BRAIN__STORAGE__SHARD_COUNT=8

# Observability
BRAIN__MONITORING__LOGGING__FORMAT=json
BRAIN__MONITORING__TRACING__ENABLED=true
BRAIN__MONITORING__TRACING__ENDPOINT=http://otel-collector:4318/v1/traces

Don't bake provider keys into the image or commit them to the TOML file. Inject BRAIN__LLM__API_KEY at boot from your platform's secret store and never persist it to disk.

On this page