Skip to main content
AgentFlow is configured through environment variables and Python config classes.

​
Local .env

Create a .env file at the project root: 
# Required for LLM-backed calls
OPENAI_API_KEY=sk-...

# Required for tenant-backed routes
DATABASE_URL=postgresql://postgres:postgres@postgres:5432/agentflow
TENANT=agentflow
TENANT_NAMES=agentflow
PREWARM_TENANTS=agentflow

# Local development auth bypass
DEV_AUTH_BYPASS=true
DEV_TENANT_NAME=agentflow
DEV_USER_ID=local-dev

# Runtime
ENVIRONMENT=development          # development | staging | production
CORS_ALLOWED_ORIGINS=http://localhost:3000
LOG_LEVEL=INFO                   # DEBUG | INFO | WARNING | ERROR
ENCRYPTION_KEY=64_hex_characters # Required for encrypted tenant BYO LLM keys
For Docker Compose, keep DATABASE_URL pointed at the Compose service hostname postgres. For host-run scripts, override it with postgresql://postgres:postgres@localhost:5432/agentflow.

​
Deployment Matrix

VariableRequired forNotes
DATABASE_URLReadiness, migrations, all tenant-backed routesLeave unset only with AGENTFLOW_ALLOW_NO_DATABASE=true for health/docs-only mode.
AGENTFLOW_ALLOW_NO_DATABASEHealth/docs-only local bootSet true only when intentionally running without PostgreSQL.
OPENAI_API_KEYPlatform-managed OpenAI callsNot needed for a tenant that exclusively uses BYO provider keys.
Provider keys such as ANTHROPIC_API_KEY or GOOGLE_API_KEYPlatform-managed non-OpenAI callsUse only for provider keys the deployment owns globally.
ENCRYPTION_KEYTenant BYO LLM keysRequired before saving encrypted provider keys through /api/v1/llm/config.
REDIS_URLShared caches, rate limits, question wakeups, workersRecommended for any multi-replica deployment.
TENANTSingle-tenant local or production jobsDefault tenant key for scripts and prewarm.
TENANT_NAMESMulti-tenant workers and migration jobsComma or whitespace separated tenant database names.
PREWARM_TENANTSLow-latency startupComma or whitespace separated tenants to bootstrap at API startup.
DEV_AUTH_BYPASSLocal development onlyMust be false or unset outside local development.
DEV_TENANT_NAME, DEV_USER_IDLocal development onlyTenant/user identity used when DEV_AUTH_BYPASS=true.
AUTH0_DOMAIN, AUTH0_AUDIENCE, AUTH0_ISSUERProduction human authVerifies user bearer tokens.
AUTH0_M2M_AUDIENCE, AUTH0_M2M_ISSUER, AUTH0_M2M_REQUIRED_SCOPEProduction machine authVerifies service-to-service bearer tokens and required scope.
CORS_ALLOWED_ORIGINSBrowser clientsComma separated allowed web origins.
LOG_LEVELAll environmentsDEBUG, INFO, WARNING, or ERROR.
DD_TRACE_ENABLED, DD_LLMOBS_ENABLED, DD_LLMOBS_ML_APPDatadog observabilityKeep DD_LLMOBS_ML_APP lowercase.
Add platform API keys for providers the deployment itself should manage. Tenant BYO keys are configured by admins at runtime through /api/v1/llm/config; they are encrypted with ENCRYPTION_KEY and are not stored in .env.

​
Auth Modes

Local development can bypass Auth0: 
DEV_AUTH_BYPASS=true
DEV_TENANT_NAME=agentflow
DEV_USER_ID=local-dev
Production uses bearer tokens from the configured Auth0 issuer. Machine clients use client credentials, a configured M2M scope, and tenant/user context agreed to during onboarding. See Authentication.

​
Usage & Budget Controls

AgentFlow tracks LLM usage through the LiteLLM gateway and enforces monthly spend caps before outbound model calls. 
# Per-process outbound LLM concurrency
LLM_CONCURRENCY_LIMIT=30

# Shared fixed-window request limits; 0 disables the limit
LLM_RATE_LIMIT_RPM_PER_TENANT=600
LLM_RATE_LIMIT_RPM_PER_USER=120

# Monthly caps used when no settings override is configured
LLM_BUDGET_PER_TENANT=100.0
LLM_BUDGET_PER_USER=100.0

# Admin scopes accepted for Usage and Budget settings APIs
AGENTFLOW_ADMIN_SCOPES=agentflow:admin admin:agentflow admin:usage usage:admin admin:budget budget:admin

# Recommended for shared live spend and RPM counters in multi-replica deployments
REDIS_URL=redis://redis:6379/0
See Usage Tracking & Budgets for the dashboard, telemetry pipeline, budget reset behavior, and rate-control model.

​
LLM Defaults

These defaults are used when no explicit llm_config is provided:
PurposeDefault Behavior
AgentPrimary model, higher temperature for natural responses
ToolSmaller model, zero temperature for deterministic output
PlanningSmaller model, moderate temperature
ReflectionSmaller model, zero temperature
Override per-agent via the llm_config parameter in the @agent decorator or the management API.

​
Multi-Provider LLM Support

AgentFlow supports multiple LLM providers. Prefix models with the provider name: 
"openai/gpt-4o"
"anthropic/claude-sonnet-4-20250514"
"google/gemini-2.0-flash"
Set the corresponding API key environment variable for each provider you use.

​
BYO LLM Tenant Keys

Tenant admins can bring their own provider keys without exposing platform defaults. Save one provider configuration per key: 
POST /api/v1/llm/config
{
  "provider": "anthropic",
  "api_key": "sk-ant-...",
  "allowed_models": ["anthropic/claude-sonnet-4-5-20250929"],
  "default_models": {
    "chat": "anthropic/claude-sonnet-4-5-20250929",
    "tool": "anthropic/claude-sonnet-4-5-20250929"
  },
  "mode": "byo"
}
When mode is byo, every tenant LLM use case must resolve to an allowed tenant model. This includes agent chat, raw LLM chat, tool calls, sub-agents, title generation, KB enrichment, follow-up questions, autocomplete, query processing, planning, reflection, summaries, embeddings, reranking, and vision. Disallowed explicit model requests return 403. Use GET /api/v1/llm/config/model-options to discover the current model ids and use-case keys before saving the policy.