Skip to main content

Environment Variable Reference

Last Updated: 2026-01-27

Complete reference for all environment variables used by Aragora.

Quick Start​

Copy .env.example to .env and fill in your values:

cp .env.example .env

Production Required Variables​

These variables MUST be set in production (ARAGORA_ENV=production). The application will fail loudly if they are missing, preventing silent fallback to localhost defaults.

VariableDescriptionExample
GOOGLE_OAUTH_CLIENT_IDGoogle OAuth client ID1234567890-abc.apps.googleusercontent.com
GOOGLE_OAUTH_CLIENT_SECRETGoogle OAuth client secretyour-client-secret
GOOGLE_OAUTH_REDIRECT_URIOAuth callback URLhttps://api.aragora.ai/api/auth/oauth/google/callback
OAUTH_SUCCESS_URLPost-login redirecthttps://aragora.ai/auth/success
OAUTH_ERROR_URLAuth error pagehttps://aragora.ai/auth/error
OAUTH_ALLOWED_REDIRECT_HOSTSComma-separated allowed hostsaragora.ai,api.aragora.ai
NEXT_PUBLIC_API_URLFrontend API base URLhttps://api.aragora.ai
NEXT_PUBLIC_WS_URLFrontend WebSocket URLwss://api.aragora.ai

Warning Behavior:

  • In development mode, missing URLs will trigger console warnings but fall back to localhost
  • In production mode (ARAGORA_ENV=production), missing OAuth URLs will cause startup failures
  • Frontend components will log [Aragora] NEXT_PUBLIC_API_URL not set if using localhost fallback

Example Production Configuration:

# OAuth (required in production)
GOOGLE_OAUTH_CLIENT_ID=1234567890-abc.apps.googleusercontent.com
GOOGLE_OAUTH_CLIENT_SECRET=your-client-secret
GOOGLE_OAUTH_REDIRECT_URI=https://api.aragora.ai/api/auth/oauth/google/callback
OAUTH_SUCCESS_URL=https://aragora.ai/auth/success
OAUTH_ERROR_URL=https://aragora.ai/auth/error
OAUTH_ALLOWED_REDIRECT_HOSTS=aragora.ai,api.aragora.ai,www.aragora.ai

# Frontend URLs (required for deployed frontend)
NEXT_PUBLIC_API_URL=https://api.aragora.ai
NEXT_PUBLIC_WS_URL=wss://api.aragora.ai

OAuth Runtime Controls​

VariableRequiredDescriptionDefault
OAUTH_STATE_TTL_SECONDSOptionalOAuth state TTL (seconds)600
OAUTH_MAX_STATESOptionalMax in-memory OAuth states10000

AI Provider Keys​

At least one AI provider key is required.

VariableRequiredDescriptionDefault
ANTHROPIC_API_KEYOne requiredAnthropic Claude API key-
OPENAI_API_KEYOne requiredOpenAI API key-
GEMINI_API_KEYOptionalGoogle Gemini API key-
GOOGLE_API_KEYOptionalAlias for GEMINI_API_KEY-
XAI_API_KEYOptionalGrok/XAI API key-
GROK_API_KEYOptionalAlias for XAI_API_KEY-
MISTRAL_API_KEYOptionalMistral AI API key (Large, Codestral)-
OPENROUTER_API_KEYOptionalOpenRouter for multi-model access-
DEEPSEEK_API_KEYOptionalDeepSeek CLI key (for deepseek-cli)-
ARAGORA_OPENROUTER_FALLBACK_ENABLEDOptionalEnable OpenRouter fallback for supported providersfalse

Note: Never commit your .env file. It's gitignored for security.

OpenRouter Models​

