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. The repo's docs/secrets.md has the list of what to move and a rotation runbook.

  • Provider API keys are stored encrypted at rest. A key pasted into the panel is encrypted with AES-256-GCM (Encryption:MasterKey) into Provider.ApiKeyEncrypted, decrypted by the gateway per call, and never returned to the browser. A Provider's SecretRef — the name of a config key, read by ConfigurationProviderSecretResolver at call time — is the fallback for a provider with no stored key, for teams that prefer rotating keys through configuration. A stored key wins over SecretRef; Ollama needs neither.
  • The encryption master key (Encryption:MasterKey, base64, 32 bytes) protects every at-rest secret: provider keys, the Azure discovery client secret, connector client secrets and users' OAuth tokens, workflow credentials and webhook tokens. It also derives the HMAC key for the Playground's panel-to-gateway delegation token. It must be identical on the Application host and on Application.Api, or decryption fails on one side.
  • MCP server bearer tokens are not encrypted today; treat the MCP registry accordingly.

#Where each app reads config

  • Application.Api (gateway) reads ConnectionStrings:GatewayDb, Encryption:MasterKey, the whole Gateway:* tree (routing, cache, moderation, files, RAG, data app, connectors, workflows, batch/eval, health, alerts, OTLP), ClickHouse:*, Telemetry:*, Qdrant:*, and any provider SecretRef.
  • Application (panel host) reads ConnectionStrings:GatewayDb and ConnectionStrings:UserManagementDb, the identity-app sign-in settings (Identity:BaseUrl, ClientId, ClientSecret, CallbackPath, Scope), Encryption:MasterKey, Gateway:InternalBaseUrl / Gateway:PublicBaseUrl (to reach the gateway for the Playground, workflow approvals and webhooks), Gateway:Data:* (the dataset picker), Qdrant:*, Connectors:RedirectUri, Telemetry:Panel:ShowBodies, EmailSettings:*, and the same ClickHouse:* / Telemetry:* settings so the dashboard and observability 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"
  },
  "Encryption": { "MasterKey": "<base64, 32 bytes — same value on the panel host>" },
  "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, files, RAG, dataset agents, connectors, workflows, batch/eval, health probing, alerting, telemetry and OTLP — is in the Configuration reference.

#Dashboard source and OTLP export

Relay always writes its observability store (relay_observation, relay_score) when ClickHouse:ConnectionString is set; the trace, session, score and evaluator pages depend on it. Two independent switches sit beside that:

  • Gateway:Otlp:Enabled — additionally export traces, logs and metrics over OTLP/HTTP to a ClickStack collector, so HyperDX shows the same trace tree.
  • Telemetry:DashboardSource — clickhouse (default) reads the usage Dashboard and Telemetry pages from relay_observation; otel reads those two pages from the collector's otel_traces table instead.

Telemetry:Backend, which older builds used for this, is no longer read; a value left in configuration is ignored. See Telemetry & dashboards.