Skip to main content

Aragora Configuration Reference

Complete reference for all configuration options. For quick setup, see .env.example.

Quick Start​

# Copy the example config
cp .env.example .env

# Minimum required: at least one AI provider key
echo "ANTHROPIC_API_KEY=sk-ant-..." >> .env

# Start the server
python -m aragora.server.unified_server

Production Checklist​

Before deploying to production, ensure:

  • ARAGORA_ENVIRONMENT=production
  • JWT_SECRET set (min 32 chars): python -c "import secrets; print(secrets.token_urlsafe(32))"
  • ARAGORA_ALLOWED_ORIGINS set to your domain(s)
  • At least one AI provider API key configured
  • DATABASE_URL or SUPABASE_URL for persistence
  • REDIS_URL for multi-instance deployments
  • ARAGORA_CSP_REPORT_ONLY=false to enforce CSP
  • Review rate limiting settings

Verify configuration:

python -m aragora.cli doctor

1. AI Providers​

Primary LLM APIs​

At least one required for debates to function.

VariableRequiredDescription
ANTHROPIC_API_KEYYes*Anthropic Claude API key
OPENAI_API_KEYYes*OpenAI GPT API key
GEMINI_API_KEYYes*Google Gemini API key
XAI_API_KEYYes*xAI Grok API key
MISTRAL_API_KEYYes*Mistral AI API key
OPENROUTER_API_KEYYes*OpenRouter multi-model API (fallback)
DEEPSEEK_API_KEYNoDeepSeek direct API

*At least one required

Local Models​

VariableDefaultDescription
OLLAMA_HOSThttp://localhost:11434Ollama server URL
LM_STUDIO_HOSThttp://localhost:1234LM Studio server URL

Embeddings & Vector Search​

VariableDefaultDescription
EMBEDDING_MODELtext-embedding-3-smallEmbedding model
EMBEDDING_DIMENSIONS1536Vector dimensions
VECTOR_BACKENDmemoryVector store backend
WEAVIATE_URLhttp://localhost:8080Weaviate cluster URL
WEAVIATE_API_KEY-Weaviate Cloud API key
ARAGORA_WEAVIATE_ENABLEDfalseEnable Weaviate

2. Server Configuration​

VariableDefaultDescription
ARAGORA_PORT8080HTTP/WebSocket server port
ARAGORA_BIND_HOST127.0.0.1Server bind address
ARAGORA_ENVIRONMENTdevelopmentEnvironment mode
ARAGORA_DATA_DIR.nomicData directory for databases
ARAGORA_INSTANCE_COUNT1Number of server instances

3. Database & Persistence​

Database Backend​

VariableDefaultDescription
ARAGORA_DB_BACKENDsqliteBackend: sqlite or postgres
DATABASE_URL-PostgreSQL connection string
ARAGORA_POSTGRES_DSN-Legacy alias for DATABASE_URL
ARAGORA_DATABASE_URL-Legacy alias for DATABASE_URL
ARAGORA_SQLITE_PATHaragora.dbSQLite file path
ARAGORA_POLICY_STORE_BACKENDautoPolicy store backend: sqlite or postgres (defaults to ARAGORA_DB_BACKEND)
ARAGORA_AUDIT_STORE_BACKENDautoAudit log backend: sqlite or postgres (defaults to ARAGORA_DB_BACKEND)
ARAGORA_INBOX_STORE_BACKENDautoUnified inbox backend: memory, sqlite, postgres (defaults to ARAGORA_DB_BACKEND)
ARAGORA_REQUIRE_DISTRIBUTEDautoEnforce distributed stores in production (fail closed on SQLite/file)
ARAGORA_STORAGE_MODEautoForce storage mode: postgres, redis, sqlite, file
ARAGORA_EXPLAINABILITY_STORE_BACKENDautoExplainability batch store backend: redis, postgres, sqlite, memory
ARAGORA_EXPLAINABILITY_BATCH_TTL_SECONDS3600Explainability batch retention (seconds)
ARAGORA_EXPLAINABILITY_DB-SQLite path override for explainability batch jobs
ARAGORA_CONTROL_PLANE_POLICY_SOURCEautoControl plane policy source: compliance, inprocess

Production recommendation: keep explainability batch jobs in Redis with TTL. Set ARAGORA_EXPLAINABILITY_STORE_BACKEND=postgres only for long-term retention.

PostgreSQL Connection String Examples:

# Supabase
DATABASE_URL=postgresql://postgres.[ref]:[pass]@aws-0-us-west-1.pooler.supabase.com:6543/postgres

# AWS RDS
DATABASE_URL=postgresql://admin:[email protected]:5432/aragora

