Environment variables

Aegra is configured through environment variables in your .env file. Copy .env.example as a starting point:

cp .env.example .env

Application

Variable	Default	Description
`PROJECT_NAME`	`Aegra`	Application name
`VERSION`	`0.10.8`	Application version
`DEBUG`	`false`	Enable debug mode
`AEGRA_CONFIG`	`aegra.json`	Path to the configuration file
`MAX_SEARCH_LIMIT`	`1000`	Max `limit` for `POST /threads/search` and `POST /store/items/search`. Omitted or null `limit` uses `min(20, MAX_SEARCH_LIMIT)`. Default cap matches LangGraph Platform threads.search (`1..1000`).

Database

Two ways to configure the database connection:

Option 1: Connection string

DATABASE_URL=postgresql://user:password@host:5432/aegra

The URL is used by both SQLAlchemy (async) and LangGraph (sync) with the appropriate driver prefix applied automatically.

TLS / SSL

For managed Postgres (RDS, Azure, GCP CloudSQL, etc.) that requires TLS, set PGSSLMODE as an environment variable rather than embedding ?sslmode= in the URL:

DATABASE_URL=postgresql://user:password@host:5432/aegra
PGSSLMODE=require

Both drivers Aegra uses (psycopg and asyncpg) read PGSSLMODE from the environment. If you keep ?sslmode=... in the URL (e.g. when pasting a connection string from a cloud console), Aegra translates it for the async driver automatically:

`sslmode`	Behavior on the async path
`disable`, `allow`, `prefer`	TLS off
`require`	TLS on
`verify-ca`, `verify-full`	TLS on, but cert verification requires `PGSSLMODE` + `PGSSLROOTCERT` env vars — the URL form cannot configure an `SSLContext`

Other libpq-only parameters (sslcert, sslkey, sslrootcert, channel_binding, gssencmode, target_session_attrs) are stripped from the async URL with a warning. Use the matching PG* env vars instead — those are honored by both drivers.

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.

Variable	Default	Description
`DATABASE_URL`	—	Full PostgreSQL connection string. Supports comma-separated hosts for high availability (e.g. `host1:5432,host2:5432`)
`POSTGRES_DB`	`aegra`	Database name
`POSTGRES_HOST`	`localhost`	Database host
`POSTGRES_PASSWORD`	`password`	Database password
`POSTGRES_PORT`	`5432`	Port for direct connections and Docker’s host mapping; the Compose API container always connects on internal port `5432`
`POSTGRES_USER`	`user`	Database user
`DB_ECHO_LOG`	`false`	Log all SQL statements

Connection pools

Aegra uses two connection pools: one for SQLAlchemy (metadata) and one for LangGraph (agent runtime).

Variable	Default	Description
`SQLALCHEMY_POOL_SIZE`	`10`	SQLAlchemy connection pool size
`SQLALCHEMY_MAX_OVERFLOW`	`20`	Max overflow connections for SQLAlchemy
`LANGGRAPH_MIN_POOL_SIZE`	`5`	Minimum connections for LangGraph pool
`LANGGRAPH_MAX_POOL_SIZE`	`20`	Maximum connections for LangGraph pool

Server

Variable	Default	Description
`HOST`	`0.0.0.0`	Server host
`PORT`	`2026`	Server port
`SERVER_URL`	`http://localhost:2026`	Public-facing server URL

Authentication

Variable	Default	Description
`AUTH_TYPE`	`noop`	Authentication mode: `noop` (no auth) or `custom`

Logging

Variable	Default	Description
`LOG_LEVEL`	`INFO`	Logging level (`DEBUG`, `INFO`, `WARNING`, `ERROR`)
`ENV_MODE`	`LOCAL`	Environment mode: `LOCAL`, `DEVELOPMENT`, `PRODUCTION` (PRODUCTION outputs JSON logs)
`LOG_VERBOSITY`	`standard`	`standard` or `verbose` (verbose includes request-id)
`LOG_EXCLUDE_PATHS`	`""`	Comma-separated path prefixes whose successful (2xx/3xx) access logs are suppressed. Errors (4xx/5xx) are still logged. Example: `/health,/metrics`

