---
title: "Configuration Guide"
description: "Complete guide to configuring Honcho for development and production"
icon: "gear"
---

Honcho uses a flexible configuration system that supports both TOML files and environment variables. Configuration values are loaded in the following priority order (highest to lowest):

1. Environment variables (always take precedence)
2. `.env` file (for local development)
3. `config.toml` file (base configuration)
4. Default values

## Recommended Configuration Approaches

### Option 1: Environment Variables Only (Production)
- Use environment variables for all configuration
- No config files needed
- Ideal for containerized deployments (Docker, Kubernetes)
- Secrets managed by your deployment platform

### Option 2: config.toml (Development/Simple Deployments)
- Use config.toml for base configuration
- Override sensitive values with environment variables
- Good for development and simple deployments

### Option 3: Hybrid Approach
- Use config.toml for non-sensitive base settings
- Use .env file for sensitive values (API keys, secrets)
- Good for development teams

### Option 4: .env Only (Local Development)
- Use .env file for all configuration
- Simple for local development
- Never commit .env files to version control

## Configuration Methods

### Using config.toml

Copy the example configuration file to get started:

```bash
cp config.toml.example config.toml
```

Then modify the values as needed. The TOML file is organized into sections:

- `[app]` - Application-level settings (log level, host, port, embedding settings)
- `[db]` - Database connection and pool settings
- `[auth]` - Authentication configuration
- `[llm]` - LLM provider API keys and general settings
- `[dialectic]` - Dialectic API configuration (provider, model, search settings)
- `[deriver]` - Background worker settings and theory of mind configuration
- `[summary]` - Session summarization settings
- `[sentry]` - Error tracking and monitoring settings

### Using Environment Variables

All configuration values can be overridden using environment variables. The environment variable names follow this pattern:

- `{SECTION}_{KEY}` for nested settings
- Just `{KEY}` for app-level settings

Examples:

- `DB_CONNECTION_URI` → `[db].CONNECTION_URI`
- `DB_POOL_SIZE`      → `[db].POOL_SIZE`
- `AUTH_JWT_SECRET`   → `[auth].JWT_SECRET`
- `DIALECTIC_MODEL` → `[dialectic].MODEL`
- `LOG_LEVEL` (no section) → `[app].LOG_LEVEL`

### Configuration Priority

When a configuration value is set in multiple places, Honcho uses this priority:

1. **Environment variables** - Always take precedence
2. **.env file** - Loaded for local development
3. **config.toml** - Base configuration
4. **Default values** - Built-in defaults

This allows you to:

- Use `config.toml` for base configuration
- Override specific values with environment variables in production
- Use `.env` files for local development without modifying config.toml

### Example

If you have this in `config.toml`:

```toml
[db]
CONNECTION_URI = "postgresql://localhost/honcho_dev"
POOL_SIZE = 10
```

You can override just the connection URI in production:

```bash
export DB_CONNECTION_URI="postgresql://prod-server/honcho_prod"
```

The application will use the production connection URI while keeping the pool size from config.toml.

## Core Configuration

### Application Settings

**Basic Application Configuration:**
```bash
# Logging and server settings
LOG_LEVEL=INFO  # DEBUG, INFO, WARNING, ERROR
SESSION_PEERS_LIMIT=10
GET_CONTEXT_MAX_TOKENS=100000

# Embedding settings (optional)
EMBED_MESSAGES=false
MAX_EMBEDDING_TOKENS=8192
MAX_EMBEDDING_TOKENS_PER_REQUEST=300000
```

**Environment-specific settings:**
```bash
# Development
LOG_LEVEL=DEBUG
FASTAPI_HOST=127.0.0.1

# Production
LOG_LEVEL=WARNING
FASTAPI_HOST=0.0.0.0
```

### Database Configuration

**Required Database Settings:**
```bash
# PostgreSQL connection string (required)
DB_CONNECTION_URI=postgresql+psycopg://username:password@host:port/database

# Example for local development
DB_CONNECTION_URI=postgresql+psycopg://postgres:postgres@localhost:5432/honcho

# Example for production
DB_CONNECTION_URI=postgresql+psycopg://honcho_user:secure_password@db.example.com:5432/honcho_prod
```

**Database Pool Settings:**
```bash
# Connection pool configuration
DB_SCHEMA=public
DB_POOL_SIZE=10
DB_MAX_OVERFLOW=20
DB_POOL_TIMEOUT=30
DB_POOL_RECYCLE=300
DB_POOL_PRE_PING=true
DB_SQL_DEBUG=false
DB_TRACING=false
```

