Configuration reference

Every configuration key read by the gateway, with defaults where the code sets one. See Configuration & secrets for precedence and secret handling.

#Connections & hosting

Key	Default	Purpose
`ConnectionStrings:GatewayDb`	—	Gateway SQL database.
`Cors:PanelOrigins`	—	Allowed origins for the control-plane CORS policy.
`Seed:MockBaseUrl`	`http://localhost:8899`	Mock provider base URL used when seeding.

#Chat & agents

Key	Default	Purpose
`Gateway:DefaultModel`	—	Model used when a request omits one / team default.
`Gateway:FallbackModel`	—	Global default fallback, used only when a model declares no fallback of its own. Set a per-model fallback in Models → Edit → Fallback model instead — it takes precedence. See Model routing & fallback.
`Gateway:ModelAliases:{requested}`	—	Dynamic remap of a requested model name.
`Gateway:ToolMaxIterations`	`5`	Max MCP tool-loop iterations for agents.

#Routing & resilience

Key	Default	Purpose
`Gateway:MaxRetries`	`2`	Transient retry count.
`Gateway:RetryBaseDelayMs`	`250`	Retry backoff base.
`Gateway:CatalogCacheSeconds`	`10`	Model/provider catalog cache TTL.
`Gateway:BudgetRefreshMinutes`	`5`	Budget spend refresh interval.

#Response cache

Key	Default	Purpose
`Gateway:Cache:TtlSeconds`	`0` (off)	Response-cache TTL.
`Gateway:Cache:MaxEntries`	`5000`	Response-cache size cap.

#Moderation

Key	Default	Purpose
`Gateway:Moderation:Enabled`	`false`	Turn moderation on.
`Gateway:Moderation:Block`	`true`	Block flagged content vs. only flag.
`Gateway:Moderation:FlagJailbreak`	`true`	Detect prompt-injection / jailbreak.

#RAG

Key	Default	Purpose
`Gateway:Rag:HybridAlpha`	`0.5`	Dense vs. lexical blend weight.
`Gateway:Rag:MmrLambda`	`0.7`	MMR relevance/diversity tradeoff.
`Qdrant:Url`	—	Vector store endpoint.
`Qdrant:ApiKey`	—	Vector store key (if required).

#Dataset agents (SQL)

Reached by the gateway and, for the editor's picker only, by the panel host. Both hosts should carry the same BaseUrl and ApiKey — a mismatch means the picker lists a different company's datasets than a run resolves. See Dataset agents.

Key	Default	Purpose
`Gateway:Data:BaseUrl`	—	Data app base URL. Absolute http/https, no query or fragment; an invalid value fails at startup. In development use `https://localhost:7434` — the http port 307-redirects and redirects are not followed.
`Gateway:Data:ApiKey`	—	Data app API key. A secret — user-secrets / env / Key Vault. Carries the data app's company, so one key = one company for the whole instance.
`Gateway:Data:TimeoutSeconds`	`15`	Per-call timeout to the data app.
`Gateway:Data:ModelMaxRows`	`100`	Rows shown to the model.
`Gateway:Data:CallerMaxRows`	`1000`	Rows fetched, i.e. what the caller receives in `relay_dataset`.
`Gateway:Data:ModelMaxChars`	`20000`	Character budget for rows handed to the model.
`Gateway:Data:MaxIterations`	`6`	Query attempts per turn before the run fails with 422.
`Gateway:Data:CacheTtlSeconds`	`120`	Schema + grant cache TTL per (dataset, user). `0` disables — useful while editing grants.
`Gateway:Data:NegativeCacheSeconds`	`30`	How long "not accessible" is remembered, so a wrong id does not hammer the data app.
`Gateway:Data:CacheMaxEntries`	`500`	Schema cache size cap.
`Gateway:Data:SchemaMaxChars`	`24000`	Prompt budget for the schema block; past it the prompt switches to a table index.
`Gateway:Data:IndexColumnPreview`	`8`	Columns previewed per table in index mode.
`Gateway:Data:UserIdHeader`	`X-Relay-User-Id`	Header naming the acting end user. `X-User-Id` is always accepted as a fallback. Named under `Data:` because dataset agents introduced it, but it is Relay's single acting-user header — a non-public agent's audience check reads the same one.
`Gateway:Data:CatalogUserId`	—	Data-app identity used only to populate the panel's dataset picker.
`Gateway:Data:AllowInvalidCertificates`	`false`	Accept the data app's self-signed dev certificate. Honoured only in Development.