LLM providers

Variable	Description
`OPENAI_API_KEY`	OpenAI API key
`ANTHROPIC_API_KEY`	Anthropic API key
`TOGETHER_API_KEY`	Together AI API key

Redis

Variable	Default	Description
`REDIS_BROKER_ENABLED`	`false`	Enable Redis for multi-instance SSE streaming and worker job dispatch
`REDIS_URL`	`redis://localhost:6379/0`	Redis connection URL
`REDIS_CHANNEL_PREFIX`	`aegra:run:`	Prefix for Redis pub/sub channels
`REDIS_MAX_CONNECTIONS`	`250`	Maximum 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.

Variable	Default	Description
`WORKER_COUNT`	`3`	Number of worker loops per instance
`N_JOBS_PER_WORKER`	`10`	Maximum concurrent runs per worker loop
`BG_JOB_TIMEOUT_SECS`	`3600`	Maximum execution time per run (seconds)
`BG_JOB_MAX_RETRIES`	`3`	Maximum retry attempts before a crashed run is permanently failed
`STUCK_PENDING_THRESHOLD_SECONDS`	`120`	How long a pending run can sit before the reaper re-enqueues it, if it is no longer in the job queue
`LEASE_DURATION_SECONDS`	`30`	Lease TTL before a crashed run is reclaimed
`HEARTBEAT_INTERVAL_SECONDS`	`10`	How often workers extend their lease
`REAPER_INTERVAL_SECONDS`	`15`	How often the reaper scans for expired leases
`POSTGRES_POLL_INTERVAL_SECONDS`	`5`	Fallback poll interval when Redis is unavailable
`WORKER_DRAIN_TIMEOUT`	`30.0`	Graceful shutdown wait time (seconds)

Total capacity per instance = WORKER_COUNT x N_JOBS_PER_WORKER (default: 30 concurrent runs).

Cron scheduler

The background scheduler polls the database for due cron jobs and fires them as runs.

Variable	Default	Description
`CRON_ENABLED`	`true`	Enable the background cron scheduler
`CRON_POLL_INTERVAL_SECONDS`	`60`	How often (in seconds) the scheduler checks for due jobs
`CRON_CLAIM_DURATION_SECONDS`	`300`	Lease duration applied when claiming a cron for firing. Must comfortably exceed worst-case run preparation time so a slow firing cannot be re-claimed by the next tick
`CRON_MAX_PER_USER`	`100`	Maximum number of crons a single user may own. `0` disables the cap
`CRON_ALLOW_SECONDS_SCHEDULE`	`false`	Allow 6-field (seconds-first) cron schedules. Sub-minute schedules multiply scheduler load and DB writes
`CRON_TICK_BATCH_SIZE`	`100`	Cap on how many crons a single tick fires per instance
`CRON_MAX_PAYLOAD_BYTES`	`65536`	Soft cap on the JSONB payload size accepted on create/update

Set CRON_ENABLED=false to disable scheduling without removing cron records. Jobs will not fire but can still be created, updated, and queried.

Cron firing is at-least-once: if a worker crashes after claiming a cron but before the run setup commits, the claim eventually expires (after CRON_CLAIM_DURATION_SECONDS) and another tick re-fires the cron. Make agent runs idempotent if duplicate firings are unacceptable.

Thread TTL

Variable	Default	Description
`AEGRA_THREAD_TTL`	—	Thread retention policy. Either a bare number (`default_ttl` in minutes) or a JSON object with any of `strategy`, `default_ttl`, `sweep_interval_minutes`, `sweep_limit`
`LANGGRAPH_THREAD_TTL`	—	Fallback alias for `AEGRA_THREAD_TTL` (same format), so env files migrated from LangGraph Platform work unchanged. `AEGRA_THREAD_TTL` wins when both are set

