--- last_validated: 2026-03-16 --- # Deployment Guide This guide covers deploying Agent Brain in various environments, from local development to production deployments. ## Table of Contents - [Local Development](#local-development) - [Production Considerations](#production-considerations) - [Docker Deployment](#docker-deployment) - [Resource Requirements](#resource-requirements) - [Monitoring and Observability](#monitoring-and-observability) - [Security Considerations](#security-considerations) - [Troubleshooting](#troubleshooting) --- ## Local Development ### Quick Start ```bash # 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 ```bash # 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 ```bash # 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: ```bash # 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`: ```ini [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: ```bash sudo systemctl enable agent-brain sudo systemctl start agent-brain sudo systemctl status agent-brain ``` --- ## Docker Deployment ### Dockerfile ```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 ```yaml 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 ```bash # 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 ```bash # 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: ```bash # 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: ```yaml # 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 # 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` ```bash # .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 ```bash # 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: ```python 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**: ```bash # 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 ```bash # 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**: ```bash # Reset and re-index agent-brain reset --yes agent-brain index /path/to/documents ``` #### API Key Errors **Symptoms**: `AuthenticationError` or `Invalid API key`. **Solutions**: ```bash # 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: ```bash 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: ```bash # 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**: ```bash #!/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 ```bash # 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: ```bash # Reset all indexes agent-brain reset --yes # Re-index from source documents agent-brain index /path/to/documents --include-code ``` --- ## Next Steps - [API Reference](API_REFERENCE.md) - Complete API documentation - [Configuration Reference](CONFIGURATION.md) - All configuration options - [Architecture Overview](ARCHITECTURE.md) - System design