#Batch & eval processors

Key	Default	Purpose
`Gateway:BatchPollSeconds`	`10`	Batch queue poll interval.
`Gateway:BatchConcurrency`	`4` (1–32)	Batch row concurrency.
`Gateway:EvalPollSeconds`	`10`	Eval queue poll interval.
`Gateway:EvalConcurrency`	`4` (1–32)	Eval case concurrency.

#Health probing & alerting

Key	Default	Purpose
`Gateway:HealthProbe:Enabled`	`false`	Actively probe providers.
`Gateway:HealthProbe:IntervalSeconds`	`60`	Probe interval.
`Gateway:HealthProbe:TimeoutSeconds`	`5`	Probe timeout.
`Gateway:HealthProbe:AlertThreshold`	`2`	Consecutive failures before alert.
`Gateway:HealthProbe:WebhookUrl`	—	Slack-compatible alert webhook.
`Gateway:HealthProbe:AlertEmail`	—	Alert recipient.
`Gateway:HealthProbe:Smtp:Host` / `Port` / `UseSsl` / `From` / `User` / `Password`	`587` / `true`	SMTP for email alerts.
`Gateway:Alerts:Enabled`	`false`	Telemetry-threshold alerting.
`Gateway:Alerts:IntervalSeconds`	`300`	Alert evaluation interval.
`Gateway:Alerts:WindowMinutes`	`15`	Look-back window.
`Gateway:Alerts:ErrorRatePercent`	`10`	Error-rate threshold.
`Gateway:Alerts:P95LatencyMs`	`0` (off)	p95 latency threshold.

#Telemetry & OTLP

Key	Default	Purpose
`ClickHouse:ConnectionString`	—	Observability store (read/write). Set on the gateway and the panel. Empty = no telemetry.
`ClickHouse:ObservationTable` / `ScoreTable`	`relay_observation` / `relay_score`	Table names (created and evolved at startup).
`ClickHouse:FlushIntervalMs` / `BatchSize` / `Capacity`	`1000` / `500` / `10000`	Writer batching; events are dropped (never blocking) when the buffer is full.
`ClickHouse:QueryTimeoutSeconds`	`30`	Panel/API query timeout.
`Telemetry:DashboardSource`	—	`otel` reads the usage dashboard from the collector's `otel_traces` table instead of `relay_observation`.
`Telemetry:Backend`	—	Legacy; observations are always written when ClickHouse is configured. OTLP export is `Gateway:Otlp:Enabled`.
`Telemetry:Capture:Default`	`metadata`	Body capture when a workspace has no setting: `none`, `metadata`, `full`.
`Telemetry:Capture:RedactPii`	`true`	Default PII redaction of captured text.
`Telemetry:Capture:MaxBodyChars`	`20000`	Default per-field cap on captured text.
`Telemetry:RetentionDays` / `BodyRetentionDays`	`0` / `30`	Default row and captured-text retention (0 = keep).
`Telemetry:SettingsCacheSeconds`	`60`	How long the gateway caches a workspace's observability settings.
`Telemetry:Panel:ShowBodies`	`true`	Hide captured text in the panel (metrics still show).
`Gateway:Stream:IncludeUsage`	`true`	Ask OpenAI-compatible providers for streamed token usage.
`Gateway:EvaluatorPollSeconds` / `EvaluatorLagSeconds`	`60` / `30`	LLM-judge evaluator cycle, and how far behind "now" it reads.
`Gateway:AlertRules:IntervalSeconds`	`60`	Workspace alert-rule evaluation interval.
`Gateway:EndUserBudgetCacheSeconds`	`30`	End-user budget cache on the request path.
`Gateway:Otlp:Enabled`	`false`	Enable OTLP export.
`Gateway:Otlp:Endpoint`	`http://localhost:4318/v1/traces`	Traces endpoint (logs/metrics derived).
`Gateway:Otlp:LogsEndpoint` / `MetricsEndpoint`	derived	Override the derived endpoints.
`Gateway:Otlp:ServiceName`	`relay-gateway`	Service name on emitted signals.
`Gateway:Otlp:ApiKey`	—	HyperDX ingestion key (Authorization header).
`Gateway:Otlp:MetricsIntervalSeconds`	`30`	Metrics export interval.

#Secrets

Key	Purpose
`Encryption:MasterKey`	AES-256-GCM key for at-rest secrets in the DB.
`config[<SecretRef>]`	Each provider's API key, resolved by the `SecretRef` name stored on the Provider row.