AgentTrust Docs

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

Variable	Default	Purpose
`AGENTRUST_ENABLED`	`true`	Master kill-switch
`AGENTRUST_GATEWAY_URL`	`http://localhost:8000`	Gateway base URL
`AGENTRUST_KEY`	—	API key (overrides config file)
`AGENTRUST_TIMEOUT_SEC`	`10`	HTTP request timeout
`AGENTRUST_RETRY_ATTEMPTS`	`3`	Max retries (requires `[retry]` extra)
`AGENTRUST_RETRY_BACKOFF`	`0.5`	Initial backoff seconds
`AGENTRUST_FAILURE_MODE`	`open`	`open` \| `closed` \| `queue`
`AGENTRUST_QUEUE_DB`	`~/.agentrust/queue.db`	Queue buffer SQLite path
`AGENTRUST_AUTO_INSTRUMENT`	`true`	Disable auto-hooks when `false`
`AGENTRUST_EMBED_PORT`	`8765`	Embedded gateway port
`AGENTRUST_EMBED_DB`	`~/.agentrust/embedded.db`	Embedded SQLite path
`AGENTRUST_EMBED_TOKEN`	auto-generated	Bearer token for embedded gateway
`AGENTRUST_AUTOLOAD_EMBED`	—	Auto-start embedded gateway
`AGENTRUST_AUTOLOAD_AGENT_ID`	—	Default agent ID for autoload
`AGENTRUST_SDK_VERSION`	`0.0.1a1`	Override only in tests

TypeScript SDK

Variable	Default	Purpose
`AGENTRUST_GATEWAY_URL`	`http://localhost:8000`	Gateway base URL
`AGENTRUST_API_KEY`	—	API key (not `AGENTRUST_KEY`)
`AGENTRUST_ENABLED`	`true`	Kill-switch
`AGENTRUST_FAILURE_MODE`	`open`	`open` \| `closed` (no `queue`)
`AGENTRUST_TIMEOUT_MS`	`10000`	Request timeout

Gateway (Docker Compose / K8s)

Variable	Purpose
`DATABASE_URL`	PostgreSQL connection string
`REDIS_URL`	Redis connection string
`AGENTRUST_ENV`	`production` / `development`
`AGENTRUST_JWT_SECRET`	JWT signing secret (required when auth on)
`AUTH_ENABLED`	Defaults ON except dev/test
`RATE_LIMIT_ENABLED`	Per-agent rate limiting
`RATE_LIMIT_PER_MINUTE`	Default 60
`AGENTRUST_API_KEYS`	Comma-separated static API keys
`AGENTRUST_AUTO_MIGRATE`	Auto-run Alembic migrations
`JUDGE_BACKEND`	`disabled` \| `ollama` \| `claude`
`ANTHROPIC_API_KEY`	Claude judge backend
`WEBHOOK_URL`, `WEBHOOK_SECRET`	Outbound webhooks
`AGENTRUST_AUDIT_ENCRYPTION_KEY`	AES-256-GCM at-rest encryption
`OBJECT_STORE_*`	S3/MinIO evidence offload
`VECTOR_STORE_*`	pgvector/Chroma semantic search
`AGENTRUST_SIGNING_KEY`	Ed25519 audit package signing
`AGENTRUST_HYBRID_MODE`	Hybrid cloud telemetry
`OTEL_EXPORTER_OTLP_ENDPOINT`	OpenTelemetry export
`RECERT_ENABLED`	Continuous re-certification scheduler
`CORS_ALLOWED_ORIGINS`	Dashboard CORS

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

Issue	Check
SDK ignores env change	Call `SDK_CONFIG.reload()` in tests after mutating `os.environ`
Invalid failure mode	Must be exactly `open`, `closed`, or `queue`
Gateway auth fails	Verify `AGENTRUST_KEY` matches `AGENTRUST_API_KEYS` or JWT

Environment Variables