**Docker Compose for PostgreSQL:**
```yaml
# docker-compose.yml
version: '3.8'
services:
  database:
    image: pgvector/pgvector:pg15
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: honcho
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql

volumes:
  postgres_data:
```

### Authentication Configuration

**JWT Authentication:**
```bash
# Enable/disable authentication
AUTH_USE_AUTH=false  # Set to true for production

# JWT settings (required if AUTH_USE_AUTH is true)
AUTH_JWT_SECRET=your-super-secret-jwt-key
```

**Generate JWT Secret:**
```bash
# Generate a secure JWT secret
python scripts/generate_jwt_secret.py
```

## LLM Provider Configuration

Honcho supports multiple LLM providers for different tasks. API keys are configured in the `[llm]` section, while specific features use their own configuration sections.

### API Keys

All provider API keys use the `LLM_` prefix:

```bash
# Provider API Keys
LLM_ANTHROPIC_API_KEY=your-anthropic-api-key
LLM_OPENAI_API_KEY=your-openai-api-key
LLM_GEMINI_API_KEY=your-gemini-api-key
LLM_GROQ_API_KEY=your-groq-api-key

# OpenAI-compatible endpoints
LLM_OPENAI_COMPATIBLE_API_KEY=your-api-key
LLM_OPENAI_COMPATIBLE_BASE_URL=https://your-openai-compatible-endpoint.com
```

### General LLM Settings

```bash
# Default settings for all LLM calls
LLM_DEFAULT_MAX_TOKENS=2500
```

### Feature-Specific Model Configuration

Different features can use different providers and models:

**Dialectic API:**
```bash
# Main dialectic model (default: Anthropic)
DIALECTIC_PROVIDER=anthropic
DIALECTIC_MODEL=claude-sonnet-4-20250514
DIALECTIC_MAX_OUTPUT_TOKENS=2500
DIALECTIC_THINKING_BUDGET_TOKENS=1024

# Query generation for dialectic (default: Groq)
DIALECTIC_QUERY_GENERATION_PROVIDER=groq
DIALECTIC_QUERY_GENERATION_MODEL=llama-3.1-8b-instant

# Semantic search settings
DIALECTIC_SEMANTIC_SEARCH_TOP_K=10
DIALECTIC_SEMANTIC_SEARCH_MAX_DISTANCE=0.85
```

**Deriver:**
```bash
# Deriver model (default: Google)
DERIVER_PROVIDER=google
DERIVER_MODEL=gemini-2.0-flash-lite

# Worker settings
DERIVER_WORKERS=1
DERIVER_STALE_SESSION_TIMEOUT_MINUTES=5
DERIVER_POLLING_SLEEP_INTERVAL_SECONDS=1.0

# Peer card settings
DERIVER_PEER_CARD_PROVIDER=openai
DERIVER_PEER_CARD_MODEL=gpt-5-nano-2025-08-07
DERIVER_PEER_CARD_MAX_OUTPUT_TOKENS=2000

# Maximum number of observations to store in working representation
# This is applied to both explicit and deductive observations
DERIVER_WORKING_REPRESENTATION_MAX_OBSERVATIONS=100
```

**Summary Generation:**
```bash
# Summary model (default: Google)
SUMMARY_PROVIDER=google
SUMMARY_MODEL=gemini-1.5-flash-latest
SUMMARY_MAX_TOKENS_SHORT=1000
SUMMARY_MAX_TOKENS_LONG=2000
SUMMARY_THINKING_BUDGET_TOKENS=512

# Summary frequency
SUMMARY_MESSAGES_PER_SHORT_SUMMARY=20
SUMMARY_MESSAGES_PER_LONG_SUMMARY=60
```

### Default Provider Usage

By default, Honcho uses:
- **Anthropic** for dialectic API responses
- **Groq** for query generation
- **Google** for deriving theory of mind and summarization
- **OpenAI** for embeddings (if `EMBED_MESSAGES=true`)

You only need to set the API keys for the providers you plan to use.


## Monitoring Configuration

### Sentry Error Tracking

**Sentry Settings:**
```bash
# Enable/disable Sentry
SENTRY_ENABLED=false

# Sentry configuration
SENTRY_DSN=https://your-sentry-dsn@sentry.io/project-id
SENTRY_TRACES_SAMPLE_RATE=0.1
SENTRY_PROFILES_SAMPLE_RATE=0.1
```

