Configuration

Environment Variables

Complete reference for AGENTRUST_* environment variables.

Environment Variables

Overview

All AgentTrust configuration is driven by environment variables. No config file is required for basic usage. Variables are read lazily at runtime, so secrets managers and container entrypoints can inject values without restart.

Why It Matters

Env-only configuration enables the deployment ladder: identical app code across dev, staging, and production with only variable changes.

Prerequisites

None — reference document.

Step-by-Step Guide

Python SDK

VariableDefaultPurpose
AGENTRUST_ENABLEDtrueMaster kill-switch
AGENTRUST_GATEWAY_URLhttp://localhost:8000Gateway base URL
AGENTRUST_KEY—API key (overrides config file)
AGENTRUST_TIMEOUT_SEC10HTTP request timeout
AGENTRUST_RETRY_ATTEMPTS3Max retries (requires [retry] extra)
AGENTRUST_RETRY_BACKOFF0.5Initial backoff seconds
AGENTRUST_FAILURE_MODEopenopen | closed | queue
AGENTRUST_QUEUE_DB~/.agentrust/queue.dbQueue buffer SQLite path
AGENTRUST_AUTO_INSTRUMENTtrueDisable auto-hooks when false
AGENTRUST_EMBED_PORT8765Embedded gateway port
AGENTRUST_EMBED_DB~/.agentrust/embedded.dbEmbedded SQLite path
AGENTRUST_EMBED_TOKENauto-generatedBearer token for embedded gateway
AGENTRUST_AUTOLOAD_EMBED—Auto-start embedded gateway
AGENTRUST_AUTOLOAD_AGENT_ID—Default agent ID for autoload
AGENTRUST_SDK_VERSION0.0.1a1Sent as X-AgentTrust-SDK-Version; override only in tests
AGENTRUST_EMBED_HOST127.0.0.1Embedded gateway bind host (0.0.0.0 for Docker)
AGENTRUST_AUTOLOAD_LOG_LEVELINFOVerbosity of the autoload bootstrap
AGENTRUST_WEBHOOK_URL—Discord or generic HTTPS webhook, registered on client init (Team+)
AGENTRUST_WEBHOOK_EVENTSallComma-separated: all, approve, block, escalate, request_evidence
AGENTRUST_WEBHOOK_DB~/.agentrust/webhooks.dbWebhook registry
AGENTRUST_WEBHOOK_TIMEOUT5Per-dispatch timeout, seconds
AGENTRUST_WEBHOOK_AUTO_DISPATCHtrueFire webhooks automatically after each validate()
AGENTRUST_KILL_SWITCH—Set 1 to hard-block every agent in the embedded gateway
AGENTRUST_MODEalertEmbedded execution mode: alert | hitl | block
AGENTRUST_DISCORD_WEBHOOK_URL—Embedded gateway Discord notifier
AGENTRUST_SLACK_WEBHOOK_URL—Embedded gateway Slack notifier
AGENTRUST_LLM_ENABLEDfalseEnable the embedded LLM classifier
AGENTRUST_LLM_KEY / AGENTRUST_LLM_MODEL— / gpt-4o-miniOpenAI-compatible classifier credentials

TypeScript SDK

VariableDefaultPurpose
AGENTRUST_GATEWAY_URLhttp://localhost:8000Gateway base URL
AGENTRUST_API_KEY—API key (not AGENTRUST_KEY)
AGENTRUST_ENABLEDtrueKill-switch
AGENTRUST_FAILURE_MODEopenopen | closed (no queue)
AGENTRUST_TIMEOUT_MS10000Request timeout

Gateway (Docker Compose / K8s)

VariablePurpose
DATABASE_URLPostgreSQL connection string (required — no default)
REDIS_URLRedis connection string
AGENTRUST_ENVproduction / development
AGENTRUST_JWT_SECRETJWT signing secret (required when auth on)
AUTH_ENABLEDDefaults ON except dev/test
RATE_LIMIT_ENABLEDPer-agent rate limiting
RATE_LIMIT_PER_MINUTEDeclared in settings (default 60) but not read by the limiter — it loads gateway/config/rate_limits.yaml. Edit that file to change limits
AGENTRUST_API_KEYSComma-separated static API keys
AGENTRUST_AUTO_MIGRATEAuto-run Alembic migrations
JUDGE_BACKENDdisabled | ollama | claude
ANTHROPIC_API_KEYClaude judge backend
WEBHOOK_URL, WEBHOOK_SECRETOutbound webhooks
AGENTRUST_AUDIT_ENCRYPTION_KEYAES-256-GCM at-rest encryption
OBJECT_STORE_*S3/MinIO evidence offload
VECTOR_STORE_*pgvector/Chroma semantic search
AGENTRUST_SIGNING_KEYEd25519 audit package signing
AGENTRUST_HYBRID_MODEHybrid cloud telemetry
OTEL_EXPORTER_OTLP_ENDPOINTOpenTelemetry export
RECERT_ENABLEDContinuous re-certification scheduler
CORS_ALLOWED_ORIGINSDashboard CORS

Two variables the gateway hard-fails on

Starting the gateway with AUTH_ENABLED=true and no AGENTRUST_JWT_SECRET — or a secret shorter than 32 characters — aborts the process at startup. In a production-like AGENTRUST_ENV (production, staging, prod, stg), AUTH_ENABLED=false or RATE_LIMIT_ENABLED=false also aborts startup. Generate a secret with openssl rand -hex 32.

Deployment ladder example

# Dev
AGENTRUST_ENABLED=true
# embed_gateway() sets AGENTRUST_GATEWAY_URL=http://localhost:8765

# Staging
AGENTRUST_GATEWAY_URL=https://agentrust-staging.internal:8000
AGENTRUST_KEY=at_team_...
AGENTRUST_FAILURE_MODE=closed

# Production
AGENTRUST_GATEWAY_URL=https://agentrust.internal:8000
AGENTRUST_FAILURE_MODE=open
AGENTRUST_RETRY_ATTEMPTS=5

Examples

Kill-switch:

export AGENTRUST_ENABLED=false

Queue mode (air-gap):

export AGENTRUST_FAILURE_MODE=queue
export AGENTRUST_QUEUE_DB=/var/lib/agentrust/queue.db

Best Practices

  • Inject secrets via your platform's secret manager, not .env files in repos
  • Use AGENTRUST_FAILURE_MODE=closed in staging, open in production (unless compliance requires closed)
  • Set AUTH_ENABLED=true on gateway in all non-dev environments
  • Document env var differences between Python and TypeScript SDKs in your runbooks

Common Mistakes

  • Using AGENTRUST_KEY in Node.js (use AGENTRUST_API_KEY)
  • Setting AGENTRUST_RETRY_ATTEMPTS without installing [retry] extra
  • Running production gateway with AUTH_ENABLED=false

Troubleshooting

IssueCheck
SDK ignores env changeEvery value is read live from os.environ on access, so no reload is needed. A client already constructed keeps the base URL and headers it was built with — construct a new one.
Invalid failure modeMust be exactly open, closed, or queue
Gateway auth failsVerify AGENTRUST_KEY matches AGENTRUST_API_KEYS or JWT

Trust Chain

Multi-agent provenance, parent envelopes, and trust chain verification.

Config File

~/.agentrust/config.yaml structure and CLI-managed configuration.

On this page

OverviewWhy It MattersPrerequisitesStep-by-Step GuidePython SDKTypeScript SDKGateway (Docker Compose / K8s)Deployment ladder exampleExamplesBest PracticesCommon MistakesTroubleshootingRelated Resources