Relay docs

Configuration & secrets

Relay reads all configuration through the standard ASP.NET Core stack, so any value can be overridden without editing a committed file.

#Precedence

Highest wins:

  1. Command-line arguments
  2. Environment variables
  3. User-secrets (Development only)
  4. appsettings.{Environment}.json
  5. appsettings.json

In Development, appsettings.Development.json overrides appsettings.json.

#Secrets

Never commit real secrets. Supply them via environment variables (or Key Vault) in shared/production environments, and user-secrets locally.

  • Provider API keys are not stored in the database. Each Provider row holds a SecretRef — the name of a config key. At call time ConfigurationProviderSecretResolver reads config[secretRef] to get the actual key. So rotating a provider key is a config change, not a DB write.
  • Encryption master key (Encryption:MasterKey) — AES-256-GCM key that encrypts any at-rest secrets that do live in the DB (e.g. MCP auth tokens).

#Where each app reads config

  • Application.Api (gateway) reads ConnectionStrings:GatewayDb, the whole Gateway:* tree (routing, cache, moderation, RAG, batch/eval, health, alerts, OTLP), ClickHouse:*, Telemetry:*, Qdrant:*, and provider secrets by SecretRef.
  • Application (panel host) reads the SQL connections, Entra auth settings, and the same ClickHouse / Telemetry settings so the Dashboard/Telemetry pages can query.

#Common settings

A minimal gateway appsettings.Development.json:

{
  "ConnectionStrings": {
    "GatewayDb": "Server=127.0.0.1;Database=relay_gateway;Trusted_Connection=True;TrustServerCertificate=True"
  },
  "Gateway": {
    "DefaultModel": "gpt-4o",
    "FallbackModel": "gpt-4o-mini",
    "MaxRetries": 2,
    "Cache": { "TtlSeconds": 0 }
  },
  "Qdrant": { "Url": "http://127.0.0.1:6333" },
  "ClickHouse": { "ConnectionString": "Host=127.0.0.1;Port=8123;Username=default;Password=;Database=default" }
}

The full list of keys — routing, caching, moderation, RAG, batch/eval, health probing, alerting and OTLP — is in the Configuration reference.

#Telemetry backend

Telemetry:Backend selects how usage is stored and read:

  • clickhouse (default) — Relay writes its own usage table; the dashboard reads it.
  • otel — Relay emits standard OpenTelemetry over OTLP to ClickStack; the dashboard reads the otel_* tables.

See Telemetry & dashboards.