# Local
DATABASE_URL=postgresql://user:pass@localhost:5432/aragora

Distributed Store Enforcement:

  • In production, ARAGORA_REQUIRE_DISTRIBUTED=true will fail closed if a store falls back to SQLite or local files.
  • Set ARAGORA_STORAGE_MODE to pin a backend across stores when validating production readiness.
  • ARAGORA_REQUIRE_DISTRIBUTED_STATE is a legacy alias honored when ARAGORA_REQUIRE_DISTRIBUTED is unset.

Connection Pooling (PostgreSQL)​

VariableDefaultDescription
ARAGORA_DB_POOL_SIZE20Connection pool size
ARAGORA_DB_POOL_MAX_OVERFLOW15Max overflow connections
ARAGORA_DB_POOL_TIMEOUT30.0Acquisition timeout (seconds)

Supabase​

VariableDefaultDescription
SUPABASE_URL-Supabase project URL
SUPABASE_KEY-Supabase API key
SUPABASE_SYNC_ENABLEDfalseEnable background sync

4. Redis (Caching & Sessions)​

Required for multi-instance deployments and distributed rate limiting.

Basic Configuration​

VariableDefaultDescription
REDIS_URL-Redis connection URL
ARAGORA_REDIS_URL-Alternative Redis URL
ARAGORA_REDIS_HOSTlocalhostRedis hostname
ARAGORA_REDIS_PORT6379Redis port
ARAGORA_REDIS_PASSWORD-Redis password
ARAGORA_REDIS_DB0Redis database number
ARAGORA_REDIS_MAX_CONNECTIONS50Max connections
ARAGORA_REDIS_SOCKET_TIMEOUT5.0Socket timeout (seconds)
ARAGORA_REDIS_SOCKET_CONNECT_TIMEOUT5.0Connection timeout (seconds)

Redis High-Availability Modes​

Aragora supports three Redis deployment modes for different scale and availability requirements:

VariableDefaultDescription
ARAGORA_REDIS_MODEstandaloneMode: standalone, sentinel, or cluster

Mode auto-detection: If ARAGORA_REDIS_MODE is not set, the mode is auto-detected based on configuration:

  • If ARAGORA_REDIS_SENTINEL_HOSTS is set -> Sentinel mode
  • If ARAGORA_REDIS_CLUSTER_NODES is set -> Cluster mode
  • Otherwise -> Standalone mode

Redis Sentinel (HA Failover)​

Redis Sentinel provides automatic master/replica failover. Recommended for production deployments requiring high availability without data sharding.

VariableDefaultDescription
ARAGORA_REDIS_SENTINEL_HOSTS-Comma-separated sentinel hosts (e.g., sentinel1:26379,sentinel2:26379)
ARAGORA_REDIS_SENTINEL_MASTERmymasterSentinel master name
ARAGORA_REDIS_SENTINEL_PASSWORD-Sentinel authentication password
ARAGORA_REDIS_SENTINEL_SOCKET_TIMEOUT5.0Sentinel socket timeout

Example Sentinel setup:

# Sentinel mode configuration
ARAGORA_REDIS_MODE=sentinel
ARAGORA_REDIS_SENTINEL_HOSTS=sentinel1.example.com:26379,sentinel2.example.com:26379,sentinel3.example.com:26379
ARAGORA_REDIS_SENTINEL_MASTER=mymaster
ARAGORA_REDIS_SENTINEL_PASSWORD=sentinel-secret
ARAGORA_REDIS_PASSWORD=redis-secret

Redis Cluster (Horizontal Scaling)​

Redis Cluster provides data sharding across multiple nodes. Recommended for enterprise deployments requiring both high availability and horizontal scaling.

VariableDefaultDescription
ARAGORA_REDIS_CLUSTER_NODES-Comma-separated cluster nodes (e.g., node1:6379,node2:6379)
ARAGORA_REDIS_CLUSTER_MODEautoCluster mode detection
ARAGORA_REDIS_CLUSTER_READ_FROM_REPLICAStrueEnable read from replicas for scaling
ARAGORA_REDIS_CLUSTER_SKIP_FULL_COVERAGEfalseSkip slot coverage check

Example Cluster setup:

# Cluster mode configuration
ARAGORA_REDIS_MODE=cluster
ARAGORA_REDIS_CLUSTER_NODES=redis1.example.com:6379,redis2.example.com:6379,redis3.example.com:6379
ARAGORA_REDIS_CLUSTER_READ_FROM_REPLICAS=true
ARAGORA_REDIS_PASSWORD=cluster-secret

SSL/TLS Configuration​