# 30-day TTL, delete strategy, other fields at defaults
AEGRA_THREAD_TTL=43200

# Full policy as JSON
AEGRA_THREAD_TTL='{"strategy": "keep_latest", "default_ttl": 1440, "sweep_interval_minutes": 5, "sweep_limit": 10000}'

AEGRA_THREAD_TTL takes precedence. When set, the checkpointer.ttl block in aegra.json is ignored entirely and unset fields fall back to their defaults. See the configuration reference for field semantics.

Checkpoint durability

Variable	Default	Description
`AEGRA_CHECKPOINT_DURABILITY`	—	Default checkpoint durability for runs that do not set one: `sync`, `async`, or `exit`. Wins over `checkpointer.durability` in `aegra.json`; a run’s own `durability` wins over both. When unset, `checkpointer.durability` applies, and LangGraph’s default (`async`) only if that is unset too

# Write one checkpoint per run instead of one per step
AEGRA_CHECKPOINT_DURABILITY=exit

An invalid value stops the server at startup. See checkpoint durability for the trade-offs.

Prometheus metrics

Variable	Default	Description
`ENABLE_PROMETHEUS_METRICS`	`false`	Expose `/metrics` endpoint with HTTP request metrics in Prometheus format

When enabled, a /metrics endpoint serves standard HTTP request metrics (request count, latency histograms, in-progress requests) using prometheus-fastapi-instrumentator. Compatible with any Prometheus/Grafana stack.

Observability (OpenTelemetry)

Variable	Default	Description
`OTEL_SERVICE_NAME`	`aegra-backend`	Service name for traces
`OTEL_TARGETS`	`""`	Comma-separated list: `LANGFUSE`, `PHOENIX`, `GENERIC`
`OTEL_CONSOLE_EXPORT`	`false`	Log traces to console

Langfuse

Variable	Description
`LANGFUSE_BASE_URL`	Langfuse API endpoint (e.g., `https://cloud.langfuse.com`)
`LANGFUSE_PUBLIC_KEY`	Langfuse public key
`LANGFUSE_SECRET_KEY`	Langfuse secret key

Arize Phoenix

Variable	Default	Description
`PHOENIX_COLLECTOR_ENDPOINT`	`http://127.0.0.1:6006/v1/traces`	Phoenix OTLP endpoint
`PHOENIX_API_KEY`	—	Phoenix API key (optional)

Generic OTLP

Variable	Description
`OTEL_EXPORTER_OTLP_ENDPOINT`	OTLP collector endpoint
`OTEL_EXPORTER_OTLP_HEADERS`	Headers as comma-separated `key=value` pairs

See observability guide for configuration examples.

Getting started

Core concepts

Data & storage

Configuration

Contributing

Reference

Environment variables

Application

Database

Option 1: Connection string

TLS / SSL

Option 2: Individual fields

Connection pools

Server

Authentication

Logging

LLM providers

Redis

Workers

Cron scheduler

Thread TTL

Checkpoint durability

Prometheus metrics

Observability (OpenTelemetry)

Langfuse

Arize Phoenix

Generic OTLP

​Application

​Database

​Option 1: Connection string

​TLS / SSL

​Option 2: Individual fields

​Connection pools

​Server

​Authentication

​Logging

​LLM providers

​Redis

​Workers

​Cron scheduler

​Thread TTL

​Checkpoint durability

​Prometheus metrics

​Observability (OpenTelemetry)

​Langfuse

​Arize Phoenix

​Generic OTLP

Application

Database

Option 1: Connection string

TLS / SSL

Option 2: Individual fields

Connection pools

Server

Authentication

Logging

LLM providers

Redis

Workers

Cron scheduler

Thread TTL

Checkpoint durability

Prometheus metrics

Observability (OpenTelemetry)

Langfuse

Arize Phoenix

Generic OTLP