Configuration

Overview

All xbrain services are configured via environment variables defined in infrastructure/.env. This file is gitignored — it is never committed to the repository. An .env.example is provided with safe defaults and CHANGE_ME placeholders for all secrets.

bashcp infrastructure/.env.example infrastructure/.env
# Edit .env and replace all CHANGE_ME values with your actual credentials

Core Database

PostgreSQL is the primary relational store for memory-api, events, audit logs, and team/user data. These variables are required on all phases.

memory-api

memory-api is the central memory service — all read/write operations from LibreChat, Open WebUI, and agents go through it. Several variables are phase-gated (Phase 3+, Phase 5).

GitHub App Phase 12

The xbrain GitHub App handles all sign-in flows (web + Chrome extension) and all server-to-server calls to api.github.com on behalf of installed orgs. These six vars replace the legacy GITHUB_API_PAT + OAuth App env.

Brain Monitor & Superadmin Phase 11

Phase 11 adds the universal Brain Monitor (per-team feed) and the /account/admin/ superadmin dashboard. Storage metrics rely on MinIO env vars already set in earlier phases; only ADMIN_USER_SUBS is new.

LibreChat

LibreChat connects to AI model providers via API keys. At least one model key is required for the chat interface to function.

Bridge & Pipeline

The LibreChat bridge and Open WebUI pipeline forward conversations to memory-api. BRIDGE_SHARED_SECRET must match the value set in memory-api.

agent-runtime

agent-runtime hosts LangGraph agents and connects to the MCP gateway for tool access.

Langfuse (Phase 2)

Langfuse provides LLM observability — tracing, cost tracking, and prompt management. Keys are generated from the Langfuse UI after first boot.

Graphiti (Phase 5)

Graphiti performs temporal fact extraction from conversations and builds an episodic knowledge graph. memory-api calls it asynchronously and fails soft if the service is unavailable.

Generating Secrets

Several variables require cryptographically random values. Use these commands to generate appropriate secrets for each:

bash — secret generation# Generate BRIDGE_SHARED_SECRET (32-byte hex)
openssl rand -hex 32

# Generate MEILI_MASTER_KEY (32-byte hex)
openssl rand -hex 32

# Generate PIPELINE_API_KEY (32-byte hex)
openssl rand -hex 32

# Generate NEO4J_PASSWORD (base64, 16-byte)
openssl rand -base64 16

# Generate OAUTH_CREDENTIALS_ENCRYPTION_KEY (Fernet key, required for Drive sync)
python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Complete .env.example

This is the full infrastructure/.env.example as shipped in the repository. Copy it to infrastructure/.env and replace every CHANGE_ME value before starting any services.

infrastructure/.env.example# ================================================================
# xbrain — Environment Variable Reference
# Copy to infrastructure/.env and fill in your values.
# NEVER commit infrastructure/.env to git.
# ================================================================

# === Core Database ===
POSTGRES_USER=xbrain
POSTGRES_PASSWORD=CHANGE_ME
POSTGRES_DB=xbrain
DATABASE_URL=postgres+asyncpg://xbrain:CHANGE_ME@postgres:5432/xbrain

# === Qdrant (Vector Store) ===
QDRANT_URL=http://qdrant:6333
QDRANT_API_KEY=

# === Google OAuth (Required for SSO) ===
GOOGLE_CLIENT_ID=CHANGE_ME.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=CHANGE_ME

# === Security ===
BRIDGE_SHARED_SECRET=CHANGE_ME_32HEX
JWT_ALGORITHM=HS256
ADMIN_USER_SUBS=

# === AI Models ===
ANTHROPIC_API_KEY=sk-ant-CHANGE_ME
OPENAI_API_KEY=sk-CHANGE_ME
XAI_API_KEY=

# === LibreChat ===
MEILI_MASTER_KEY=CHANGE_ME_32HEX
LIBRECHAT_MONGO_URI=mongodb://mongo:27017/librechat

# === Bridge & Pipeline ===
MEMORY_API_URL=http://memory-api:8000
BRIDGE_DEFAULT_TEAM_SCOPE=default
BRIDGE_BACKFILL_FROM=startup
PIPELINE_API_KEY=CHANGE_ME_32HEX
PIPELINE_DEFAULT_TEAM_SCOPE=default
AGENT_RUNTIME_URL=http://agent-runtime:9100

# === agent-runtime ===
MCP_GATEWAY_URL=http://mcp-gateway:8080
MCP_TOOL_CACHE_TTL_SECS=300

# === Langfuse (Phase 2 — generate from Langfuse UI after first boot) ===
LANGFUSE_PUBLIC_KEY=
LANGFUSE_SECRET_KEY=

# === Neo4j (Phase 3) ===
NEO4J_URI=bolt://neo4j:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=CHANGE_ME

# === Drive Sync Encryption (Phase 3) ===
OAUTH_CREDENTIALS_ENCRYPTION_KEY=

# === External URLs ===
MEMORY_API_EXTERNAL_URL=https://api.yourdomain.com

# === Logging ===
LOG_LEVEL=INFO

# === GitHub Org display (legacy, optional post-Phase 12) ===
GITHUB_ORG=your-github-org
# GITHUB_API_PAT=     # REMOVED in Phase 12 — DO NOT set

# === Graphiti (Phase 5) ===
GRAPHITI_SERVICE_URL=http://graphiti-service:8300
SEMAPHORE_LIMIT=3

# === Brain Monitor + Superadmin (Phase 11) ===
# Comma-separated subs; empty value disables /v1/admin/brain/* entirely.
ADMIN_USER_SUBS=github:mrboups
# MINIO_URL etc. — already required from Phase 2 onwards.

# === GitHub App (Phase 12) ===
GITHUB_APP_ID=3743573
GITHUB_APP_SLUG=xbrain
GITHUB_APP_CLIENT_ID=Iv23liVnZvIN0Lo6isof
GITHUB_APP_CLIENT_SECRET=CHANGE_ME
GITHUB_APP_PRIVATE_KEY_B64=CHANGE_ME_SINGLE_LINE_BASE64
GITHUB_APP_WEBHOOK_SECRET=CHANGE_ME_32HEX

Next Steps

• Deployment guide — Step-by-step instructions for Phase 1 through Phase 5, including VM sizing and Docker setup.
• Memory System — How the 7-field tagging contract is applied to every data point stored by memory-api.
• Drive Sync — Configuring OAuth credentials for Google Drive folder synchronisation.
• GitHub Auth — Setting up GitHub Org membership verification for team access control.