VariableDefaultDescription
ARAGORA_REDIS_SSLfalseEnable SSL/TLS connections
ARAGORA_REDIS_SSL_CERT_REQS-SSL certificate requirements
ARAGORA_REDIS_SSL_CA_CERTS-Path to CA certificates

Distributed State (Horizontal Scaling)​

For multi-instance deployments where debate state needs to be shared across servers.

VariableDefaultDescription
ARAGORA_STATE_BACKENDmemoryBackend: memory (single instance) or redis (multi-instance)
ARAGORA_REDIS_URLredis://localhost:6379Redis URL for state storage
ARAGORA_INSTANCE_IDinstance-\{pid\}Unique instance identifier for event deduplication

When to use Redis HA:

DeploymentRecommended ModeUse Case
Development/TestStandaloneSingle instance, local development
Production (small)StandaloneSingle server, moderate load
Production (HA)SentinelMulti-server, automatic failover
EnterpriseClusterHigh scale, data sharding, global distribution

Example multi-instance setup with Sentinel:

# Instance 1
ARAGORA_STATE_BACKEND=redis
ARAGORA_REDIS_MODE=sentinel
ARAGORA_REDIS_SENTINEL_HOSTS=sentinel1:26379,sentinel2:26379,sentinel3:26379
ARAGORA_REDIS_SENTINEL_MASTER=mymaster
ARAGORA_INSTANCE_ID=server-1
ARAGORA_PORT=8081

# Instance 2
ARAGORA_STATE_BACKEND=redis
ARAGORA_REDIS_MODE=sentinel
ARAGORA_REDIS_SENTINEL_HOSTS=sentinel1:26379,sentinel2:26379,sentinel3:26379
ARAGORA_REDIS_SENTINEL_MASTER=mymaster
ARAGORA_INSTANCE_ID=server-2
ARAGORA_PORT=8082

Health Check:

from aragora.storage.redis_ha import check_redis_health

health = check_redis_health()
print(f"Healthy: {health['healthy']}, Mode: {health['mode']}")

5. Authentication & Security​

JWT Configuration​

VariableDefaultDescription
JWT_SECRET-Required in production (min 32 chars)
ARAGORA_JWT_EXPIRY_HOURS24Token expiry
ARAGORA_REFRESH_TOKEN_EXPIRY_DAYS30Refresh token expiry

API Authentication​

VariableDefaultDescription
ARAGORA_API_TOKEN-Simple token auth (dev)
ARAGORA_AUTH_REQUIREDfalseRequire auth for WebSocket

Content Security Policy​

VariableDefaultDescription
ARAGORA_ENABLE_CSPtrueEnable CSP header
ARAGORA_CSP_MODEstandardMode: api, standard, development
ARAGORA_CSP_REPORT_ONLYtrueReport-only mode

CORS​

VariableDefaultDescription
ARAGORA_ALLOWED_ORIGINS-Comma-separated allowed origins
ARAGORA_TRUSTED_PROXIES127.0.0.1,::1,localhostTrusted proxy IPs

6. Rate Limiting​

VariableDefaultDescription
ARAGORA_RATE_LIMIT60Requests per minute
ARAGORA_IP_RATE_LIMIT120Per-IP rate limit
ARAGORA_BURST_MULTIPLIER2.0Burst multiplier
ARAGORA_RATE_LIMIT_FAIL_OPENfalseAllow if Redis down

WebSocket Rate Limiting​

VariableDefaultDescription
ARAGORA_WS_CONN_RATE30Connections per minute
ARAGORA_WS_MAX_PER_IP10Max connections per IP
ARAGORA_WS_MSG_RATE10Messages per second

7. Timeouts​

Request Timeouts​

VariableDefaultDescription
ARAGORA_REQUEST_TIMEOUT30Default request timeout
ARAGORA_MAX_REQUEST_TIMEOUT600Maximum allowed timeout
ARAGORA_SLOW_REQUEST_TIMEOUT120Slow request threshold

Debate Timeouts​

VariableDefaultDescription
ARAGORA_SLOW_DEBATE_THRESHOLD30Slow debate detection (seconds)
ARAGORA_CONTEXT_TIMEOUT150.0Context gathering timeout
ARAGORA_EVIDENCE_TIMEOUT30.0Evidence collection timeout

Debate Concurrency​

VariableDefaultDescription
ARAGORA_MAX_CONCURRENT_PROPOSALS5Max parallel proposal generations
ARAGORA_PROPOSAL_STAGGER_SECONDS0.0Stagger delay between proposals (0=disabled)
ARAGORA_AGENT_TIMEOUT_SECONDS60Per-agent timeout

Note: Proposal generation uses bounded semaphores for true parallelism. Set stagger > 0 for legacy sequential behavior.

8. Observability​

Logging​