OpenRouter provides access to multiple models through a single API:

  • DeepSeek (V3, R1 Reasoner)
  • Llama (Meta's open models)
  • Mistral (also available via direct MISTRAL_API_KEY)
  • Qwen (Alibaba's code and reasoning models)
  • Yi (01.AI's balanced models)

See OpenRouter docs for available models.

Mistral Direct API​

For best performance with Mistral models, use the direct API:

  • mistral-api agent uses MISTRAL_API_KEY directly
  • codestral agent for code-specialized tasks
  • Falls back to OpenRouter if direct API fails

Web Research (Experimental)​

Enable external web research during debates (requires aragora[research]):

VariableRequiredDescriptionDefault
TAVILY_API_KEYOptionalTavily search API key for web research-

Ollama (Local Models)​

Run AI models locally with Ollama.

VariableRequiredDescriptionDefault
OLLAMA_HOSTOptionalOllama server URLhttp://localhost:11434
OLLAMA_MODELOptionalDefault model namellama2

Usage:

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Pull a model
ollama pull llama2

# Set in .env (optional - defaults work for local)
OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=llama2

LM Studio (Local Models)​

Run local LLMs through LM Studio's OpenAI-compatible server.

VariableRequiredDescriptionDefault
LM_STUDIO_HOSTOptionalLM Studio base URLhttp://localhost:1234

Usage:

# Start LM Studio server with a model loaded
# Default endpoint: http://localhost:1234/v1
LM_STUDIO_HOST=http://localhost:1234

Supermemory (Cross-Session Memory)​

Optional integration with Supermemory for cross-session learning and context injection. Supermemory provides external persistent memory that enables debates to learn from past sessions across projects.

VariableRequiredDescriptionDefault
SUPERMEMORY_API_KEYRequired for featureSupermemory API key (sm_... format)-
SUPERMEMORY_BASE_URLOptionalBase URL overrideSDK default
SUPERMEMORY_TIMEOUTOptionalRequest timeout (seconds)30
SUPERMEMORY_SYNC_THRESHOLDOptionalMin importance to sync externally (0.0-1.0)0.7
SUPERMEMORY_PRIVACY_FILTEROptionalEnable privacy filtering before synctrue
SUPERMEMORY_CONTAINER_TAGOptionalDefault container tag for memoriesaragora

Features:

  • Context Injection: Load relevant context from past sessions at debate start
  • Outcome Persistence: Sync debate conclusions to external memory
  • Semantic Search: Query historical memories across projects
  • Privacy Filter: Automatically redacts API keys, tokens, passwords before sync

Usage:

# Enable Supermemory integration
SUPERMEMORY_API_KEY=sm_xxxxxxxxxxxxx

# Optional: adjust sync threshold (default: 0.7)
# Only debates with >= 0.7 confidence are synced externally
SUPERMEMORY_SYNC_THRESHOLD=0.8

# Optional: disable privacy filter (not recommended)
SUPERMEMORY_PRIVACY_FILTER=true

# Optional: custom container for memories
SUPERMEMORY_CONTAINER_TAG=aragora_production

ArenaConfig Options:

from aragora.debate.arena_config import ArenaConfig

config = (
    ArenaConfig.builder()
    .with_supermemory(
        enable_supermemory=True,
        supermemory_enable_km_adapter=True,  # Force-enable KM adapter in coordinator
        supermemory_inject_on_start=True,
        supermemory_sync_on_conclusion=True,
    )
    .build()
)

Note: Supermemory is opt-in and disabled by default. Set enable_supermemory=True in ArenaConfig to activate. Use supermemory_enable_km_adapter=True to force-enable the Supermemory KM adapter in the bidirectional coordinator (requires SUPERMEMORY_API_KEY).

Memory Capture (Tool Usage)​

Optional tool-level memory capture for gateway tool/capability usage events. Disabled by default; enable only if you want tool usage logged into the FAST memory tier for retrieval and auditing.

VariableRequiredDescriptionDefault
ARAGORA_MEMORY_CAPTURE_ENABLEDOptionalEnable tool usage capturefalse
ARAGORA_MEMORY_CAPTURE_TOOLSOptionalAllowlist of tool names (comma-separated)-
ARAGORA_MEMORY_SKIP_TOOLSOptionalDenylist of tool names (comma-separated)-
ARAGORA_MEMORY_CAPTURE_CASE_SENSITIVEOptionalTreat tool names as case-sensitivefalse
ARAGORA_MEMORY_CAPTURE_MAX_PER_MINUTEOptionalMax captured events per minute120
ARAGORA_MEMORY_CAPTURE_TIEROptionalMemory tier for tool entriesfast
ARAGORA_MEMORY_CAPTURE_IMPORTANCEOptionalImportance score for captured entries0.4
ARAGORA_MEMORY_CAPTURE_MAX_DETAIL_CHARSOptionalMax detail chars to store800

Claude-Mem (Optional Local Memory Source)​

Optional integration with a local claude-mem worker API for read-only memory search. This is an external dependency and not bundled with Aragora.

VariableRequiredDescriptionDefault
ARAGORA_CLAUDE_MEM_BASE_URLOptionalclaude-mem worker base URLhttp://localhost:37777
ARAGORA_CLAUDE_MEM_TIMEOUTOptionalRequest timeout (seconds)10
ARAGORA_CLAUDE_MEM_PROJECTOptionalDefault project filter-

Persistence (Supabase)​

Optional but recommended for production.

VariableRequiredDescriptionDefault
SUPABASE_URLOptionalSupabase project URL-
SUPABASE_KEYOptionalSupabase service key-

Enables:

  • Historical debate storage
  • Cross-session learning
  • Live dashboard at aragora.ai

Pluggable Storage Backends​

Configure storage backends for channel integrations, tokens, workflows, and federation. Most stores support sqlite and postgres, with optional redis for multi-instance workloads and memory for development.

Integration Store​

Persists channel/integration configurations (Slack, Teams, Discord, Gmail).

VariableRequiredDescriptionDefault
ARAGORA_INTEGRATION_STORE_BACKENDOptionalBackend: memory, sqlite, postgres, redissqlite

Gmail Token Store​

Persists Gmail OAuth tokens and sync job state.

VariableRequiredDescriptionDefault
ARAGORA_GMAIL_STORE_BACKENDOptionalBackend: memory, sqlite, postgres, redissqlite

Unified Inbox Store​

Persists unified inbox accounts, messages, and triage results.

VariableRequiredDescriptionDefault
ARAGORA_INBOX_STORE_BACKENDOptionalBackend: memory, sqlite, postgressqlite

Finding Workflow Store​

Persists audit finding workflow state, assignments, and history.

VariableRequiredDescriptionDefault
ARAGORA_WORKFLOW_STORE_BACKENDOptionalBackend: memory, sqlite, postgres, redissqlite

Federation Registry Store​

Persists federated region configurations for multi-region knowledge sync.

VariableRequiredDescriptionDefault
ARAGORA_FEDERATION_STORE_BACKENDOptionalBackend: memory, sqlite, postgres, redissqlite

Explainability Batch Store​

Persists batch explainability job state.

VariableRequiredDescriptionDefault
ARAGORA_EXPLAINABILITY_STORE_BACKENDOptionalBackend: redis, postgres, sqlite, memoryAuto (prefers Redis)
ARAGORA_EXPLAINABILITY_BATCH_TTL_SECONDSOptionalBatch job retention (seconds)3600
ARAGORA_EXPLAINABILITY_DBOptionalSQLite path override-

Production default: Redis with TTL. Use PostgreSQL only when long-term retention or audit requirements apply.

Backend Selection:

  • memory - Fast but not persistent; use for testing only
  • sqlite - Default; persists to ARAGORA_DATA_DIR/<store>.db
  • postgres - Production-grade persistence (recommended for multi-instance)
  • redis - Multi-instance deployments with TTL-based job retention

Example:

# Use Redis for multi-instance deployment
ARAGORA_INTEGRATION_STORE_BACKEND=redis
ARAGORA_GMAIL_STORE_BACKEND=redis
ARAGORA_WORKFLOW_STORE_BACKEND=redis
ARAGORA_FEDERATION_STORE_BACKEND=redis
ARAGORA_EXPLAINABILITY_STORE_BACKEND=redis
ARAGORA_REDIS_URL=redis://localhost:6379/0

Database Connection (PostgreSQL/SQLite)​

Use DATABASE_URL for managed Postgres, or set backend-specific settings for local control.

VariableRequiredDescriptionDefault
DATABASE_URLOptionalPostgres connection string (primary)-
ARAGORA_DATABASE_URLOptionalLegacy alias for DATABASE_URL-
ARAGORA_DB_BACKENDOptionalBackend: sqlite, postgres, postgresqlAuto-detect*
ARAGORA_DB_MODEOptionalDatabase layout: legacy or consolidatedlegacy
ARAGORA_DB_TIMEOUTOptionalConnection timeout (seconds)30
ARAGORA_DB_POOL_SIZEOptionalConnection pool size10
ARAGORA_DB_POOL_MAX_OVERFLOWOptionalExtra pool connections5
ARAGORA_DB_POOL_OVERFLOWOptionalLegacy alias for overflow (settings)-
ARAGORA_DB_POOL_TIMEOUTOptionalPool wait timeout (seconds)30
ARAGORA_SQLITE_PATHOptionalSQLite path for the DB backendaragora.db
ARAGORA_SQLITE_POOL_SIZEOptionalSQLite pool size (storage backend)10
ARAGORA_PG_HOSTOptionalPostgres hostlocalhost
ARAGORA_PG_PORTOptionalPostgres port5432
ARAGORA_PG_DATABASEOptionalPostgres database namearagora
ARAGORA_PG_USEROptionalPostgres useraragora
ARAGORA_PG_PASSWORDOptionalPostgres password-
ARAGORA_PG_SSL_MODEOptionalPostgres SSL moderequire
ARAGORA_POSTGRESQL_POOL_SIZEOptionalPostgres pool size (storage backend)5
ARAGORA_POSTGRESQL_POOL_MAX_OVERFLOWOptionalPostgres overflow (storage backend)10
ARAGORA_POLICY_STORE_BACKENDOptionalPolicy store backend: sqlite, postgres, postgresqlUses ARAGORA_DB_BACKEND
ARAGORA_AUDIT_STORE_BACKENDOptionalAudit log backend: sqlite, postgres, postgresqlUses ARAGORA_DB_BACKEND

Control Plane Policy Sync​

VariableRequiredDescriptionDefault
ARAGORA_CONTROL_PLANE_POLICY_SOURCEOptionalPolicy source: compliance, inprocessAuto (compliance in production)
ARAGORA_REQUIRE_DISTRIBUTEDOptionalFail closed when stores fall back to local (prod default)auto
ARAGORA_STORAGE_MODEOptionalForce storage mode: postgres, redis, sqlite, fileauto

Control Plane Watchdog​

Three-tier monitoring system for agent health and SLA compliance. See WATCHDOG.md for architecture details.

VariableRequiredDescriptionDefault
CP_ENABLE_WATCHDOGOptionalEnable the three-tier watchdog systemtrue
CP_WATCHDOG_CHECK_INTERVALOptionalTier check interval (seconds)5
CP_WATCHDOG_HEARTBEAT_TIMEOUTOptionalAgent heartbeat timeout (seconds)30
CP_WATCHDOG_AUTO_ESCALATEOptionalAuto-escalate issues to higher tierstrue
CP_WATCHDOG_ESCALATION_THRESHOLDOptionalIssues before escalating3
CP_WATCHDOG_MEMORY_WARNING_MBOptionalMemory usage warning threshold (MB)1024
CP_WATCHDOG_MEMORY_CRITICAL_MBOptionalMemory usage critical threshold (MB)2048
CP_WATCHDOG_LATENCY_WARNING_MSOptionalLatency warning threshold (ms)5000
CP_WATCHDOG_LATENCY_CRITICAL_MSOptionalLatency critical threshold (ms)15000
CP_WATCHDOG_ERROR_RATE_WARNINGOptionalError rate warning threshold (0.0-1.0)0.1
CP_WATCHDOG_ERROR_RATE_CRITICALOptionalError rate critical threshold (0.0-1.0)0.3
CP_WATCHDOG_SLA_AVAILABILITY_PCTOptionalSLA availability target (percent)99.0
CP_WATCHDOG_SLA_RESPONSE_TIME_MSOptionalSLA response time target (ms)10000

Example Configuration:

# Production: strict monitoring
CP_ENABLE_WATCHDOG=true
CP_WATCHDOG_CHECK_INTERVAL=2
CP_WATCHDOG_HEARTBEAT_TIMEOUT=10
CP_WATCHDOG_AUTO_ESCALATE=true
CP_WATCHDOG_SLA_AVAILABILITY_PCT=99.9

# Development: relaxed monitoring
CP_ENABLE_WATCHDOG=true
CP_WATCHDOG_CHECK_INTERVAL=30
CP_WATCHDOG_HEARTBEAT_TIMEOUT=120
CP_WATCHDOG_AUTO_ESCALATE=false

Skills System​

Skills provide specialized capabilities to agents during debates. See SKILLS.md for usage.

VariableRequiredDescriptionDefault
ARAGORA_SKILLS_ENABLEDOptionalEnable the skills systemtrue
ARAGORA_SKILLS_RATE_LIMITOptionalSkills API rate limit (req/min)30
ARAGORA_SKILLS_TIMEOUTOptionalDefault skill invocation timeout (seconds)30
ARAGORA_SKILLS_MAX_TIMEOUTOptionalMaximum allowed skill timeout (seconds)60
ARAGORA_MARKETPLACE_DBOptionalSQLite path for the skills marketplace:memory:
GOOGLE_SEARCH_API_KEYOptionalGoogle Custom Search API key-
GOOGLE_SEARCH_CXOptionalGoogle Custom Search engine ID-

Notes:

  • TAVILY_API_KEY (documented in Web Research section) is used by web search skills
  • GOOGLE_SEARCH_API_KEY + GOOGLE_SEARCH_CX enable Google search skills
  • Skills can define their own API key requirements

*Auto-detect Behavior:

  • If DATABASE_URL or ARAGORA_POSTGRES_DSN is set → uses PostgreSQL
  • Otherwise → uses SQLite for local development
  • Set ARAGORA_DB_BACKEND explicitly to override auto-detection
  • Store-specific backends (policy/audit) inherit ARAGORA_DB_BACKEND unless overridden
  • ARAGORA_REQUIRE_DISTRIBUTED=true enforces distributed stores in production
  • ARAGORA_REQUIRE_DISTRIBUTED_STATE is a legacy alias honored when ARAGORA_REQUIRE_DISTRIBUTED is unset

Production Setup:

# Set PostgreSQL connection string (auto-enables PostgreSQL backend)
DATABASE_URL=postgresql://user:password@host:5432/aragora

# Or use Supabase PostgreSQL
DATABASE_URL=postgresql://postgres:[password]@[project].supabase.co:5432/postgres

# Initialize database tables (choose one method)

# Method 1: Direct store initialization (development)
python scripts/init_postgres_db.py

# Method 2: Alembic migrations (production recommended)
python scripts/init_postgres_db.py --alembic
# Or run Alembic directly:
alembic upgrade head

# Verify tables exist
python scripts/init_postgres_db.py --verify

Migration Management with Alembic:

# Check current migration status
alembic current

# Upgrade to latest schema
alembic upgrade head

# Downgrade one revision
alembic downgrade -1

# Generate new migration (after schema changes)
alembic revision --autogenerate -m "description"

Note: ARAGORA_DB_MODE defaults to legacy in the legacy config, while aragora.persistence.db_config defaults to consolidated if unset. Set it explicitly to avoid ambiguity. The storage backend also honors the ARAGORA_SQLITE_POOL_SIZE / ARAGORA_POSTGRESQL_* pool settings; set them explicitly if you need consistent pooling across subsystems.

Server Configuration​

VariableRequiredDescriptionDefault
ARAGORA_API_URLOptionalAPI base URL for CLI/SDK clientshttp://localhost:8080
ARAGORA_ENVRecommendeddevelopment or productiondevelopment
ARAGORA_ENVIRONMENTOptionalAlias used by billing/authdevelopment
ARAGORA_API_TOKENOptionalEnable token authDisabled
ARAGORA_TOKEN_TTLOptionalToken lifetime (seconds)3600
ARAGORA_WS_MAX_MESSAGE_SIZEOptionalMax WebSocket message size65536
ARAGORA_WS_HEARTBEATOptionalWebSocket heartbeat interval (seconds)30
ARAGORA_DEFAULT_HOSTOptionalFallback host for link generationlocalhost:8080
ARAGORA_NOTIFICATION_WORKEROptionalEnable notification worker (0 to disable)1
ARAGORA_NOTIFICATION_CONCURRENCYOptionalMax concurrent notification deliveries20

Debate Defaults​

VariableRequiredDescriptionDefault
ARAGORA_DEFAULT_ROUNDSOptionalDefault debate rounds9
ARAGORA_MAX_ROUNDSOptionalMax debate rounds12
ARAGORA_DEFAULT_CONSENSUSOptionalConsensus modejudge
ARAGORA_DEBATE_TIMEOUTOptionalDebate timeout (seconds)600
ARAGORA_AGENT_TIMEOUTOptionalPer-agent timeout (seconds)240

Agent Defaults​

VariableRequiredDescriptionDefault
ARAGORA_DEFAULT_AGENTSOptionalDefault agent list when none specifiedgrok,anthropic-api,openai-api,deepseek,mistral,gemini,qwen,kimi
ARAGORA_STREAMING_AGENTSOptionalAgents allowed for streaming responsesgrok,anthropic-api,openai-api,mistral

Streaming Controls​

VariableRequiredDescriptionDefault
ARAGORA_STREAM_BUFFER_SIZEOptionalMax SSE buffer size (bytes)10485760
ARAGORA_STREAM_CHUNK_TIMEOUTOptionalTimeout between stream chunks (seconds)180

WebSocket & Audience Limits​

VariableRequiredDescriptionDefault
ARAGORA_TRUSTED_PROXIESOptionalComma-separated proxy IPs for client IP resolution127.0.0.1,::1,localhost
ARAGORA_WS_CONN_RATEOptionalWS connections per IP per minute30
ARAGORA_WS_MAX_PER_IPOptionalMax concurrent WS connections per IP10
ARAGORA_WS_MSG_RATEOptionalWS messages per second per connection10
ARAGORA_WS_MSG_BURSTOptionalWS message burst size20
ARAGORA_AUDIENCE_INBOX_MAX_SIZEOptionalAudience inbox queue size1000
ARAGORA_MAX_EVENT_QUEUE_SIZEOptionalEvent queue size (server)10000

Reserved / Not Yet Wired​

These variables exist in the settings schema but are not currently wired into runtime behavior.

VariableDescriptionDefaultStatus
ARAGORA_MAX_CONTEXT_CHARSMax context length for truncation (chars)100000Planned
ARAGORA_MAX_MESSAGE_CHARSMax message length for truncation (chars)50000Planned
ARAGORA_LOCAL_FALLBACK_ENABLEDEnable local LLM fallback in provider chainsfalsePlanned
ARAGORA_LOCAL_FALLBACK_PRIORITYPrefer local LLMs over OpenRouterfalsePlanned

Note: aragora serve runs HTTP on port 8080 and WebSocket on port 8765 by default. The WebSocket server accepts / or /ws. For single-port deployments, embed AiohttpUnifiedServer (advanced).

Legacy/Deployment Host & Port​

VariableRequiredDescriptionDefault
ARAGORA_HOSTOptionalLegacy bind host used by deployment templates0.0.0.0
ARAGORA_PORTOptionalLegacy HTTP port used by deployment templates8080

These are not read by the CLI server directly; prefer aragora serve --api-port/--ws-port in local dev.

Environment Mode​

Set ARAGORA_ENVIRONMENT=production for production deployments. This enables:

  • Strict JWT secret validation (required, minimum 32 characters)
  • Disabled unsafe JWT fallbacks
  • Blocked format-only API key validation
  • Stricter security defaults

Data Directory​

VariableRequiredDescriptionDefault
ARAGORA_DATA_DIRRecommendedDirectory for all runtime data (databases, etc.).nomic

All databases are stored under this directory:

  • agent_elo.db - ELO rankings
  • continuum.db - Memory storage
  • consensus_memory.db - Consensus records
  • token_blacklist.db - Revoked JWT tokens
  • And others...

Related directories:

  • ARAGORA_NOMIC_DIR - Legacy alias used by some migration tooling (defaults to .nomic)
  • ARAGORA_STORAGE_DIR - Non-DB runtime artifacts (plugins, reviews, modes) default to .aragora

Production recommended: /var/lib/aragora or ~/.aragora for ARAGORA_DATA_DIR

Use aragora.config.resolve_db_path() to keep legacy SQLite files under ARAGORA_DATA_DIR. For consolidated mapping, use aragora.persistence.db_config.get_db_path().

Cleanup (repo root artifacts)​

If you ran Aragora in the repo root, stray .db files may land there. Move them under ARAGORA_DATA_DIR with:

python scripts/cleanup_runtime_artifacts.py --apply

For a DB-only migration with tracked-file safeguards, preview first:

python scripts/migrate_runtime_dbs.py --dry-run

Receipt Retention​

VariableRequiredDescriptionDefault
ARAGORA_RECEIPT_RETENTION_DAYSOptionalHow long to keep decision receipts2555 (~7 years)
ARAGORA_RECEIPT_CLEANUP_INTERVAL_HOURSOptionalHow often to run receipt cleanup24

Decision receipts are cryptographic audit trails for debates. They're automatically cleaned up by a background scheduler.

Compliance note: The default 7-year retention aligns with financial audit requirements. Adjust based on your regulatory requirements.

CORS Configuration​

VariableRequiredDescriptionDefault
ARAGORA_ALLOWED_ORIGINSOptionalComma-separated allowed originsSee below

Default origins:

http://localhost:3000,http://localhost:8080,
http://127.0.0.1:3000,http://127.0.0.1:8080,
https://aragora.ai,https://www.aragora.ai,
https://api.aragora.ai

Example:

ARAGORA_ALLOWED_ORIGINS=https://myapp.com,https://staging.myapp.com

Webhook Integration​

VariableRequiredDescriptionDefault
ARAGORA_WEBHOOKSOptionalJSON array of webhook configs-
ARAGORA_WEBHOOKS_CONFIGOptionalPath to JSON config file-
ARAGORA_WEBHOOK_QUEUE_SIZEOptionalMax queued events1000
ARAGORA_WEBHOOK_ALLOW_LOCALHOSTOptionalAllow localhost webhook targets (dev only)false
ARAGORA_WEBHOOK_WORKERSOptionalMax concurrent deliveries10
ARAGORA_WEBHOOK_MAX_RETRIESOptionalDelivery retry attempts3
ARAGORA_WEBHOOK_RETRY_DELAYOptionalInitial retry delay (seconds)1.0
ARAGORA_WEBHOOK_MAX_RETRY_DELAYOptionalMax retry delay (seconds)60.0
ARAGORA_WEBHOOK_TIMEOUTOptionalRequest timeout (seconds)30.0

ARAGORA_WEBHOOKS and ARAGORA_WEBHOOKS_CONFIG accept a JSON array of configs with: name, url, optional secret, optional event_types, and optional loop_ids.

Slack Integration (Server)​

Configure Slack slash commands and outbound notifications.

VariableRequiredDescriptionDefault
SLACK_SIGNING_SECRETOptionalVerify Slack request signatures-
SLACK_BOT_TOKENOptionalBot token for Slack API calls-
SLACK_WEBHOOK_URLOptionalOutbound Slack webhook URL-

Rate Limiting​

VariableRequiredDescriptionDefault
ARAGORA_RATE_LIMITOptionalRequests per minute per token60
ARAGORA_IP_RATE_LIMITOptionalRequests per minute per IP120
ARAGORA_BURST_MULTIPLIEROptionalBurst multiplier for short spikes2.0
ARAGORA_REDIS_URLOptionalRedis URL for distributed rate limitsredis://localhost:6379/0
REDIS_URLOptionalLegacy Redis URL used by queues/oauth/token revocationredis://localhost:6379
ARAGORA_REDIS_KEY_PREFIXOptionalRedis key prefixaragora:ratelimit:
ARAGORA_REDIS_TTLOptionalRedis TTL for limiter keys (seconds)120
ARAGORA_REDIS_MAX_CONNECTIONSOptionalRedis connection pool max size50
ARAGORA_REDIS_SOCKET_TIMEOUTOptionalRedis socket timeout (seconds)5.0
ARAGORA_RATE_LIMIT_FAIL_OPENOptionalAllow requests if Redis is down (true/false)false
ARAGORA_REDIS_FAILURE_THRESHOLDOptionalFailures before Redis limiter disables (count)3

Redis High-Availability (HA) Configuration​

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

  • Standalone: Single Redis instance (development/testing)
  • Sentinel: Redis Sentinel for automatic failover (production HA)
  • Cluster: Redis Cluster for horizontal scaling (enterprise)

Core Redis HA Settings​

VariableRequiredDescriptionDefault
ARAGORA_REDIS_MODEOptionalRedis mode: standalone, sentinel, clusterAuto-detect
ARAGORA_REDIS_URLOptionalRedis URL for standalone moderedis://localhost:6379/0
REDIS_URLOptionalLegacy Redis URL (fallback)redis://localhost:6379
ARAGORA_REDIS_HOSTOptionalRedis host for standalone modelocalhost
ARAGORA_REDIS_PORTOptionalRedis port for standalone mode6379
ARAGORA_REDIS_PASSWORDOptionalRedis authentication password-
ARAGORA_REDIS_DBOptionalRedis database number0

Redis Sentinel Configuration​

Redis Sentinel provides automatic failover for high availability.

VariableRequiredDescriptionDefault
ARAGORA_REDIS_SENTINEL_HOSTSFor SentinelComma-separated sentinel hosts (e.g., sentinel1:26379,sentinel2:26379,sentinel3:26379)-
ARAGORA_REDIS_SENTINEL_MASTEROptionalSentinel master namemymaster
ARAGORA_REDIS_SENTINEL_PASSWORDOptionalSentinel authentication password-

Example Sentinel Configuration:

# 3-node Redis Sentinel setup
ARAGORA_REDIS_MODE=sentinel
ARAGORA_REDIS_SENTINEL_HOSTS=sentinel1:26379,sentinel2:26379,sentinel3:26379
ARAGORA_REDIS_SENTINEL_MASTER=mymaster
ARAGORA_REDIS_PASSWORD=your-redis-password
ARAGORA_REDIS_SENTINEL_PASSWORD=your-sentinel-password

Redis Cluster Configuration​

Redis Cluster provides horizontal scaling with automatic sharding.

VariableRequiredDescriptionDefault
ARAGORA_REDIS_CLUSTER_NODESFor ClusterComma-separated cluster nodes (e.g., redis1:6379,redis2:6379,redis3:6379)-
ARAGORA_REDIS_CLUSTER_READ_FROM_REPLICASOptionalEnable read from replicastrue
ARAGORA_REDIS_CLUSTER_SKIP_FULL_COVERAGEOptionalSkip slot coverage checkfalse

Example Cluster Configuration:

# 3-node Redis Cluster
ARAGORA_REDIS_MODE=cluster
ARAGORA_REDIS_CLUSTER_NODES=redis-node1:6379,redis-node2:6379,redis-node3:6379
ARAGORA_REDIS_CLUSTER_READ_FROM_REPLICAS=true
ARAGORA_REDIS_PASSWORD=your-cluster-password

Common Connection Settings​

These settings apply to all Redis modes.

VariableRequiredDescriptionDefault
ARAGORA_REDIS_SOCKET_TIMEOUTOptionalSocket timeout (seconds)5.0
ARAGORA_REDIS_SOCKET_CONNECT_TIMEOUTOptionalConnection timeout (seconds)5.0
ARAGORA_REDIS_MAX_CONNECTIONSOptionalMax connections in pool50
ARAGORA_REDIS_RETRY_ON_TIMEOUTOptionalRetry on timeouttrue
ARAGORA_REDIS_HEALTH_CHECK_INTERVALOptionalHealth check interval (seconds)30
ARAGORA_REDIS_DECODE_RESPONSESOptionalDecode responses to stringstrue

Redis SSL/TLS Configuration​

VariableRequiredDescriptionDefault
ARAGORA_REDIS_SSLOptionalEnable SSL/TLSfalse
ARAGORA_REDIS_SSL_CERT_REQSOptionalSSL certificate requirements-
ARAGORA_REDIS_SSL_CA_CERTSOptionalPath to CA certificates-

Auto-Detection Behavior​

When ARAGORA_REDIS_MODE is not set:

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

Features​

  • Auto-detection: Automatically detects deployment mode from configuration
  • Connection pooling: Manages connections with health monitoring
  • Graceful failover: Automatic reconnection on node failures (Sentinel/Cluster)
  • Read scaling: Distributes reads across replicas when enabled (Cluster)
  • Hash tag support: Use \{tag\} in keys for slot affinity (e.g., {user:123}:session)
  • SSL/TLS: Secure connections for production deployments

Production Recommendations​

For Sentinel (recommended for most production deployments):

# Minimum 3 sentinel nodes for quorum
ARAGORA_REDIS_SENTINEL_HOSTS=sentinel1:26379,sentinel2:26379,sentinel3:26379
ARAGORA_REDIS_SENTINEL_MASTER=mymaster
ARAGORA_REDIS_PASSWORD=your-strong-password
ARAGORA_REDIS_SSL=true

For Cluster (recommended for high-throughput/large datasets):

# Minimum 3 master nodes with replicas
ARAGORA_REDIS_CLUSTER_NODES=redis1:6379,redis2:6379,redis3:6379
ARAGORA_REDIS_CLUSTER_READ_FROM_REPLICAS=true
ARAGORA_REDIS_PASSWORD=your-strong-password
ARAGORA_REDIS_SSL=true

Request Timeout Middleware​

Controls HTTP request timeouts to prevent hanging requests and cascading failures.

VariableRequiredDescriptionDefault
ARAGORA_REQUEST_TIMEOUTOptionalDefault request timeout (seconds)30
ARAGORA_SLOW_REQUEST_TIMEOUTOptionalTimeout for slow endpoints like debates, broadcasts (seconds)60
ARAGORA_MAX_REQUEST_TIMEOUTOptionalMaximum allowed timeout (seconds)300
ARAGORA_TIMEOUT_WORKERSOptionalThread pool size for sync timeout operations4

Slow Endpoint Patterns (automatically use ARAGORA_SLOW_REQUEST_TIMEOUT):

  • /api/debates/ - Debate orchestration
  • /api/broadcast/ - Audio/video generation
  • /api/evidence/ - Evidence collection
  • /api/gauntlet/ - Comprehensive testing

Per-endpoint Overrides:

from aragora.server.middleware.timeout import configure_timeout

configure_timeout(
    endpoint_overrides={
        "/api/debates/run": 120.0,  # 2 minutes for debate runs
        "/api/broadcast/generate": 180.0,  # 3 minutes for video generation
    }
)

Billing & Authentication​

JWT authentication and Stripe integration for paid tiers.

JWT Configuration​

VariableRequiredDescriptionDefault
ARAGORA_JWT_SECRETRequired (prod)Secret key for JWT signing (min 32 chars)-
ARAGORA_JWT_SECRET_PREVIOUSOptionalPrevious secret for rotation-
ARAGORA_JWT_SECRET_ROTATED_ATOptionalUnix timestamp of rotation-
ARAGORA_JWT_ROTATION_GRACE_HOURSOptionalGrace period for previous secret24
ARAGORA_JWT_EXPIRY_HOURSOptionalAccess token expiry (max 168h/7d)24
ARAGORA_REFRESH_TOKEN_EXPIRY_DAYSOptionalRefresh token expiry (max 90d)30
ARAGORA_ALLOW_FORMAT_ONLY_API_KEYSOptionalAllow API key format-only validation (dev only)0

Security Notes:

  • In production (ARAGORA_ENVIRONMENT=production), ARAGORA_JWT_SECRET is required and must be at least 32 characters.
  • Generate a secure secret: python -c "import secrets; print(secrets.token_urlsafe(32))"
  • In other environments, set ARAGORA_JWT_SECRET if you use auth endpoints (missing secrets raise config errors).
  • ARAGORA_JWT_SECRET_PREVIOUS is only honored if ARAGORA_JWT_SECRET_ROTATED_AT is set.
  • Set ARAGORA_JWT_ROTATION_GRACE_HOURS to control the previous-secret window.
  • ARAGORA_ALLOW_FORMAT_ONLY_API_KEYS is blocked in production regardless of setting.

Token Blacklist Configuration​

VariableRequiredDescriptionDefault
ARAGORA_BLACKLIST_BACKENDOptionalBackend type: memory, sqlite, redissqlite
ARAGORA_REDIS_URLFor redisRedis connection URLredis://localhost:6379/0
  • memory: Fast but not persistent; use for development only
  • sqlite: Default; persists to ARAGORA_DATA_DIR/token_blacklist.db
  • redis: Use for multi-instance deployments (requires redis package)

Stripe Integration​

VariableRequiredDescriptionDefault
STRIPE_SECRET_KEYFor billingStripe API secret key-
STRIPE_WEBHOOK_SECRETFor billingWebhook signing secret-
STRIPE_PRICE_STARTERFor billingPrice ID for Starter tier-
STRIPE_PRICE_PROFESSIONALFor billingPrice ID for Professional tier-
STRIPE_PRICE_ENTERPRISEFor billingPrice ID for Enterprise tier-

See BILLING.md for subscription tiers and usage tracking.

Billing Notifications​

VariableRequiredDescriptionDefault
ARAGORA_SMTP_HOSTOptionalSMTP server host-
ARAGORA_SMTP_PORTOptionalSMTP server port587
ARAGORA_SMTP_USEROptionalSMTP username-
ARAGORA_SMTP_PASSWORDOptionalSMTP password-
ARAGORA_SMTP_FROMOptionalFrom email addressbilling@aragora.ai
ARAGORA_NOTIFICATION_WEBHOOKOptionalWebhook URL for billing notifications-
ARAGORA_PAYMENT_GRACE_DAYSOptionalDays before downgrade after payment failure10
ARAGORA_ALLOW_INSECURE_PASSWORDSOptionalAllow weak passwords (dev only)0

SSO/Enterprise Authentication​

Single Sign-On configuration for enterprise authentication. Supports OIDC and SAML 2.0.

VariableRequiredDescriptionDefault
ARAGORA_SSO_ENABLEDNoEnable SSO authenticationfalse
ARAGORA_SSO_PROVIDER_TYPEIf SSO enabledProvider type: oidc, saml, azure_ad, okta, googleoidc
ARAGORA_SSO_CALLBACK_URLIf SSO enabledCallback URL for auth response (must be HTTPS in production)-
ARAGORA_SSO_ENTITY_IDIf SSO enabledService provider entity ID-

OIDC Configuration​

VariableRequiredDescriptionDefault
ARAGORA_SSO_CLIENT_IDOIDCOAuth client ID-
ARAGORA_SSO_CLIENT_SECRETOIDCOAuth client secret-
ARAGORA_SSO_ISSUER_URLOIDCOIDC issuer URL (e.g., https://login.microsoftonline.com/tenant/v2.0)-
ARAGORA_SSO_AUTH_ENDPOINTOptionalOverride authorization endpointAuto-discovered
ARAGORA_SSO_TOKEN_ENDPOINTOptionalOverride token endpointAuto-discovered
ARAGORA_SSO_USERINFO_ENDPOINTOptionalOverride userinfo endpointAuto-discovered
ARAGORA_SSO_JWKS_URIOptionalOverride JWKS URIAuto-discovered
ARAGORA_SSO_SCOPESOptionalOAuth scopesopenid,email,profile

SAML Configuration​

VariableRequiredDescriptionDefault
ARAGORA_SSO_IDP_ENTITY_IDSAMLIdP entity ID-
ARAGORA_SSO_IDP_SSO_URLSAMLIdP SSO URL-
ARAGORA_SSO_IDP_SLO_URLOptionalIdP logout URL-
ARAGORA_SSO_IDP_CERTIFICATESAMLIdP X.509 certificate (PEM format)-
ARAGORA_SSO_SP_CERTIFICATEOptionalSP X.509 certificate for signed requests (PEM)-
ARAGORA_SSO_SP_PRIVATE_KEYOptionalSP private key for signed requests (PEM)-

SSO Options​

VariableRequiredDescriptionDefault
ARAGORA_SSO_ALLOWED_DOMAINSOptionalComma-separated allowed email domains- (all allowed)
ARAGORA_SSO_ALLOWED_REDIRECT_HOSTSOptionalAllowed redirect hosts for SSO callbacks-
ARAGORA_SSO_AUTO_PROVISIONOptionalAuto-create users on first logintrue
ARAGORA_SSO_SESSION_DURATIONOptionalSession duration in seconds (300-604800)28800 (8h)

Security Notes:

  • In production (ARAGORA_ENV=production), callback URLs must use HTTPS
  • SAML in production requires python3-saml package for signature validation
  • Certificates must be in PEM format (starting with -----BEGIN)

Example OIDC Configuration (Azure AD):

ARAGORA_SSO_ENABLED=true
ARAGORA_SSO_PROVIDER_TYPE=azure_ad
ARAGORA_SSO_CLIENT_ID=your-app-client-id
ARAGORA_SSO_CLIENT_SECRET=your-client-secret
ARAGORA_SSO_ISSUER_URL=https://login.microsoftonline.com/your-tenant-id/v2.0
ARAGORA_SSO_CALLBACK_URL=https://your-app.example.com/auth/sso/callback
ARAGORA_SSO_ENTITY_ID=https://your-app.example.com
ARAGORA_SSO_ALLOWED_DOMAINS=yourcompany.com

See SSO_SETUP.md for detailed provider-specific setup instructions.

SCIM 2.0 Provisioning​

VariableRequiredDescriptionDefault
SCIM_BEARER_TOKENYes (for SCIM)Bearer token for SCIM endpoint authentication(empty - no auth)
SCIM_TENANT_IDOptionalTenant ID for multi-tenant SCIM deployments(none)
SCIM_BASE_URLOptionalBase URL for SCIM resource location headers(empty)

Example SCIM Configuration:

SCIM_BEARER_TOKEN=scim-secret-token-from-idp
SCIM_TENANT_ID=acme-corp
SCIM_BASE_URL=https://api.aragora.ai

SCIM endpoints are available at /scim/v2/Users and /scim/v2/Groups. See API_REFERENCE.md for full endpoint documentation.

Embedding Providers​

For semantic search and memory retrieval.

VariableRequiredDescriptionDefault
OPENAI_EMBEDDING_MODELOptionalOpenAI embedding modeltext-embedding-3-small

Currently uses OpenAI or Gemini embeddings based on available API keys.

Broadcast / TTS​

Configure audio generation backends for broadcasts.

VariableRequiredDescriptionDefault
ARAGORA_TTS_ORDEROptionalComma-separated backend priorityelevenlabs,xtts,edge-tts,pyttsx3
ARAGORA_TTS_BACKENDOptionalForce a specific backend-
ARAGORA_ELEVENLABS_API_KEYOptionalElevenLabs API key-
ARAGORA_ELEVENLABS_MODEL_IDOptionalElevenLabs model IDeleven_multilingual_v2
ARAGORA_ELEVENLABS_VOICE_IDOptionalDefault ElevenLabs voice ID-
ARAGORA_ELEVENLABS_VOICE_MAPOptionalJSON map of speaker→voice ID-
ARAGORA_XTTS_MODEL_PATHOptionalCoqui XTTS model name/pathtts_models/multilingual/multi-dataset/xtts_v2
ARAGORA_XTTS_DEVICEOptionalXTTS device (auto, cuda, cpu)auto
ARAGORA_XTTS_LANGUAGEOptionalXTTS language codeen
ARAGORA_XTTS_SPEAKER_WAVOptionalDefault XTTS speaker WAV path-
ARAGORA_XTTS_SPEAKER_WAV_MAPOptionalJSON map of speaker→WAV path-

Notes:

  • ELEVENLABS_API_KEY is also accepted as an alias for ARAGORA_ELEVENLABS_API_KEY.
  • Use ARAGORA_TTS_ORDER to prioritize ElevenLabs or XTTS ahead of edge-tts.

Social Media APIs (Pulse Module)​

For trending topics and real-time context in debates. These power the Pulse ingestors.

VariableRequiredDescriptionSource
TWITTER_BEARER_TOKENOptionalTwitter/X API v2 Bearer token for trending topicsTwitter Developer Portal
ARAGORA_ALLOWED_OAUTH_HOSTSOptionalComma-separated allowed hosts for social OAuth redirectslocalhost:8080,127.0.0.1:8080 (dev)

No credentials needed:

  • Reddit - Uses public JSON API (reddit.com/.json)
  • Hacker News - Uses public Firebase API (hacker-news.firebaseio.com)

These services are automatically enabled when the pulse module loads.

Getting Twitter API Access​

  1. Create a developer account at developer.twitter.com
  2. Create a new project and app
  3. Generate a Bearer Token (read-only access is sufficient)
  4. Add to your .env: 
    TWITTER_BEARER_TOKEN=AAAAAAAAAAAAAAAAAAAAAx...

Pulse Module Usage​

The pulse module fetches trending topics that can inform debate context:

from aragora.pulse import PulseManager

pulse = PulseManager()
trends = await pulse.get_trending()  # Returns combined trends from all sources

Formal Verification​

Note: These variables are defined but not yet actively used in the codebase.

VariableRequiredDescriptionDefaultStatus
Z3_TIMEOUTOptionalZ3 solver timeout (seconds)30Planned
LEAN_PATHOptionalPath to Lean 4 installationAuto-detectPlanned

OpenTelemetry OTLP Export​

Configure distributed tracing export to external backends like Jaeger, Zipkin, or Datadog.

VariableRequiredDescriptionDefault
ARAGORA_OTLP_EXPORTEROptionalExporter type: none, jaeger, zipkin, otlp_grpc, otlp_http, datadognone
ARAGORA_OTLP_ENDPOINTOptionalCollector/agent endpoint URLType-specific defaults
ARAGORA_SERVICE_NAMEOptionalService name for tracesaragora
ARAGORA_SERVICE_VERSIONOptionalService version string1.0.0
ARAGORA_ENVIRONMENTOptionalDeployment environmentdevelopment
ARAGORA_TRACE_SAMPLE_RATEOptionalSampling rate 0.0-1.0 (1.0 = 100%)1.0
ARAGORA_OTLP_HEADERSOptionalJSON-encoded headers for authenticated endpoints-
ARAGORA_OTLP_BATCH_SIZEOptionalBatch processor queue size512
ARAGORA_OTLP_EXPORT_TIMEOUT_MSOptionalExport timeout in milliseconds30000
ARAGORA_OTLP_INSECUREOptionalAllow insecure (non-TLS) connectionsfalse
DATADOG_API_KEYOptionalDatadog API key (for datadog exporter)-

Default Endpoints by Exporter Type:

  • jaeger: localhost (uses Jaeger agent UDP port 6831)
  • zipkin: http://localhost:9411/api/v2/spans
  • otlp_grpc: http://localhost:4317
  • otlp_http: http://localhost:4318/v1/traces
  • datadog: http://localhost:4317 (Datadog Agent OTLP receiver)

Example Configurations:

# Jaeger (local development)
ARAGORA_OTLP_EXPORTER=jaeger
ARAGORA_OTLP_ENDPOINT=localhost

# Zipkin
ARAGORA_OTLP_EXPORTER=zipkin
ARAGORA_OTLP_ENDPOINT=http://zipkin.example.com:9411/api/v2/spans

# OTLP gRPC (standard OpenTelemetry collector)
ARAGORA_OTLP_EXPORTER=otlp_grpc
ARAGORA_OTLP_ENDPOINT=http://otel-collector.example.com:4317

# OTLP HTTP
ARAGORA_OTLP_EXPORTER=otlp_http
ARAGORA_OTLP_ENDPOINT=http://otel-collector.example.com:4318/v1/traces

# Datadog (via Datadog Agent)
ARAGORA_OTLP_EXPORTER=datadog
ARAGORA_OTLP_ENDPOINT=http://localhost:4317
DATADOG_API_KEY=your-datadog-api-key

# Production with authentication
ARAGORA_OTLP_EXPORTER=otlp_grpc
ARAGORA_OTLP_ENDPOINT=https://otel.example.com:443
ARAGORA_OTLP_HEADERS='{"Authorization": "Bearer your-token"}'
ARAGORA_TRACE_SAMPLE_RATE=0.1  # 10% sampling for high traffic

Required Packages:

  • Jaeger: pip install opentelemetry-exporter-jaeger
  • Zipkin: pip install opentelemetry-exporter-zipkin
  • OTLP gRPC: pip install opentelemetry-exporter-otlp-proto-grpc
  • OTLP HTTP: pip install opentelemetry-exporter-otlp-proto-http

Telemetry Configuration​

Controls observation levels for debug and production modes.

VariableRequiredDescriptionDefault
ARAGORA_TELEMETRY_LEVELOptionalTelemetry level (SILENT/DIAGNOSTIC/CONTROLLED/SPECTACLE)CONTROLLED

Levels:

  • SILENT (0): No telemetry broadcast
  • DIAGNOSTIC (1): Internal diagnostics only
  • CONTROLLED (2): Redacted telemetry (default, secrets filtered)
  • SPECTACLE (3): Full transparency (development only)

Belief Network Settings​

For belief propagation analysis during debates.

VariableRequiredDescriptionDefault
ARAGORA_BELIEF_MAX_ITERATIONSOptionalMax iterations for belief convergence100
ARAGORA_BELIEF_CONVERGENCE_THRESHOLDOptionalConvergence epsilon0.001

Queue Settings​

VariableRequiredDescriptionDefault
ARAGORA_USER_EVENT_QUEUE_SIZEOptionalUser event queue buffer size100

Broadcast (Audio/Podcast)​

Configuration for debate-to-podcast conversion.

VariableRequiredDescriptionDefault
ARAGORA_AUDIO_DIROptionalAudio storage directory.nomic/audio/
ARAGORA_TTS_TIMEOUTOptionalTTS generation timeout (seconds)60
ARAGORA_TTS_RETRIESOptionalTTS retry attempts3

See BROADCAST.md for the complete audio pipeline documentation.

Transcription (Speech-to-Text)​

Configuration for audio/video transcription using Whisper backends.

VariableRequiredDescriptionDefault
ARAGORA_WHISPER_BACKENDOptionalTranscription backend: openai, faster-whisper, whisper-cpp, autoauto
ARAGORA_WHISPER_MODELOptionalWhisper model size: tiny, base, small, medium, largebase
ARAGORA_TRANSCRIPTION_TIMEOUTOptionalTranscription timeout (seconds)300
ARAGORA_MAX_AUDIO_DURATIONOptionalMax audio duration for transcription (seconds)3600
ARAGORA_MAX_AUDIO_SIZE_MBOptionalMax audio file size (MB)25

Backend Selection:

  • openai - Uses OpenAI Whisper API (requires OPENAI_API_KEY)
  • faster-whisper - Local CTranslate2-based transcription (requires pip install faster-whisper)
  • whisper-cpp - Local whisper.cpp binary (requires whisper in PATH)
  • auto - Tries OpenAI first, falls back to local backends

Usage:

# Use OpenAI Whisper API (fastest, requires API key)
ARAGORA_WHISPER_BACKEND=openai

# Use local faster-whisper (GPU-accelerated)
ARAGORA_WHISPER_BACKEND=faster-whisper
ARAGORA_WHISPER_MODEL=medium

# Use whisper.cpp (CPU-optimized)
ARAGORA_WHISPER_BACKEND=whisper-cpp

Accounting & Payroll Integrations​

Configuration for accounting and payroll connectors (enable only if used).

VariableRequiredDescriptionDefault
QBO_CLIENT_IDOptionalQuickBooks OAuth client ID-
QBO_CLIENT_SECRETOptionalQuickBooks OAuth client secret-
QBO_REDIRECT_URIOptionalQuickBooks OAuth callback URL-
QBO_ENVIRONMENTOptionalQuickBooks environment (sandbox, production)sandbox
PLAID_CLIENT_IDOptionalPlaid client ID-
PLAID_SECRETOptionalPlaid secret key-
PLAID_ENVIRONMENTOptionalPlaid environment (sandbox, development, production)sandbox
GUSTO_CLIENT_IDOptionalGusto OAuth client ID-
GUSTO_CLIENT_SECRETOptionalGusto OAuth client secret-
GUSTO_REDIRECT_URIOptionalGusto OAuth callback URL-

Bot Integrations​

Configuration for chat platform bots (Discord, Teams, Zoom, Slack).

Discord Bot​

VariableRequiredDescriptionDefault
DISCORD_BOT_TOKENRequiredDiscord bot authentication token-
DISCORD_APPLICATION_IDRequiredDiscord application ID for slash commands-
DISCORD_PUBLIC_KEYRequiredPublic key for interaction verification-

Setup:

  1. Create application at Discord Developer Portal
  2. Enable "Bot" and copy the token
  3. Enable "Slash Commands" and note the Application ID
  4. Copy the Public Key from "General Information"
  5. Set Interactions Endpoint URL to https://your-api.com/api/bots/discord/interactions

Microsoft Teams Bot​

VariableRequiredDescriptionDefault
TEAMS_APP_IDRequiredAzure Bot registration App ID-
TEAMS_APP_PASSWORDRequiredAzure Bot registration password-

Setup:

  1. Register a bot at Azure Bot Service
  2. Enable Teams channel in "Channels" settings
  3. Create an app manifest for Teams deployment
  4. Set Messaging Endpoint to https://your-api.com/api/bots/teams/messages

Zoom Bot​

VariableRequiredDescriptionDefault
ZOOM_CLIENT_IDRequiredZoom app OAuth client ID-
ZOOM_CLIENT_SECRETRequiredZoom app OAuth client secret-
ZOOM_BOT_JIDRequiredBot's JID for chat messages-
ZOOM_SECRET_TOKENRequiredWebhook signature verification token-
ZOOM_VERIFICATION_TOKENOptionalLegacy verification token-

Setup:

  1. Create an app at Zoom Marketplace
  2. Choose "Chatbot" app type
  3. Configure OAuth scopes for chat messaging
  4. Set Event Subscription URL to https://your-api.com/api/bots/zoom/events

Slack (Enhanced)​

Slack integration uses the existing SLACK_* variables with additional bidirectional features.

VariableRequiredDescriptionDefault
SLACK_CLIENT_IDRequiredOAuth app client ID-
SLACK_CLIENT_SECRETRequiredOAuth app client secret-
SLACK_SIGNING_SECRETRequiredRequest signing secret (webhook verification)-
SLACK_REDIRECT_URIRequired in ProductionOAuth callback URL (enforced when ARAGORA_ENV=production)Auto-construct in dev
SLACK_BOT_TOKENOptionalBot token for direct API calls (xoxb-...)-
SLACK_APP_TOKENOptionalApp-level token for Socket Mode (xapp-...)-
SLACK_SCOPESOptionalOAuth scopes (comma-separated)See default scopes
ARAGORA_API_BASE_URLRequired in ProductionBase URL for internal API callshttp://localhost:8080
ARAGORA_ENCRYPTION_KEYRequired in ProductionEncryption key for token storage-
ARAGORA_ENVOptionalEnvironment mode (production enforces requirements)development

Production Requirements:

  • SLACK_REDIRECT_URI must be set when ARAGORA_ENV=production (prevents open redirect attacks)
  • ARAGORA_API_BASE_URL should point to your production API endpoint
  • ARAGORA_ENCRYPTION_KEY required for secure token storage (PBKDF2-HMAC with 480k iterations)

Additional Commands:

  • /aragora debate "topic" - Start a multi-agent debate
  • /aragora gauntlet - Run stress-test validation (with file attachment)
  • /aragora status - Check system health
  • /aragora help - List available commands

See BOT_INTEGRATIONS.md for detailed setup guides.

Debug & Logging​

VariableRequiredDescriptionDefault
ARAGORA_DEBUGOptionalEnable debug loggingfalse
ARAGORA_LOG_LEVELOptionalLog level (DEBUG/INFO/WARN/ERROR)INFO
ARAGORA_LOG_FILEOptionalLog file path- (stdout only)
ARAGORA_LOG_FORMATOptionalLog format (json, text)text
ARAGORA_LOG_TIMESTAMPOptionalInclude timestamps in logstrue
ARAGORA_LOG_MAX_BYTESOptionalMax log file size before rotation10485760 (10MB)
ARAGORA_LOG_BACKUP_COUNTOptionalNumber of rotated log files to keep5
ARAGORA_DEV_MODEOptionalEnable development mode featuresfalse

Security & Encryption​

VariableRequiredDescriptionDefault
ARAGORA_ENCRYPTION_KEYOptionalEncryption key for sensitive data at rest-
ARAGORA_ENCRYPTION_REQUIREDOptionalFail if encryption unavailablefalse (auto true in production)
ARAGORA_AUDIT_SIGNING_KEYOptionalKey for signing audit log entries-
ARAGORA_METRICS_TOKENOptionalAuth token for metrics endpoint-
ARAGORA_SECRET_NAMEOptionalAWS Secrets Manager secret name-
ARAGORA_ALLOW_UNVERIFIED_WEBHOOKSOptionalAllow unverified webhooks (dev only)false

Security Notes:

  • ARAGORA_ENCRYPTION_REQUIRED is automatically enabled when ARAGORA_ENV=production
  • ARAGORA_ALLOW_UNVERIFIED_WEBHOOKS should never be set in production - webhooks will fail-closed if verification is unavailable
  • Webhook verification requires: Slack (signing secret), Discord (PyNaCl + public key), Teams/Google Chat (PyJWT)
  • When AWS_REGION/AWS_DEFAULT_REGION is set, Secrets Manager is enabled by default and ARAGORA_SECRET_NAME falls back to aragora/production if not provided.

Knowledge System​

VariableRequiredDescriptionDefault
ARAGORA_KNOWLEDGE_AUTO_PROCESSOptionalAuto-process new knowledge entriestrue
ARAGORA_QUERY_CACHE_ENABLEDOptionalEnable request-scoped knowledge query cachetrue
ARAGORA_QUERY_CACHE_MAX_SIZEOptionalMax entries per request-scoped cache1000

Evolution & Prompt Settings​

VariableRequiredDescriptionDefault
ARAGORA_ALLOW_AUTO_EVOLVEOptionalAllow automatic prompt evolutionfalse
ARAGORA_ALLOW_PROMPT_EVOLVEOptionalAllow prompt modification during debatesfalse
ARAGORA_HYBRID_IMPLEMENTOptionalEnable hybrid implementation modefalse
ARAGORA_SKIP_GATESOptionalSkip safety gates (dev only)false

Cache Settings​

VariableRequiredDescriptionDefault
ARAGORA_CACHE_MAX_ENTRIESOptionalMax entries in LRU caches1000
ARAGORA_CACHE_EVICT_PERCENTOptionalPercentage to evict when cache full10

Observability & Performance​

VariableRequiredDescriptionDefault
ARAGORA_N1_DETECTIONOptionalN+1 query detection mode: off, warn, erroroff
ARAGORA_N1_THRESHOLDOptionalN+1 query threshold per table5

CLI & Process Settings​

VariableRequiredDescriptionDefault
ARAGORA_MAX_CLI_SUBPROCESSESOptionalMax concurrent CLI agent subprocesses4
ARAGORA_BIND_HOSTOptionalHost to bind server to0.0.0.0
ARAGORA_ORG_IDOptionalDefault organization ID-
ARAGORA_SCOPE_CHECKOptionalEnable scope validationtrue

Testing & CI​

VariableRequiredDescriptionDefault
ARAGORA_BASELINE_PARALLELOptionalParallel workers for baseline runnerauto
ARAGORA_BASELINE_TIMEOUTOptionalTimeout seconds for baseline runner60
ARAGORA_TEST_REAL_AUTHOptionalEnable real auth checks in tests-

Legacy Database Aliases​

These variables are legacy aliases maintained for backwards compatibility:

VariableAlias ForDescription
ARAGORA_SQL_CONNECTIONDATABASE_URLLegacy SQL connection string
ARAGORA_POSTGRES_DSNDATABASE_URLLegacy Postgres DSN
ARAGORA_REQUIRE_DISTRIBUTED_STATEARAGORA_REQUIRE_DISTRIBUTEDDeprecated distributed-state flag

Validation Rules​

API Keys​

  • Must be non-empty strings
  • Validated on first API call
  • Keys are not logged (security)

Ports​

  • Must be integers 1-65535
  • HTTP API: 8080 (default)
  • WebSocket: 8765 (default, / or /ws)
  • Single-port option: use AiohttpUnifiedServer (advanced)

URLs​

  • Must be valid HTTPS URLs (for production)
  • HTTP allowed for localhost development

Example .env File​

# Required: At least one AI provider
ANTHROPIC_API_KEY=sk-ant-xxx
OPENAI_API_KEY=sk-xxx

# Optional: Additional providers
GEMINI_API_KEY=AIzaSy...
XAI_API_KEY=xai-xxx
MISTRAL_API_KEY=xxx
OPENROUTER_API_KEY=sk-or-xxx
DEEPSEEK_API_KEY=sk-xxx

# Optional: Local models
OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=llama2

# Optional: Persistence
SUPABASE_URL=https://xxx.supabase.co
SUPABASE_KEY=eyJ...

# Optional: Client defaults / auth
ARAGORA_API_URL=http://localhost:8080
ARAGORA_API_TOKEN=my-secret-token

# Optional: JWT Authentication
ARAGORA_JWT_SECRET=your-secure-secret-key
ARAGORA_JWT_EXPIRY_HOURS=24

# Optional: Stripe Billing
STRIPE_SECRET_KEY=sk_test_xxx
STRIPE_WEBHOOK_SECRET=whsec_xxx
STRIPE_PRICE_STARTER=price_xxx
STRIPE_PRICE_PROFESSIONAL=price_xxx
STRIPE_PRICE_ENTERPRISE=price_xxx

# Optional: Redis (rate limiting, queues, oauth state)
ARAGORA_REDIS_URL=redis://localhost:6379/0
REDIS_URL=redis://localhost:6379

# Optional: Webhooks
ARAGORA_WEBHOOKS_CONFIG=/etc/aragora/webhooks.json

# Optional: Social Media (Pulse module)
TWITTER_BEARER_TOKEN=AAAA...  # For trending topics

Troubleshooting​

"No API key found"​

  • Set at least one of: ANTHROPIC_API_KEY, OPENAI_API_KEY
  • Verify .env file is in project root

"CORS blocked"​

  • Add your domain to ARAGORA_ALLOWED_ORIGINS
  • Check for typos in origin URLs

"WebSocket connection failed"​

  • Verify --ws-port (server) matches NEXT_PUBLIC_WS_URL (frontend) or your client URL
  • Check firewall/proxy settings

"Rate limit exceeded"​

  • Increase ARAGORA_RATE_LIMIT / ARAGORA_IP_RATE_LIMIT
  • Or wait for rate limit window to reset

SSL/TLS Configuration​

Enable HTTPS for production deployments.

VariableRequiredDescriptionDefault
ARAGORA_SSL_ENABLEDOptionalEnable SSL/TLSfalse
ARAGORA_SSL_CERTIf SSL enabledPath to SSL certificate file-
ARAGORA_SSL_KEYIf SSL enabledPath to SSL private key file-

Example:

ARAGORA_SSL_ENABLED=true
ARAGORA_SSL_CERT=/etc/ssl/certs/aragora.pem
ARAGORA_SSL_KEY=/etc/ssl/private/aragora-key.pem

Self-signed certificate for development​

# Generate a self-signed certificate
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

# Use with Aragora
ARAGORA_SSL_ENABLED=true
ARAGORA_SSL_CERT=cert.pem
ARAGORA_SSL_KEY=key.pem

Deployment Tuning Guides​

High-Load Deployments​

For production systems handling many concurrent debates:

# Rate limiting - increase for high-traffic APIs
ARAGORA_RATE_LIMIT=200          # 200 req/min per token
ARAGORA_IP_RATE_LIMIT=500       # 500 req/min per IP

# Debate limits
ARAGORA_MAX_AGENTS_PER_DEBATE=8 # Limit agents per debate
ARAGORA_MAX_CONCURRENT_DEBATES=50  # Allow more parallel debates

# WebSocket settings
ARAGORA_WS_MAX_MESSAGE_SIZE=131072  # 128KB for large messages
ARAGORA_WS_HEARTBEAT=15            # More frequent heartbeats

# Database timeouts
ARAGORA_DB_TIMEOUT=60.0            # Longer timeout for complex queries

# Cache TTLs - shorter for freshness
ARAGORA_CACHE_LEADERBOARD=60       # 1 minute leaderboard cache
ARAGORA_CACHE_AGENT_PROFILE=120    # 2 minute profile cache

Development Mode​

For local development with faster iteration:

# Debug output
ARAGORA_DEBUG=true
ARAGORA_LOG_LEVEL=DEBUG

# Disable SSL for localhost
ARAGORA_SSL_ENABLED=false

# Lower timeouts for faster feedback
ARAGORA_DEBATE_TIMEOUT=120         # 2 minute debate timeout
ARAGORA_DB_TIMEOUT=10.0            # Quick database timeout

# Generous rate limits
ARAGORA_RATE_LIMIT=1000
ARAGORA_IP_RATE_LIMIT=1000

# Full telemetry for debugging
ARAGORA_TELEMETRY_LEVEL=SPECTACLE

Testing Configuration​

For running test suites:

# Use in-memory or test databases
ARAGORA_DB_ELO=:memory:
ARAGORA_DB_MEMORY=:memory:

# Short timeouts for fast tests
ARAGORA_DB_TIMEOUT=5.0
ARAGORA_DEBATE_TIMEOUT=30

# Disable external services
# (Don't set API keys to skip external API tests)

# Disable SSL
ARAGORA_SSL_ENABLED=false

# Silent telemetry
ARAGORA_TELEMETRY_LEVEL=SILENT

Configuration Validation​

Aragora validates configuration at startup. Check configuration with:

from aragora.config import validate_configuration

# Non-strict: logs warnings, returns validation result
result = validate_configuration(strict=False)
print(result["valid"])       # True if no errors
print(result["warnings"])    # List of warnings
print(result["config_summary"])  # Current config values

# Strict: raises ConfigurationError on errors
from aragora.config import validate_configuration, ConfigurationError
try:
    validate_configuration(strict=True)
except ConfigurationError as e:
    print(f"Config error: \{e\}")

Validation Checks​

  • Rate limits: Must be positive integers
  • Timeouts: Must be positive numbers
  • SSL paths: Must exist if SSL enabled
  • API keys: Warning if none configured (error in strict mode)