Brainby arc-labs/docs
Brain on GitHubDashboard →
Self-host overview
Self-host

Self-host overview

Run Brain on your own infrastructure — one Docker image, one process, no external database. All you provide is an LLM provider key.

What you're running

One process: brain-server. It embeds every subsystem it needs.

PROCESS01 STAGESPER-SHARD STATE (IN-PROCESS)06 STAGESEXTERNAL01 STAGESbrain-server (one binary)mmap arena (vectors)WALredb (metadata)HNSW (in RAM)tantivy (lexical)BGE-small + rerankerLLM provider API
One process, one data volume. Each shard owns its arena, WAL, metadata store, indexes, and models. The only outbound dependency is the LLM provider API.

Brain is thread-per-core. The process splits into shards — one shard pins one core, runs its own executor (Glommio, io_uring), and owns the full per-shard state below. Sharding is the parallelism; you scale by adding shards and machines, not by scaling a separate database tier.

What's inside the box

Every shard owns, in-process, from byte zero:

vectors

mmap arena

A memory-mapped file of fixed-size slots holds the embedding vectors. Per-slot CRC; slot-version stamped into every MemoryId.

durability

Write-ahead log

Group-commit WAL. No write is acknowledged until its record is durably fsynced — WAL-before-acknowledge is a hard invariant.

metadata

redb B-tree

An embedded redb store holds all metadata — memory records, entities, statements, relations, predicates, idempotency, audit. This is Brain's metadata database; it is not a separate process.

vector search

HNSW indexes

Three in-RAM HNSW indexes (memory, entity, statement) via hnsw_rs. Rebuilt/maintained by a background worker; they live in process memory, not on a remote service.

lexical

tantivy

Full-text (BM25-style) indexes over memory and statement text. This is the lexical retriever in the read pipeline.

models

Bundled embedder + reranker

Brain owns the embedding model — BGE-small via candle, 384-dim — so clients send text, not vectors. A cross-encoder reranker is bundled for the read path. Models are cached on the data/model volume after first download.

What you must provide

  1. An LLM provider API key — mandatory at boot. Write-time HyPE (hypothetical-question generation) and the extraction pipeline are always-on, and the write path is built on them. brain-server refuses to start without a valid [llm] api_key (env BRAIN__LLM__API_KEY). This is an external LLM call, not a datastore — set one key, and the provider is derived from the model id (claude* → Anthropic, otherwise OpenAI). See Configuration.
  2. A persistent data volume. Everything Brain stores — arena, WAL, redb, indexes — lives under one data directory. Back that volume up and you can restore Brain. See Backups.
  3. CPU cores and RAM. One shard pins one core. The bundled models (embedder, reranker, classifier) load into RAM at boot, so size the host with headroom.

What you do NOT need

There is no external datastore to stand up, secure, back up, or scale:

  • No Postgres / no pgvector. Vectors live in the in-process arena + HNSW; metadata lives in redb.
  • No separate vector database. HNSW is in-process.
  • No Neo4j / graph store. The typed entity/statement/relation graph lives in redb.
  • No Redis / cache tier. Caches are in-process and per-shard.
  • No SQLite, no "embedded mode." There is only one shape: the single brain-server process. It is already embedded — the storage engine ships inside the binary.

Start with a single container and one shard. Grow shard_count for throughput on a bigger box before you reach for multiple machines. There is no database bottleneck to diagnose first — the storage engine scales with the process.

What's in the box

ArtifactPurpose
brain:latest Docker imageThe brain-server binary + its baked-in default config (/etc/brain/config.toml)
brain-serverThe one process: wire data plane, HTTP health/metrics, admin HTTP surface

This repository ships the server only — there is no first-party CLI, SDK, or client bundled in the image. Clients speak the wire protocol (or the HTTP edge); operators administer via the admin HTTP surface. SDKs live in sibling packages.

Pin the image to a specific version tag in production — never a floating latest. Brain is pre-1.0 and makes breaking changes in place until v1.0.

Where to go next

→ quickstart
Docker setup

The real docker run for the brain image — ports, the persistent volume, the mandatory LLM key.

→ config
Configuration

The TOML config file and every BRAIN__SECTION__FIELD env override.

→ ops
Scaling

Sharding, thread-per-core, and horizontal scale — with no DB tier to scale.

→ ops
Backups

Snapshot and restore of the data volume — arena + WAL + redb.

See also
ArchitectureHow the shard runtime, storage engine, and read/write pipelines fit together.SecurityAuth at the edge, namespace/agent isolation, network posture.ConfigurationEvery config section and env override.

Was this page helpful?

Manual rate-limit backoff

Catch a 429 / 503, honor Retry-After, and retry — taking over from the SDK's built-in auto-retry when you need to.

Docker setup

Run the single Brain image — ports, the persistent data volume, the mandatory LLM key, and the io_uring runtime flags.

On this page

What you're runningWhat's inside the boxWhat you must provideWhat you do NOT needWhat's in the boxWhere to go next
Suggest an editOpen in Playground