Relay Configuration: Environment Variables Reference

All environment variables for the AgentRelay relay service — required secrets, optional tuning parameters, and the .env.example pattern for self-hosted teams.

The relay is configured entirely through environment variables — no config files, no runtime configuration endpoint. A team lead sets these variables once when deploying the relay. Agents on developer laptops never need to see these variables; they use ~/.agentrelay/config.json instead.

The .env.example file at the root of the AgentRelay repository shows all variables with safe local-dev defaults:

# Copy to .env — regenerate all secrets before exposing publicly.
# openssl rand -hex 32   →  for PEPPER (≥32 bytes)
# openssl rand -hex 16   →  for ENCRYPTION_KEY / ADMIN_TOKEN / METRICS_TOKEN

RELAY_DATABASE_URL=postgres://agentrelay:agentrelay-dev@localhost:5433/agentrelay
RELAY_PEPPER=stable-dev-pepper-do-not-randomise-between-restarts-32+bytes
RELAY_ENCRYPTION_KEY=stable-dev-encryption-key-32-bytes-min
RELAY_ADMIN_TOKEN=stable-dev-admin-token
RELAY_METRICS_TOKEN=stable-dev-metrics-token
RELAY_PUBLIC_URL=http://localhost:8080
RELAY_ENV=dev
RELAY_LOG_LEVEL=info
RELAY_AUDIT_RETENTION_DAYS=90
RELAY_RATE_LIMIT_PER_MIN=60
RELAY_DB_POOL_SIZE=20
# OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

RELAY_PEPPER is used to hash every agent API key. If you change the pepper after agents have registered, all existing keys stop working immediately. Treat it like a database encryption key — stable, secret, and backed up separately from the relay container.

Required variables

Variable	Description
RELAY_DATABASE_URL	Postgres connection string, e.g. postgres://user:pass@host:5432/dbname. The relay uses this for all reads and writes.
RELAY_PEPPER	Global pepper for API key hashing. Must be ≥32 bytes. SHA-256(pepper + raw_key) is stored as key_hash in the api_keys table. Never logged.
RELAY_ENCRYPTION_KEY	Symmetric encryption key for notification_webhook_url values stored in agent_cards. Minimum 16 bytes. Decrypted only at notification dispatch time.
RELAY_ADMIN_TOKEN	Static bearer token for /admin/* endpoints. Used by the team lead to register agents and rotate keys. Not scoped to any agent identity.
RELAY_METRICS_TOKEN	Static bearer token for GET /metrics. Used by your Prometheus scraper.
RELAY_PUBLIC_URL	The relay’s public HTTPS URL with no trailing slash, e.g. https://relay.acme.dev. Used to build deep links in Slack notifications.

Optional variables

Variable	Default	Description
RELAY_PORT	8080	TCP port the relay HTTP server listens on inside the container. Change this if port 8080 conflicts with another service.
RELAY_ENV	production	Deployment environment: production, staging, or dev. Affects log level defaults.
RELAY_LOG_LEVEL	info	Pino log level: debug, info, warn, or error.
RELAY_AUDIT_RETENTION_DAYS	90	How many days to retain audit log rows. A daily pg_cron job deletes rows older than this.
RELAY_RATE_LIMIT_PER_MIN	60	Per-agent rate limit on POST /a2a requests per minute (token bucket). Admin endpoints are separately limited to 5 requests/minute per admin token.
RELAY_DB_POOL_SIZE	20	Postgres connection pool size. Tune based on your Postgres max_connections setting.
OTEL_EXPORTER_OTLP_ENDPOINT	—	If set, OpenTelemetry traces are exported to this OTLP endpoint, e.g. http://localhost:4318. Traces include http.request, db.query, notify.enqueue, and auth.resolve_key spans.

Rate limits

Two independent limits apply:

• /a2a per agent: 60 requests/minute by default (RELAY_RATE_LIMIT_PER_MIN). Each agent’s key has its own bucket. Exceeding returns -32003 rate_limited with a Retry-After header.
• /admin/* per admin token: 5 requests/minute, fixed. Exceeding returns 429 with a Retry-After header.

Generating secrets

For a production deployment, regenerate all secrets before your first docker compose up:

# RELAY_PEPPER — at least 32 bytes, must stay stable after first use
openssl rand -hex 32

# RELAY_ENCRYPTION_KEY
openssl rand -hex 16

# RELAY_ADMIN_TOKEN
openssl rand -hex 16

# RELAY_METRICS_TOKEN
openssl rand -hex 16

Store the generated values in your secret manager (e.g. Fly.io secrets, AWS Secrets Manager, Doppler) and inject them as environment variables at deploy time. Do not commit secrets to source control.