DocsUse

Configuration

Every setting is an environment variable starting with BBM_ATLAS_, also read from a .env file, with credentials readable from files.

How settings are read

Each setting is an environment variable named BBM_ATLAS_ plus the setting in capitals: api_port is BBM_ATLAS_API_PORT.
A .env file in the directory BBM-Atlas starts in is read too. A variable already in the environment wins over the file.
A list (API_KEYS, INDEX_ROOTS, MCP_ALLOWED_HOSTS, FORWARDED_ALLOW_IPS) is a JSON array, a comma-separated string, or a single value.
Settings are read when a process starts: restart BBM-Atlas after changing one.

.env

BBM_ATLAS_API_KEYS=["a-long-random-key"]BBM_ATLAS_INDEX_ROOTS=/srv/repos,/home/dev/workBBM_ATLAS_LOG_LEVEL=INFO

Credentials from files

Any credential can be read from a file instead, which keeps it out of the process environment: set BBM_ATLAS_<NAME>_FILE to its path. This is how Docker and Kubernetes secrets are mounted.

terminal

BBM_ATLAS_API_KEYS_FILE=/run/secrets/api_keysBBM_ATLAS_POSTGRES_DSN_FILE=/run/secrets/postgres_dsn

It works for API_KEYS, ADMIN_API_KEYS, POSTGRES_DSN, NEO4J_PASSWORD, QDRANT_API_KEY and REDIS_URL. The file's trailing newline is ignored, setting both forms of one credential is refused, and an unreadable file stops start-up with its path and the reason. The Enterprise Edition reads its licence key, OIDC client secret and SAML certificate from files too (BBM_ATLAS_EE_LICENSE_KEY_FILE, BBM_ATLAS_EE_OIDC_CLIENT_SECRET_FILE, BBM_ATLAS_EE_SAML_IDP_CERTIFICATE_FILE); for those, the file wins when both are set.

Server

Variable	Default	What it does
`BBM_ATLAS_API_HOST`	`127.0.0.1`	Where `bbm-atlas serve` listens. Set `0.0.0.0` only to expose it, with keys set (Security)
`BBM_ATLAS_API_PORT`	`8000`	Its port
`BBM_ATLAS_ENVIRONMENT`	`development`	`development`, `testing`, `staging` or `production`. Production refuses to start without API keys
`BBM_ATLAS_CONSOLE_ENABLED`	`true`	The web console at `/console/`
`BBM_ATLAS_MCP_HTTP_ENABLED`	`true`	MCP over HTTP at `/mcp`
`BBM_ATLAS_MCP_ALLOWED_HOSTS`	empty	The host names clients use for `/mcp`, when it is exposed beyond this machine
`BBM_ATLAS_FORWARDED_ALLOW_IPS`	`127.0.0.1`	The reverse proxies trusted to report the client's address and scheme
`BBM_ATLAS_DATA_DIR`	your user data folder	Where BBM-Atlas keeps its own files - logs, the local store - when their paths are relative

Access and limits

Variable	Default	What it does
`BBM_ATLAS_API_KEYS`	empty	The keys a request must carry (as `X-API-Key` or a bearer token). Empty: no key needed
`BBM_ATLAS_ADMIN_API_KEYS`	empty	Keys allowed to change feature flags. Empty: any key may
`BBM_ATLAS_INDEX_ROOTS`	empty	The directories repositories may be indexed from. Empty: anywhere the server can read
`BBM_ATLAS_RATE_LIMIT_ENABLED`	`false`	A budget of requests per minute for each caller
`BBM_ATLAS_RATE_LIMIT_REQUESTS_PER_MINUTE`	`120`	The budget: per API key, per signed-in account, else per address
`BBM_ATLAS_RATE_LIMIT_BACKEND`	`memory`	`memory` (each process counts alone) or `redis` (one budget across replicas)
`BBM_ATLAS_MAX_REQUEST_BODY_BYTES`	`10485760`	The largest request body accepted (10 MiB)

Storage

Variable	Default	What it does
`BBM_ATLAS_STORAGE_BACKEND`	`local` with `serve`	`local` (one SQLite file, one process), `memory` (nothing kept) or `all` (Postgres, Neo4j, Qdrant and Redis)
`BBM_ATLAS_LOCAL_STORE_PATH`	`store/bbm-atlas.sqlite3`	The local store's file, under the data folder when relative
`BBM_ATLAS_MEMORY_FACTS_BACKEND`	`local` with `serve`	Where remembered facts live: `memory`, `local` or `redis`
`BBM_ATLAS_POSTGRES_DSN`	a local database	Repository metadata, memory and chunks
`BBM_ATLAS_NEO4J_URI`, `_USER`, `_PASSWORD`	`bolt://localhost:7687`	The knowledge graph. The password is required with `all`
`BBM_ATLAS_QDRANT_URL`, `_API_KEY`	`http://localhost:6333`	Vectors for semantic search
`BBM_ATLAS_REDIS_URL`	`redis://localhost:6379/0`	The cache, and shared rate limits and facts

Models

Variable	Default	What it does
`BBM_ATLAS_EMBEDDING_PROVIDER`	`hash`	`sentence_transformers` loads a real embedding model (the `embeddings` extra)
`BBM_ATLAS_EMBEDDING_MODEL_NAME`	`BAAI/bge-m3`	Which model
`BBM_ATLAS_LLM_PROVIDER`	`template`	The agents' language model: `template` (deterministic, no model), `llamacpp` (in-process, the `llm` extra) or `llamacpp_server`
`BBM_ATLAS_LLM_MODEL_PATH`	a GGUF file	The model `llamacpp` loads
`BBM_ATLAS_LLM_DEVICE`, `BBM_ATLAS_EMBEDDING_DEVICE`	`cpu`	`gpu` offloads to a GPU build

Logging and tracing

Variable	Default	What it does
`BBM_ATLAS_LOG_LEVEL`	`INFO`	`DEBUG`, `INFO`, `WARNING` or `ERROR`
`BBM_ATLAS_LOG_FORMAT`	`json`	`json` lines, or `console` for people
`BBM_ATLAS_LOG_TO_FILE`	`true`	Also write log files under the data folder
`BBM_ATLAS_OTEL_ENABLED`	`false`	OpenTelemetry traces (the `otel` extra), sent where the standard `OTEL_EXPORTER_OTLP_ENDPOINT` says

The Enterprise Edition's settings start with BBM_ATLAS_EE_; see Licence and set-up.