Skip to content

Deployment Guide

Jump to bottom
Rick Hightower edited this page Feb 1, 2026 · 1 revision

Deployment Guide

This guide covers deploying Agent Brain in various environments, from local development to production deployments.

Table of Contents

Local Development

Quick Start

# 1. Install packages
pip install agent-brain-rag agent-brain-cli

# 2. Set API keys
export OPENAI_API_KEY="sk-proj-..."
export ANTHROPIC_API_KEY="sk-ant-..."  # Optional

# 3. Initialize project
cd /path/to/your/project
agent-brain init

# 4. Start server
agent-brain start --daemon

# 5. Index documents
agent-brain index ./docs --include-code

# 6. Verify
agent-brain status

Development Server Options

# Start with auto-reload for development
agent-brain start --reload

# Start with debug logging
DEBUG=true agent-brain start

# Start on specific port
agent-brain start --port 8080

# Start in foreground (see logs)
agent-brain start

Virtual Environment Setup

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# or
.venv\Scripts\activate     # Windows

# Install packages
pip install agent-brain-rag agent-brain-cli

# Verify installation
agent-brain --version
agent-brain-serve --version

Production Considerations

Checklist

Before deploying to production:

  • API keys stored securely (environment variables or secrets manager)
  • Storage paths point to persistent volumes
  • Appropriate resource limits configured
  • Health endpoints monitored
  • Backup strategy for indexed data
  • Security: bind to localhost or use reverse proxy

Environment Configuration

Create a production .env file:

# Required
OPENAI_API_KEY=sk-proj-...

# Optional (for GraphRAG)
ANTHROPIC_API_KEY=sk-ant-...

# Server Configuration
API_HOST=127.0.0.1
API_PORT=8000
DEBUG=false

# Embedding
EMBEDDING_MODEL=text-embedding-3-large
EMBEDDING_DIMENSIONS=3072

# Storage - point to persistent volumes
CHROMA_PERSIST_DIR=/data/agent-brain/vectors
BM25_INDEX_PATH=/data/agent-brain/bm25

# GraphRAG (optional)
ENABLE_GRAPH_INDEX=true
GRAPH_STORE_TYPE=kuzu
GRAPH_INDEX_PATH=/data/agent-brain/graph

Persistent Storage

Agent Brain stores data in three locations:

Storage Purpose Size Estimate
ChromaDB Vector embeddings ~1GB per 100K chunks
BM25 Index Keyword index ~100MB per 100K chunks
Graph Index Knowledge graph ~200MB per 50K entities

Recommendation: Use SSD storage for best performance.

systemd Service

Create /etc/systemd/system/agent-brain.service:

[Unit]
Description=Agent Brain RAG Server
After=network.target

[Service]
Type=simple
User=agent-brain
Group=agent-brain
WorkingDirectory=/opt/agent-brain
Environment=OPENAI_API_KEY=sk-proj-...
Environment=CHROMA_PERSIST_DIR=/data/agent-brain/vectors
Environment=BM25_INDEX_PATH=/data/agent-brain/bm25
ExecStart=/opt/agent-brain/venv/bin/agent-brain-serve --host 127.0.0.1 --port 8000
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable agent-brain
sudo systemctl start agent-brain
sudo systemctl status agent-brain

Docker Deployment

Dockerfile

FROM python:3.11-slim

WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

# Install Python packages
RUN pip install --no-cache-dir \
    agent-brain-rag \
    agent-brain-cli

# Create data directories
RUN mkdir -p /data/vectors /data/bm25 /data/graph

# Set environment defaults
ENV API_HOST=0.0.0.0
ENV API_PORT=8000
ENV CHROMA_PERSIST_DIR=/data/vectors
ENV BM25_INDEX_PATH=/data/bm25
ENV GRAPH_INDEX_PATH=/data/graph

# Expose port
EXPOSE 8000

# Health check
HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
    CMD curl -f http://localhost:8000/health || exit 1

# Run server
CMD ["agent-brain-serve", "--host", "0.0.0.0", "--port", "8000"]

docker-compose.yml

version: '3.8'

services:
  agent-brain:
    build: .
    ports:
      - "8000:8000"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - ENABLE_GRAPH_INDEX=true
      - GRAPH_STORE_TYPE=simple
    volumes:
      - agent-brain-data:/data
      - ./docs:/docs:ro  # Mount documents to index
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  agent-brain-data:

Running with Docker

# Build image
docker build -t agent-brain .

# Run container
docker run -d \
  --name agent-brain \
  -p 8000:8000 \
  -e OPENAI_API_KEY="sk-proj-..." \
  -v agent-brain-data:/data \
  -v /path/to/docs:/docs:ro \
  agent-brain

# Index documents
docker exec agent-brain agent-brain index /docs

# Check status
docker exec agent-brain agent-brain status

Docker Compose Deployment

# Set environment
export OPENAI_API_KEY="sk-proj-..."
export ANTHROPIC_API_KEY="sk-ant-..."

# Start services
docker-compose up -d

# Index documents
docker-compose exec agent-brain agent-brain index /docs

# View logs
docker-compose logs -f agent-brain

Resource Requirements

Minimum Requirements

Resource Minimum Recommended
CPU 2 cores 4 cores
RAM 2GB 8GB
Storage 10GB 50GB SSD
Python 3.10+ 3.11+

Memory Sizing

Memory usage scales with:

  1. Number of chunks: ~1KB per chunk in memory during indexing
  2. Vector dimensions: 3072 dimensions = ~12KB per vector
  3. Graph size: ~1MB per 1000 entities

Guidelines:

