Skip to main content
Aegra is configured through environment variables in your .env file. Copy .env.example as a starting point: 
cp .env.example .env

​
Application

VariableDefaultDescription
PROJECT_NAMEAegraApplication name
VERSION0.1.0Application version
DEBUGfalseEnable debug mode
AEGRA_CONFIGaegra.jsonPath to the configuration file

​
Database

Two ways to configure the database connection:

​
Option 1: Connection string

DATABASE_URL=postgresql://user:password@host:5432/aegra?sslmode=require
The URL is used by both SQLAlchemy (async) and LangGraph (sync) with the appropriate driver prefix applied automatically. Query parameters are preserved.

​
Option 2: Individual fields

Used when DATABASE_URL is not set: 
POSTGRES_DB=aegra
POSTGRES_HOST=localhost
POSTGRES_PASSWORD=password
POSTGRES_PORT=5432
POSTGRES_USER=user
DATABASE_URL takes precedence. When set, individual POSTGRES_* variables are ignored.
VariableDefaultDescription
DATABASE_URL—Full PostgreSQL connection string
POSTGRES_DBaegraDatabase name
POSTGRES_HOSTlocalhostDatabase host
POSTGRES_PASSWORDpasswordDatabase password
POSTGRES_PORT5432Database port
POSTGRES_USERuserDatabase user
DB_ECHO_LOGfalseLog all SQL statements

​
Connection pools

Aegra uses two connection pools: one for SQLAlchemy (metadata) and one for LangGraph (agent runtime).
VariableDefaultDescription
SQLALCHEMY_POOL_SIZE10SQLAlchemy connection pool size
SQLALCHEMY_MAX_OVERFLOW20Max overflow connections for SQLAlchemy
LANGGRAPH_MIN_POOL_SIZE5Minimum connections for LangGraph pool
LANGGRAPH_MAX_POOL_SIZE20Maximum connections for LangGraph pool

​
Server

VariableDefaultDescription
HOST0.0.0.0Server host
PORT2026Server port
SERVER_URLhttp://localhost:2026Public-facing server URL

​
Authentication

VariableDefaultDescription
AUTH_TYPEnoopAuthentication mode: noop (no auth) or custom

​
Logging

VariableDefaultDescription
LOG_LEVELINFOLogging level (DEBUG, INFO, WARNING, ERROR)
ENV_MODELOCALEnvironment mode: LOCAL, DEVELOPMENT, PRODUCTION (PRODUCTION outputs JSON logs)
LOG_VERBOSITYstandardstandard or verbose (verbose includes request-id)

​
LLM providers

VariableDescription
OPENAI_API_KEYOpenAI API key
ANTHROPIC_API_KEYAnthropic API key
TOGETHER_API_KEYTogether AI API key

​
Redis

VariableDefaultDescription
REDIS_BROKER_ENABLEDfalseEnable Redis for multi-instance SSE streaming and worker job dispatch
REDIS_URLredis://localhost:6379/0Redis connection URL
REDIS_CHANNEL_PREFIXaegra:run:Prefix for Redis pub/sub channels
REDIS_MAX_CONNECTIONS250Maximum Redis connection pool size

​
Workers

When REDIS_BROKER_ENABLED=true, runs are dispatched via a Redis job queue (BLPOP) and executed by concurrent asyncio worker tasks. Each instance runs multiple worker loops, each with a semaphore limiting concurrent jobs. Workers use lease-based crash recovery with heartbeats and a reaper process. See the worker architecture guide for the full design. In dev mode (REDIS_BROKER_ENABLED=false), runs execute as in-process asyncio tasks with no Redis required.
VariableDefaultDescription
WORKER_COUNT3Number of worker loops per instance
N_JOBS_PER_WORKER10Maximum concurrent runs per worker loop
BG_JOB_TIMEOUT_SECS3600Maximum execution time per run (seconds)
BG_JOB_MAX_RETRIES3Maximum retry attempts before a crashed run is permanently failed
STUCK_PENDING_THRESHOLD_SECONDS120How long a pending run can sit before the reaper re-enqueues it
LEASE_DURATION_SECONDS30Lease TTL before a crashed run is reclaimed
HEARTBEAT_INTERVAL_SECONDS10How often workers extend their lease
REAPER_INTERVAL_SECONDS15How often the reaper scans for expired leases
POSTGRES_POLL_INTERVAL_SECONDS5Fallback poll interval when Redis is unavailable
WORKER_DRAIN_TIMEOUT30.0Graceful shutdown wait time (seconds)
Total capacity per instance = WORKER_COUNT x N_JOBS_PER_WORKER (default: 30 concurrent runs).

​
Observability (OpenTelemetry)

VariableDefaultDescription
OTEL_SERVICE_NAMEaegra-backendService name for traces
OTEL_TARGETS""Comma-separated list: LANGFUSE, PHOENIX, GENERIC
OTEL_CONSOLE_EXPORTfalseLog traces to console

​
Langfuse

VariableDescription
LANGFUSE_BASE_URLLangfuse API endpoint (e.g., https://cloud.langfuse.com)
LANGFUSE_PUBLIC_KEYLangfuse public key
LANGFUSE_SECRET_KEYLangfuse secret key

​
Arize Phoenix

VariableDefaultDescription
PHOENIX_COLLECTOR_ENDPOINThttp://127.0.0.1:6006/v1/tracesPhoenix OTLP endpoint
PHOENIX_API_KEY—Phoenix API key (optional)

​
Generic OTLP

VariableDescription
OTEL_EXPORTER_OTLP_ENDPOINTOTLP collector endpoint
OTEL_EXPORTER_OTLP_HEADERSHeaders as comma-separated key=value pairs
See observability guide for configuration examples.