VariableDefaultDescription
ARAGORA_LOG_LEVELINFOLog level
ARAGORA_LOG_FORMATjsonFormat: json or text
ARAGORA_LOG_FILE-Log file path (stdout if not set)
ARAGORA_LOG_MAX_BYTES10485760Max log file size
ARAGORA_LOG_BACKUP_COUNT5Number of backups

Prometheus Metrics​

VariableDefaultDescription
METRICS_ENABLEDtrueEnable metrics endpoint
METRICS_PORT9090Metrics server port
ARAGORA_METRICS_TOKEN-Token to protect /metrics

OpenTelemetry​

VariableDefaultDescription
OTEL_ENABLEDfalseEnable tracing
OTEL_EXPORTER_OTLP_ENDPOINThttp://localhost:4317OTLP collector
OTEL_SERVICE_NAMEaragoraService name
OTEL_SAMPLE_RATE1.0Sampling rate (0.0-1.0)

Sentry​

VariableDefaultDescription
SENTRY_DSN-Sentry DSN URL
SENTRY_ENVIRONMENTdevelopmentEnvironment tag
SENTRY_TRACES_SAMPLE_RATE0.1Trace sampling

9. Billing (Stripe)​

VariableDefaultDescription
STRIPE_SECRET_KEY-Stripe secret API key
STRIPE_WEBHOOK_SECRET-Webhook signing secret
STRIPE_PRICE_STARTER-Starter plan price ID
STRIPE_PRICE_PROFESSIONAL-Professional plan price ID
STRIPE_PRICE_ENTERPRISE-Enterprise plan price ID

10. Chat Integrations​

Slack​

VariableDescription
SLACK_BOT_TOKENBot token (xoxb-...)
SLACK_APP_TOKENApp token (xapp-...)
SLACK_SIGNING_SECRETRequest signing secret

Discord​

VariableDescription
DISCORD_BOT_TOKENBot token
DISCORD_APPLICATION_IDApplication ID
DISCORD_PUBLIC_KEYPublic key for verification

Microsoft Teams​

VariableDescription
TEAMS_APP_IDApplication ID
TEAMS_APP_PASSWORDApplication password
TEAMS_TENANT_IDTenant ID

11. Enterprise Integrations​

Snowflake​

VariableDescription
SNOWFLAKE_USERUsername
SNOWFLAKE_PASSWORDPassword
SNOWFLAKE_PRIVATE_KEY_PATHKey-pair auth path
SNOWFLAKE_AUTHENTICATORAuth method

Gmail​

VariableDescription
GMAIL_CLIENT_IDOAuth client ID
GMAIL_CLIENT_SECRETOAuth client secret

12. Text-to-Speech​

VariableDefaultDescription
ARAGORA_TTS_BACKEND-TTS backend selection
ARAGORA_TTS_ORDER-Backend priority order
ARAGORA_ELEVENLABS_API_KEY-ElevenLabs API key
ARAGORA_ELEVENLABS_VOICE_ID-Default voice ID

13. Webhooks​

VariableDefaultDescription
ARAGORA_NOTIFICATION_WEBHOOK-Notification webhook URL
ARAGORA_WEBHOOK_TIMEOUT30.0Delivery timeout
ARAGORA_WEBHOOK_MAX_RETRIES3Max retries
ARAGORA_WEBHOOK_ALLOW_LOCALHOSTfalseAllow localhost targets

Environment-Specific Configurations​

Development​

ARAGORA_ENVIRONMENT=development
ARAGORA_LOG_FORMAT=text
ARAGORA_LOG_LEVEL=DEBUG
ARAGORA_CSP_REPORT_ONLY=true

Production​

ARAGORA_ENVIRONMENT=production
ARAGORA_LOG_FORMAT=json
ARAGORA_LOG_LEVEL=INFO
ARAGORA_CSP_REPORT_ONLY=false
JWT_SECRET=your-32-char-secret-here
ARAGORA_ALLOWED_ORIGINS=https://yourdomain.com
DATABASE_URL=postgresql://...
REDIS_URL=redis://...

Testing​

ARAGORA_ENVIRONMENT=test
TESTING=1
ARAGORA_DB_BACKEND=sqlite
ARAGORA_DATA_DIR=/tmp/aragora-test

Validation​

Run the configuration doctor to validate your setup:

python -m aragora.cli doctor

This checks:

  • Required environment variables
  • Database connectivity
  • AI provider availability
  • Redis connectivity (if configured)
  • SSL certificate validity (if enabled)

See Also​

  • .env.example - Quick-start configuration template
  • .env.starter - Minimal configuration for getting started
  • docs/ENVIRONMENT.md - Legacy environment documentation
  • aragora/config/settings.py - Pydantic settings schema