Project Size Documents Chunks RAM Needed
Small < 1,000 < 10,000 2GB
Medium 1,000-10,000 10,000-100,000 4-8GB
Large 10,000+ 100,000+ 8-16GB

CPU Considerations

  • Indexing: CPU-intensive during embedding generation
  • Queries: Mostly I/O-bound, scales with concurrent requests
  • GraphRAG: LLM extraction is API-bound, not CPU-bound

Monitoring and Observability

Health Endpoints

Endpoint Purpose
GET /health Basic health check (for load balancers)
GET /health/status Detailed status (indexing progress, counts)

Prometheus Metrics (Future)

Agent Brain will support Prometheus metrics in a future release. For now, use log-based monitoring.

Logging

Agent Brain logs to stdout/stderr with configurable levels:

# Enable debug logging
DEBUG=true agent-brain-serve

# Log format
# 2024-01-15 10:30:00 [INFO] agent_brain_server.api.main: Starting Agent Brain RAG server...

Log Aggregation

For production, use a log aggregator:

# docker-compose with logging
services:
  agent-brain:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

Alerting Suggestions

Set up alerts for:

  • Health endpoint returns non-healthy status
  • Query latency exceeds threshold (e.g., > 5 seconds)
  • Indexing fails repeatedly
  • Disk usage exceeds 80%

Security Considerations

Network Security

By default, Agent Brain binds to 127.0.0.1, accessible only from localhost.

For network access, use a reverse proxy:

# nginx configuration
server {
    listen 443 ssl;
    server_name agent-brain.example.com;

    ssl_certificate /etc/ssl/certs/agent-brain.crt;
    ssl_certificate_key /etc/ssl/private/agent-brain.key;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;

        # Basic auth
        auth_basic "Agent Brain";
        auth_basic_user_file /etc/nginx/.htpasswd;
    }
}

API Key Security

Never commit API keys to version control.

Options for secure storage:

  1. Environment variables: Set in systemd or Docker
  2. Secrets manager: AWS Secrets Manager, HashiCorp Vault
  3. .env files: Keep out of version control with .gitignore 
# .gitignore
.env
.env.local
.env.production

Data Security

  • Indexed content is stored locally in unencrypted format
  • Consider disk encryption for sensitive codebases
  • Limit file permissions on storage directories
# Secure storage directory
chmod 700 /data/agent-brain
chown agent-brain:agent-brain /data/agent-brain

CORS Configuration

The default CORS configuration allows all origins:

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],  # Configure for production!
)

For production, restrict to specific origins.

Troubleshooting

Common Issues

Server Won't Start

Symptoms: Address already in use or server exits immediately.

Solutions:

# Check what's using the port
lsof -i :8000

# Kill existing process
kill -9 $(lsof -t -i :8000)

# Or use a different port
agent-brain start --port 8080

Out of Memory During Indexing

Symptoms: Process killed or OOM errors during indexing.

Solutions:

  1. Index in smaller batches
  2. Increase available memory
  3. Reduce chunk overlap
  4. Disable LLM summaries
# Index specific folders instead of entire project
agent-brain index ./docs
agent-brain index ./src/module1
agent-brain index ./src/module2

Slow Query Performance

Symptoms: Queries take > 5 seconds.

Causes and Solutions:

Cause Solution
Large result sets Reduce top_k
Complex graph queries Reduce traversal_depth
Cold start First query after restart is slow
Slow disk Use SSD storage

ChromaDB Corruption

Symptoms: Errors about corrupted database or missing files.

Solution:

# Reset and re-index
agent-brain reset --yes
agent-brain index /path/to/documents

API Key Errors

Symptoms: AuthenticationError or Invalid API key.

Solutions:

# Verify key is set
echo $OPENAI_API_KEY

# Check key format (should start with sk-proj-)
# Regenerate key if needed at platform.openai.com

Debug Mode

Enable debug mode for detailed logging:

DEBUG=true agent-brain start

This enables:

  • Detailed request/response logging
  • Stack traces for errors
  • Auto-reload on code changes

Getting Help

  1. Check logs: docker-compose logs agent-brain
  2. Verify health: curl http://localhost:8000/health
  3. Check status: agent-brain status
  4. GitHub Issues: Report bugs with logs and reproduction steps

Backup and Recovery

Backup Strategy

Back up these directories regularly:

# Backup locations
CHROMA_PERSIST_DIR=/data/agent-brain/vectors
BM25_INDEX_PATH=/data/agent-brain/bm25
GRAPH_INDEX_PATH=/data/agent-brain/graph

Backup script:

#!/bin/bash
DATE=$(date +%Y%m%d)
BACKUP_DIR=/backups/agent-brain

mkdir -p $BACKUP_DIR

# Stop server for consistent backup
agent-brain stop

# Create backup
tar -czf $BACKUP_DIR/agent-brain-$DATE.tar.gz \
    /data/agent-brain/vectors \
    /data/agent-brain/bm25 \
    /data/agent-brain/graph

# Restart server
agent-brain start --daemon

# Cleanup old backups (keep 7 days)
find $BACKUP_DIR -name "*.tar.gz" -mtime +7 -delete

Recovery

# Stop server
agent-brain stop

# Restore from backup
tar -xzf /backups/agent-brain/agent-brain-20240115.tar.gz -C /

# Restart server
agent-brain start --daemon

Re-indexing

If indexes are corrupted beyond recovery:

# Reset all indexes
agent-brain reset --yes

# Re-index from source documents
agent-brain index /path/to/documents --include-code

Next Steps

Navigation

Getting Started

Architecture

Design Docs

Search Guides

Provider Config

Deployment

API

Plugin Commands

Search

Server

Setup

Plugin Agents

Features

Planning

Clone this wiki locally