> ## Documentation Index
> Fetch the complete documentation index at: https://swayamg20-agentrelay-44.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
# 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
```

<Warning>
  `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.
</Warning>

## 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`:

```bash theme={null}
# 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.