## Environment-Specific Examples

### Development Configuration

**config.toml for development:**
```toml
[app]
LOG_LEVEL = "DEBUG"
SESSION_PEERS_LIMIT = 10
EMBED_MESSAGES = false

[db]
CONNECTION_URI = "postgresql+psycopg://postgres:postgres@localhost:5432/honcho_dev"
POOL_SIZE = 5

[auth]
USE_AUTH = false

[dialectic]
PROVIDER = "anthropic"
MODEL = "claude-sonnet-4-20250514"
QUERY_GENERATION_PROVIDER = "groq"
QUERY_GENERATION_MODEL = "llama-3.1-8b-instant"
MAX_OUTPUT_TOKENS = 2500

[summary]
PROVIDER = "google"
MODEL = "gemini-1.5-flash-latest"
MAX_TOKENS_SHORT = 1000
MAX_TOKENS_LONG = 2000

[deriver]
WORKERS = 1

[sentry]
ENABLED = false
```

**Environment variables for development:**
```bash
# .env.development
LOG_LEVEL=DEBUG
DB_CONNECTION_URI=postgresql+psycopg://postgres:postgres@localhost:5432/honcho_dev
AUTH_USE_AUTH=false
ANTHROPIC_API_KEY=your-dev-anthropic-key
```

### Production Configuration

**config.toml for production:**
```toml
[app]
LOG_LEVEL = "WARNING"
SESSION_PEERS_LIMIT = 10
EMBED_MESSAGES = true

[db]
CONNECTION_URI = "postgresql+psycopg://honcho_user:secure_password@prod-db:5432/honcho_prod"
POOL_SIZE = 20
MAX_OVERFLOW = 40

[auth]
USE_AUTH = true

[dialectic]
PROVIDER = "anthropic"
MODEL = "claude-sonnet-4-20250514"
QUERY_GENERATION_PROVIDER = "groq"
QUERY_GENERATION_MODEL = "llama-3.1-8b-instant"
MAX_OUTPUT_TOKENS = 2500

[summary]
PROVIDER = "google"
MODEL = "gemini-1.5-flash-latest"
MAX_TOKENS_SHORT = 1000
MAX_TOKENS_LONG = 2000

[deriver]
WORKERS = 4
PROVIDER = "google"
MODEL = "gemini-2.0-flash-lite"

[sentry]
ENABLED = true
TRACES_SAMPLE_RATE = 0.1
```

**Environment variables for production:**
```bash
# .env.production
LOG_LEVEL=WARNING
DB_CONNECTION_URI=postgresql+psycopg://honcho_user:secure_password@prod-db:5432/honcho_prod
AUTH_USE_AUTH=true
AUTH_JWT_SECRET=your-super-secret-jwt-key
ANTHROPIC_API_KEY=your-prod-anthropic-key
GEMINI_API_KEY=your-prod-gemini-key
SENTRY_DSN=https://your-sentry-dsn@sentry.io/project-id
```

## Migration Management

**Running Database Migrations:**
```bash
# Check current migration status
uv run alembic current

# Upgrade to latest
uv run alembic upgrade head

# Downgrade to specific revision
uv run alembic downgrade revision_id

# Create new migration
uv run alembic revision --autogenerate -m "Description of changes"
```

## Troubleshooting

**Common Configuration Issues:**

1. **Database Connection Errors**
   - Ensure `DB_CONNECTION_URI` uses `postgresql+psycopg://` prefix
   - Verify database is running and accessible
   - Check pgvector extension is installed

2. **Authentication Issues**
   - Set `AUTH_USE_AUTH=true` for production
   - Generate and set `AUTH_JWT_SECRET` if authentication is enabled
   - Use `python scripts/generate_jwt_secret.py` to create a secure secret

3. **LLM Provider Issues**
   - Verify API keys are set correctly
   - Check model names match provider specifications
   - Ensure provider is enabled in configuration

4. **Deriver Issues**
   - Increase `DERIVER_WORKERS` for better performance
   - Check `DERIVER_STALE_SESSION_TIMEOUT_MINUTES` for session cleanup
   - Monitor background processing logs

This configuration guide covers all the settings available in Honcho. Always use environment-specific configuration files and never commit sensitive values like API keys or JWT secrets to version control.