Validated in the full merge-train on the .113 (lot 5, 2026-11-12): typecheck, static gates and the full unit suite. Every failure from that run was re-run in isolation, both on the merged tree and on the train base. They come from the .113 root environment, load-sensitive timing, or known flakes. None trace back to this change. Co-authored-by: Dizzle <112548150+maxmad64bis@users.noreply.github.com>
94 KiB
title, version, lastUpdated
| title | version | lastUpdated |
|---|---|---|
| Feature Flags | 3.8.52 | 2026-10-05 |
Feature Flags
Runtime toggles that change OmniRoute's behavior without a redeploy. Every flag listed here is defined in
src/shared/constants/featureFlagDefinitions.ts— the single source of truth. The dashboard and the REST API both read from that file, so the table below is generated to match it 1:1.
What Feature Flags Are
A feature flag is a named toggle (boolean or enum) whose value can be changed at
runtime and persisted in the database, with no process redeploy required. Each
flag is described by a FeatureFlagDefinition with a key, label,
description, category, defaultValue, type, and a requiresRestart hint.
Resolution Order
The effective value of a flag is resolved by
resolveFeatureFlag() with this
precedence (highest wins):
- DB override — a value stored in the
key_valuetable under thefeature_flagsnamespace (set via the dashboard or the REST API). - Environment variable —
process.env[<KEY>], if set and non-empty. - Definition default — the
defaultValuefromfeatureFlagDefinitions.ts.
A boolean flag is considered enabled when its effective value is "true",
"1", or "yes" (see isFeatureFlagEnabled()).
Note
Most flags also have a matching environment variable of the same name documented in
ENVIRONMENT.md. The flag's DB override takes precedence over that environment variable. A flag withrequiresRestart: trueis persisted immediately but only re-read at process startup — toggling it surfaces a "Restart Server" banner in the dashboard.
Flag Catalog
122 flags across 6 categories. Default is the definition default — the value used when neither a DB override nor an environment variable is present.
Security (11)
| Key | Type | Default | Description |
|---|---|---|---|
REQUIRE_API_KEY |
boolean | false |
Require an API key for all incoming requests. |
INPUT_SANITIZER_ENABLED |
boolean | true |
Enable input sanitization for all requests. |
INJECTION_GUARD_MODE |
enum | off |
Prompt injection guard mode. Values: off, warn, block, redact. |
PII_REDACTION_ENABLED |
boolean | false |
Redact PII from requests (independent of INPUT_SANITIZER_MODE). |
PII_RESPONSE_SANITIZATION |
boolean | false |
Sanitize PII from provider responses. |
PII_RESPONSE_SANITIZATION_MODE |
enum | redact |
Mode for PII response sanitization. Values: redact, warn, block, off. |
OUTBOUND_SSRF_GUARD_ENABLED |
boolean | true |
Legacy alias: a value saved on this flag's dashboard toggle is read before the environment; false, 0, no, or off in either turns the outbound URL guard's host checks off like OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS. |
ALLOW_API_KEY_REVEAL |
boolean | false |
Allow authenticated dashboard users to reveal stored API keys instead of only seeing masked values. |
AUTH_LOG_INCLUDE_ACCOUNT_ID |
boolean | false |
Include account prefix in AUTH log lines (e.g. "Using account: abc12345..."). Disabled by default so account identifiers are redacted from shared/multi-tenant process logs. Independent from Debug Mode; flipping Debug Mode does not reveal this. |
OMNIROUTE_OIDC_DISABLE_PASSWORD_LOGIN |
boolean | false |
When OIDC is enabled, disable password login so users can only authenticate via OIDC Single Sign-On. When disabled (default), both password login and OIDC are available. |
API_KEY_AUDIT_CLIENT_DETAILS_ENABLED |
boolean | false |
Record the caller's IP address and user-agent on the api_key.auth.touch audit-log rows written for successful API-key metadata and discovery reads (#17982). Off by default: those rows still record which key was used, when, and on which path, without IP or user-agent. |
Network (32)
| Key | Type | Default | Restart | Description |
|---|---|---|---|---|
ENABLE_TLS_FINGERPRINT |
boolean | false |
✓ | Enable TLS fingerprint stealth mode. |
AUDIO_REMOTE_PROVIDER_NODES |
boolean | false |
Allow the /v1/audio/* routes to use OpenAI-compatible provider nodes hosted outside localhost. Off by default — routing audio to a remote host changes egress identity and must be an explicit operator decision. Loopback nodes are always allowed and unaffected. | |
RERANK_REMOTE_PROVIDER_NODES |
boolean | false |
Allow POST /v1/rerank (and the memory engine's loopback rerank step) to use OpenAI-compatible provider nodes hosted outside localhost. Off by default — routing to a remote host changes egress identity and must be an explicit operator decision. Loopback nodes are always allowed; remote nodes must also pass the provider outbound URL policy. | |
PROXY_AUTO_SELECT_ENABLED |
boolean | false |
When no proxy is assigned to a connection, auto-select the first working proxy from the registry. Off by default (otherwise any registry proxy becomes a global fallback — #3332). | |
OMNIROUTE_CONTROL_PLANE_PROXY_DIRECT_FALLBACK |
boolean | false |
Allow OAuth and provider validation flows to bypass a pinned proxy and connect directly when proxy reachability pre-checks fail. Off by default because this can change egress IP. | |
NETWORK_ROTATION_SHARED_EGRESS_GUARD |
boolean | true |
On a network exception (timeout, connection refused/reset) for a multi-account rotation executor, when the failing account has no dedicated proxy, apply a short cooldown and skip other proxy-less accounts for the rest of the request instead of retrying each one. On by default (safe: no egress IP change, only reduces latency/cooldown risk on shared-egress accounts). Disable to restore immediate propagation on the first proxy-less throw. | |
ROTATION_ATTRIBUTION |
boolean | false |
Opencode rotation records which account served or was skipped (masked ids only, never full account ids) and links proxy log entries to their request, so the operator can tell skipped accounts apart from unused ones. Off by default. | |
PROXY_SKIP_RECENTLY_FAILED |
boolean | true |
Proxy pools and the per-account rotation of opencode stop re-serving a proxy that just failed (refused TCP probe, or a 429 received through it) for a per-process period that doubles on each repeat, up to a cap. No proxy status is written; with every candidate set aside the choice is unchanged. On by default; false restores plain selection. |
|
PROXY_POOL_SHARED_EGRESS_ORDER |
boolean | false |
For providers whose quota is bucketed by egress address, rank a pool member sharing a recently refused member's observed egress address just below healthy members. Order only, never excluded. Needs PROXY_SKIP_RECENTLY_FAILED, which produces the refusal signal it reads. Off by default. | |
PROXY_REFUSAL_MODEL_SCOPE |
boolean | false |
Scope an opencode quota 429 to the model that hit it, so the same egress keeps serving other models, and clear it only when that model succeeds. Readers with no model (pool rotation, park and replay, admin visibility, selector trigger, health sweep) still see it. Needs PROXY_SKIP_RECENTLY_FAILED, which produces the refusal. Off by default: one model's quota 429 sets the egress aside for every model. | |
PROXY_STRICT_POST_REPLAY_ENABLED |
boolean | false |
For a non-idempotent request (POST, PUT, PATCH, DELETE), resend after a transport error (fresh socket, proxy fallback, native fallback) only when the error proves nothing was sent: ECONNREFUSED, ENOTFOUND, EAI_AGAIN, ENETUNREACH or a connect timeout. A socket error after the write can mean the upstream accepted the request, so a resend could generate and bill it twice. Off by default: a replayable body is resent once on any transport error, which also recovers a stale pooled socket. | |
PROXY_POOL_EGRESS_OBSERVATION |
boolean | false |
Show, under a proxy pool in the dashboard, how many observed egress IPs served its members over the last 24 h and how many connections used them. Read-only, computed from the proxy log, never used for routing. Off by default. | |
PROXY_OPERATOR_EGRESS_ENABLED |
boolean | false |
Accept operator-pushed dated observed addresses per pool member and merge them with the journal read for display and pool order. Off by default: the push route answers 404 and pool reads behave exactly as before. | |
OPENCODE_RESPONSES_STALL_ROTATION |
boolean | false |
For the OpenCode executor, watch the first body byte of a streamed Responses reply (window: RESPONSES_FIRST_BYTE_TIMEOUT_MS, default 15000). A 2xx Responses stream that stays silent past the window is treated as stalled: the account is cooled down and the request rotates to the next account once; a second stall fails fast. Off by default: stalled streams keep today's wait until the stream readiness timeout. |
|
OPENCODE_USER_BLOCKED_ROTATION |
boolean | false |
OpenCode executor: on a 403/451 carrying a user_blocked refusal (not geo, not a Cloudflare fingerprint rejection), cool the refused account down and rotate to the next account at most once per request; a second refusal is returned as-is, without a success mark. Off by default: routing around an upstream user block can look like evasion and spread the flag across the fleet. |
|
OPENCODE_TRANSIENT_FAILOVER_BACKOFF |
boolean | false |
OpenCode rotation: after two consecutive transient upstream failures (5xx or an empty 400), pause before the next account — 1.5s doubling per further failure, capped at 6s per pause and 10s per request, skipped on client disconnect; the failed body is released before waiting. Off by default: failover stays immediate. | |
OPENCODE_PARK_AND_RESUME |
boolean | false |
OpenCode rotation: park the request after repeated transient 429s (or a fresh pool-strain marker) with a heartbeat, then replay one capped leg of up to 3 sequential accounts instead of fanning out the whole fleet. Off by default: every 429 rotates to the next account exactly as before. | |
STREAM_READINESS_STALL_RETRY |
boolean | false |
Streaming chat: when the first upstream body stalls before producing a usable event, issue one bounded second attempt through the same routing path with the same readiness budget and no account penalty. Off by default: a stalled first body fails the request without a retry. | |
FLUSH_EMPTY_RETRY_ENABLED |
boolean | false |
On translated streaming turns, when the upstream turn carries no usable content (reasoning-only completion or zero valuable chunks), issue bounded retries through the normal credential path (up to STREAM_RECOVERY.EMPTY_TURN_RETRY_MAX) before anything is exposed to the client. Off by default: empty turns keep the current behavior (empty 200 or empty-content 502). |
|
EMPTY_STREAM_SIBLING_RECOVERY_ENABLED |
boolean | false |
Claude/Codex streaming: after the first lifecycle event, briefly probe (up to 1s / 64 KiB) for usable output; a stream that ends with no content becomes an empty_content failure that spends the existing bounded retry on another eligible connection (no cooldown, no model lockout), and round-robin combos stop retrying once the client disconnects. Also treats refusal, pause_turn and model_context_window_exceeded as legitimate empty terminals inside the probe. Off by default: readiness, empty-content handling and combo retries stay exactly as before. |
|
OPENCODE_POOL_RESELECT |
boolean | false |
OpenCode rotation: after a 429 from an egress-bucketed provider on a proxy-less account under an ambient pool context, ask the connection pool for another member for the next attempt instead of retrying the same egress address. Orders, never excludes: an exhausted pool keeps the current behavior. Off by default: every 429 rotates to the next account exactly as before. | |
OPENCODE_FREE_TIER_EGRESS_PROBE |
boolean | false |
OpenCode executor: when a proxied request is answered 403/451 FreeTierError and the observed-tools retry failed or did not apply, replay it once through a different proxy (another account proxy or pool member, never a direct connection). Only a 200 on that probe sets the first egress aside in the proxy refusal memory and serves the probe; when both refuse, the original refusal is returned and nothing is recorded. Off by default: the refusal is returned unchanged. |
|
OPENCODE_RATE_LIMITED_429_EARLY_STOP |
boolean | false |
OpenCode rotation: stop the account wave at the first 429 classified as a real rate limit (parseable Retry-After, or a body naming a rate/usage limit) and return that upstream 429 unchanged. Unclassified 429s keep rotating. Off by default: the free tier is limited per egress IP (#9611), so every 429 rotates and an exhausted wave returns the last upstream 429. |
|
MITM_DISABLE_TLS_VERIFY |
boolean | false |
✓ | Disable TLS certificate verification for the MITM proxy. Danger. |
OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS |
boolean | false |
Turns off the outbound URL guard's host checks, cloud-metadata block included, on provider URL validation, model discovery, provider-node base URLs, and the proxy-fallback test, and allows private webhook targets. Local and LAN URLs already pass by default on the validation, discovery, and provider-node paths (OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS); the proxy-fallback test and private webhook targets consult only OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS and block local/LAN hosts while it is off. |
|
OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS |
boolean | true |
Allow provider URLs on local/private addresses (127.0.0.1, localhost, LAN). On by default (local-first): the guard then blocks cloud-metadata endpoints (all of 169.254.0.0/16 plus the known metadata hostnames). Disable for strict public-only blocking: private and loopback hosts are blocked too. | |
ENABLE_CC_COMPATIBLE_PROVIDER |
boolean | false |
✓ | Enable Claude Code compatible provider mode. |
STREAM_LATE_OUTPUT_PROBE_ENABLED |
boolean | false |
Streaming output probe: after the first 64 forwarded chunks keep sampling one chunk in 16 for the first visible output, so output that starts late still marks the stream as having emitted output. A lone 5xx after that point then stays request-scoped instead of recording a model-only lockout, and firstOutputMs is back-filled to the first output chunk of the current sampling gap. Off by default: only the first 64 forwarded chunks are probed, exactly as before. |
|
OPENCODE_ZEN_EGRESS_IP_LOCK_ENABLED |
boolean | false |
Add opencode-zen to the default egress-IP lockout family: a 429 on one Zen connection also cools every sibling Zen connection sharing its egress IP (#16797). Off by default: each Zen connection cools down on its own, as before. An explicit OMNIROUTE_EGRESS_IP_LOCK_PROVIDERS value always wins. |
|
OPENCODE_FULL_TEXT_ERROR_RULES_ENABLED |
boolean | false |
The built-in OpenCode error rules (opencode-zen, opencode-go, opencode-cli) match on the full upstream error text, so body markers such as organization_quota_exceeded or "monthly usage limit reached" classify a 429 as quota exhausted with a connection-scoped lock (#16797). Off by default: the rules only see the structured error code, as before. |
|
CLOUDFLARE_AI_FULL_TEXT_ERROR_RULES_ENABLED |
boolean | false |
The built-in Cloudflare Workers AI error rule matches on the full upstream error text, so the 429 "daily free allocation" body is classified as quota exhausted instead of a short rate limit (#16797). Off by default: the rule only sees the structured error code, as before. | |
| ----------------------------------------------- | ------- | ------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
OPENCODE_V2_CLIENT_FINGERPRINT_ENABLED |
boolean | false |
OpenCode Zen/Go: send the OpenCode v2 CLI client fingerprint (#16571) — User-Agent opencode/latest/<2.x>/cli, x-opencode-client: cli, a client User-Agent kept only when it is a 2.x OpenCode client; on gated free-tier requests no x-opencode-request, the session mirrored onto x-opencode-session-id/x-session-affinity/x-session-id, the v2 CLI read/shell schemas on injected placeholder tools and a tool_choice of "none" dropped. Off by default: identity, headers and body unchanged. |
Policies (8)
| Key | Type | Default | Description |
|---|---|---|---|
UNPRICED_USAGE_BUDGET_POLICY |
enum | fail_closed |
How per-key daily/weekly USD limits treat usage whose provider/model has no pricing row. fail_closed (default) marks the window as exceeded (#12341); count_as_zero counts it as $0 and keeps enforcing priced spend. Values: fail_closed, count_as_zero. |
TOOL_POLICY_MODE |
enum | disabled |
Tool-use policy enforcement mode. Values: disabled, warn, block. |
RATE_LIMIT_AUTO_ENABLE |
boolean | false |
Force the auto-enable rate-limit safety net on/off via the env var. The runtime reads only the env var: unset follows the dashboard setting (default on), not this catalog default. |
DISABLE_CONTEXT_WINDOW_CHECKS |
boolean | false |
Skip OmniRoute's local context-window / max-input-token check for direct single-model requests. Upstream limits still apply. |
CAPABILITY_FILTER_ENABLED |
boolean | false |
Reject requests before dispatch when the target model lacks required capabilities (vision, tools, structured output, context window). Protects direct single-provider requests that bypass the combo-layer compatibility filter. |
USAGE_LIMIT_IGNORE_UNPRICED |
boolean | false |
Count usage of models that have no price as $0 in per-key USD usage quotas instead of treating the quota as exceeded. Off by default: an unpriced model or routing alias can hide real spend, so the quota fails closed. |
RADAR_ENABLED |
boolean | false |
Enable the OmniRoute Radar module (catalog feed screens and sync). Off by default; enabling only unlocks the UI — data sync remains a separate opt-in. |
MODEL_ENDPOINT_CAPABILITY_GATE_ENABLED |
boolean | false |
Enforce trusted model endpoint tags (provider-declared, inferred from a specialty model id, or operator-set): reject a request sent to an endpoint the model does not serve with HTTP 400 before dispatch on /v1/chat/completions, /v1/embeddings, /v1/rerank, /v1/images/generations, /v1/videos/generations, /v1/music/generations and /v1/audio/*; hide models whose tagged endpoints have no OmniRoute adapter from /v1/models; answer the dashboard model test with 422 for them (#16929). Off by default: endpoint tags stay informational and dispatch is unchanged. |
When UNPRICED_USAGE_BUDGET_POLICY is explicitly configured (DB override before environment),
it takes precedence over USAGE_LIMIT_IGNORE_UNPRICED. With no explicit enum value, the
upstream boolean opt-out selects count_as_zero; otherwise the default is fail_closed.
Invalid enum values and unreadable feature-flag storage fail closed. Neither opt-out relaxes
priced spend or a failed pricing lookup. Enforcement and the administrator report resolve the
same effective policy.
Runtime (59)
| Key | Type | Default | Restart | Description |
|---|---|---|---|---|
UNIVERSAL_CONTEXT_HANDOFF_ENABLED |
boolean | true |
Generate and inject conversation summaries when combo routing switches models. Disable to treat model switches independently and prevent background handoff requests for all existing and future combos. | |
REASONING_REPLAY_ENABLED |
boolean | true |
Cache and replay model reasoning across multi-turn conversations. Disable to stop storing and re-injecting reasoning. | |
RESPONSES_PASSTHROUGH_DROP_COMMENTARY |
boolean | true |
Drop internal commentary-phase output items from Responses API passthrough streams before forwarding to clients. Disable to receive raw upstream commentary. | |
OMNIROUTE_MCP_ENFORCE_SCOPES |
boolean | false |
Enforce scope restrictions on MCP tool access. | |
OMNIROUTE_MCP_COMPRESS_DESCRIPTIONS |
boolean | false |
Compress MCP tool descriptions to reduce token usage. | |
OMNIROUTE_ENABLE_RUNTIME_BACKGROUND_TASKS |
boolean | false |
Enable background task processing at runtime. | |
OMNIROUTE_DISABLE_BACKGROUND_SERVICES |
boolean | false |
✓ | Disable all background services: quota refresh, provider-limits sync, connection recovery, credential health, cloud/model/free-proxy/proxy-health sync, retention cleanup, scheduled VACUUM, settings hot-reload poll. On a long-running install, connections do not auto-recover and the database keeps growing. |
OMNIROUTE_RTK_TRUST_PROJECT_FILTERS |
boolean | false |
Trust project-level RTK filters without validation. | |
OMNIROUTE_ENABLE_LIVE_WS |
boolean | true |
✓ | Start the real-time dashboard WebSocket server on import (port 20132 by default). |
OMNIROUTE_CODEX_WS_ENABLED |
boolean | true |
Allow Codex to use the Responses-over-WebSocket transport. When off, Codex falls back to HTTP Responses. | |
OMNIROUTE_CODEX_APP_SERVER_ENABLED |
boolean | true |
Allow Codex to use the local app-server WebSocket JSON-RPC transport (codexTransport=app-server). When off, connections opted into app-server fall back to Codex's other transports. | |
OMNIROUTE_EMERGENCY_FALLBACK |
boolean | true |
Route budget-exhausted requests to the emergency free fallback provider/model. (See Emergency Budget Fallback below.) | |
STREAM_RECOVERY_ENABLED |
boolean | false |
Enable transparent early retry for truncated upstream SSE streams before any response bytes reach the client. | |
STREAM_RECOVERY_MIDSTREAM_ENABLED |
boolean | false |
Allow stream recovery to re-request and stitch a response after bytes have already reached the client. | |
STREAM_RECOVERY_TOOLCALL_ORDER_FIX |
boolean | false |
Make mid-stream continuation tool-call safe: never resume a cut stream once a tool call was emitted (in flight or already finished with finish_reason tool_calls), and close after one empty continuation instead of spending the whole budget. Off: release behavior. | |
STREAM_EARLY_EOF_SIBLING_FAILOVER_ENABLED |
boolean | false |
Fail over once to a sibling connection when an SSE stream closes before emitting any useful frame and the bounded same-connection retry is spent; with no usable sibling the original STREAM_EARLY_EOF 502 is returned. Off by default: early-EOF stays terminal after the same-connection retry. |
|
MODEL_CATALOG_INCLUDE_NAMES |
boolean | true |
Include display-friendly name fields in /v1/models responses. Disable for clients that expect model IDs only. |
|
MODELS_CATALOG_PREFIX_MODE |
enum | dual |
Controls how model IDs are prefixed in /v1/models. 'dual' (default) emits both alias and canonical provider-id prefixes for backward compatibility. 'alias' emits only the short alias prefix (e.g. ds-web/model, not deepseek-web/model). 'canonical' emits only the full provider-id prefix. Values: dual, alias, canonical. |
|
ARENA_ELO_SYNC_ENABLED |
boolean | true |
Enable periodic Arena AI leaderboard ELO sync for model intelligence rankings. | |
EXPOSE_CC_DISCOVERY_ALIASES |
boolean | false |
Advertise claude/<provider>/<model> mirror ids on /v1/models so Claude Code gateway model discovery lists non-Claude models. Global level of the three-level gate (env wins over the dashboard override). See Claude Code configuration. |
|
NO_THINKING_ALIAS_ENABLED |
boolean | true |
Master switch for the no-think// gateway aliases. On (default): /v1/models advertises a no-thinking variant for every eligible thinking-capable Claude model, and a no-think/ id sent on a request resolves back to the real model with reasoning suppressed. Off: no variants are advertised and a no-think/ id is treated like any other unknown model id. The per-model ModelSpec.noThinkingAlias opt-in/opt-out still applies while this is on. | |
OMNIROUTE_DISABLE_THINKING_LEVEL_VARIANTS |
boolean | false |
Disable the generation of thinking level variants (e.g. -low, -medium, -high) in the /v1/models catalog. | |
OMNIROUTE_CHAT_VIRTUAL_LANES |
boolean | false |
✓ | Enable per-tenant adaptive virtual admission lanes for provider dispatch (#9654): one tenant's burst no longer 503s another. The OMNIROUTE_CHAT_VIRTUAL_LANES env var wins over this dashboard override; changes take effect at server restart. |
EXPOSE_FUNCTIONAL_GATEWAY_MIRRORS |
boolean | false |
Advertise / mirror ids on /v1/models for models whose canonical owner has no active credential but a passthrough gateway with an active credential routes them. Warning: adds catalog entries for all clients when enabled globally. | |
NEWAPI_AGGREGATOR_BALANCE |
boolean | false |
Enable balance detection for New-API / One-API / Sub2API aggregator compatible nodes. When enabled, compatible nodes with the aggregator flag set will report their balance in the dashboard and quota-preflight routing. | |
SERVER_OWNED_TOOL_LOOP_ENABLED |
boolean | false |
Continue non-streaming server-owned tool calls until the model returns a client-usable response. | |
SEARCH_STATS_HIDE_DELETED_CONNECTIONS |
boolean | false |
Search stats and recent searches only count providers that still have a live connection (keyless providers such as duckduckgo-free always count). Off keeps every retained search row with a provider id. | |
FREE_BADGE_REQUIRES_PROVIDER_FREE_TIER |
boolean | false |
Dashboard provider pages: show the Free badge only on signals the provider honors — drops the display-name heuristic, non-boolean free fields and :free suffixes on registered providers without a documented free tier. Off keeps the historical badge rule. | |
RETRY_AFTER_PROVENANCE_ENABLED |
boolean | false |
On aggregated 429/503 unavailable responses, omit Retry-After when no concrete future retry time is known (instead of a synthetic 1s), add error.retry_after_provenance (signal | none), and let combo drain paths read prose retry hints from JSON and plain-text upstream bodies. The field only appears on responses built by unavailableResponse(); other 429/503 bodies are unchanged. |
|
PROTECTED_PRIORITY_INFRA_502_ENABLED |
boolean | false |
When a priority combo target marked fallback-only-on-quota-exhaustion stops the combo for a cause that is provably not quota (provider circuit breaker open, predictive latency skip), answer 502 instead of the quota-looking 503. Lockout, cooldown, unavailable, exhaustion and concurrency-cap stops keep 503. |
|
MISTRAL_AMBIGUOUS_401_SOFT_LOCKOUT |
boolean | false |
A bare Mistral 401 ({"detail":"Unauthorized"}, no explicit auth signal) is identical for a revoked key and for exhausted quota. When on, it cools the connection down instead of parking it as expired, at most 3 times per hour per connection; the next one parks it, so a revoked key still converges. Off by default: every bare Mistral 401 parks the connection as before. |
|
GROK_SUBSCRIPTION_IMAGES_ENABLED |
boolean | false |
Register xai-oauth (xao) and grok-cli image routes and map OpenAI quality high/hd to xAI medium. Off by default: the API-key xAI image path stays on the existing OpenAI-compatible request and the subscription routes are not registered. | |
XAI_OAUTH_LIVE_MODEL_DISCOVERY |
boolean | true |
Fetch the live xAI model catalog for xai-oauth connections from https://api.x.ai/v1/models using the OAuth bearer token, instead of the frozen static seed. On by default. Set the flag to false to keep serving the static seed. HTTP failures fall back to the seed in the discovery route; the flag getter itself does not issue HTTP. | |
BATCH_AND_FILE_AUTO_CLEANUP_ENABLED |
boolean | false |
Let the automatic cleanup sweep delete terminal (completed/failed/cancelled/expired) Batch API jobs older than OMNIROUTE_BATCH_RETENTION_DAYS, along with their per-line checkpoints, and clear the BLOB content of uploaded files past their own expires_at. Off by default: every existing install keeps this data exactly as before until an operator opts in. The operator-triggered DELETE /api/v1/batches/delete-completed route is unaffected either way — it is a separate, unconditional public API contract. |
|
ANTIGRAVITY_ACCOUNT_LEASE_ENABLED |
boolean | false |
Reserve the selected Antigravity account for the streaming lifecycle of the request that picked it, so a concurrent retry or the credential handoff cannot re-pick an account already committed to an in-flight stream. The reservation is scoped to (connection, callable upstream model), so one account can still serve two different models at once. When every eligible account is already leased for that model, the request returns a structured 503 antigravity_pool_busy with a bounded Retry-After instead of piling onto a busy account. Off by default: account selection stays exactly as before, and no reservation is taken. |
|
COMBO_AUTO_PRUNE_STALE_STEPS |
boolean | false |
After a successful model sync against an authoritative live catalog, remove combo steps pinned to models the catalog no longer lists, with one audit entry per removed step. Never prunes on a failed, degraded or free-only sync, and never empties a combo. Off by default: stale steps are only flagged. | |
OPENCODE_PUBLISHED_CATALOG_ROUTING_ENABLED |
boolean | false |
OpenCode Zen / Go key-based requests follow the base URL and request surface (Responses for @ai-sdk/openai, Messages for @ai-sdk/anthropic) published in models.opencode.ai/api.json (read in the background, 6 h TTL, through the proxy-aware fetch), relay every client x-opencode-* header except x-opencode-org-id, and replay the tool parameter schemas the client already sent and the upstream accepted. Off by default: the registry base URL, heuristics, four known headers and placeholder schemas behave exactly as before and the catalog is never fetched. |
|
| ---------------------------------------------- | ------- | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
COMBO_EMPTY_POOL_NO_ELIGIBLE_TARGETS_ENABLED |
boolean | false |
When an auto combo's candidate pool is already empty before the tool-calling pre-filter runs (every target skipped by cooldowns, lockouts or exhaustion), answer 503 no_eligible_targets instead of the legacy 400 "No target supports tool calling" capability_mismatch (#14313). Off by default: the empty pool keeps the legacy 400. |
|
CLAUDE_OAUTH_SUMMARIZED_THINKING_UNREDACTED |
boolean | false |
Let a Claude OAuth request that asks for readable thinking (thinking.display: "summarized") drop the redact-thinking-2026-02-12 Anthropic beta, which otherwise makes Anthropic return empty, signature-only thinking blocks. Off by default: that beta is part of the Claude Code OAuth wire fingerprint, so OAuth requests keep it unchanged. API-key Claude requests already honor summarized thinking without this flag; OMNIROUTE_REDACT_THINKING=false also reaches OAuth only when this flag is on. |
|
KIRO_TOOL_CALL_REPAIR_ENABLED |
boolean | true |
When a streaming Kiro response emits a malformed tool_call wrapper (missing input.name or input.arguments) before any visible output, suppress it and re-send the request once with a corrective instruction instead of ending the turn with invalid_kiro_tool_call. The retry costs one extra Kiro request; a second failure ends the turn with kiro_tool_call_repair_retry_failed. On by default. Set to false to fail the turn on the first malformed wrapper. |
|
CATALOG_MIRROR_REFINEMENTS_ENABLED |
boolean | false |
Refine the claude/ discovery and functional-gateway mirrors on /v1/models. Off by default: both mirror passes behave exactly as before. On: claude/ discovery mirrors also cover listed reasoning-effort variants (-low/-medium/-high/-xhigh), skip built-in auto/* ids the request path cannot materialize and skip an alias already listed; functional-gateway mirrors skip combos and OmniRoute-synthesized ids (claude/, no-think/), take the owner from owned_by, never use the owner as its own gateway, skip gateways disabled in blockedProviders and models outside a gateway's authoritative live catalog. |
|
| ---------------------------------------------- | ------- | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
CLAUDE_CACHE_TAIL_TTL_1H |
boolean | false |
Mark the conversation tail that OmniRoute anchors for Claude prompt caching (the second-to-last user turn and the last assistant turn) with the same 1h TTL already used for system and tools, so a pause longer than five minutes does not rewrite the cached prefix. Vertex keeps the 5m TTL. Off by default: the tail keeps the 5m TTL exactly as before. A 1h cache write costs 2x the input price instead of 1.25x, so fast agent loops that never idle past five minutes pay more with this on. Client-managed (passthrough) markers are never changed. |
|
MODELS_DEV_EFFORT_TIERS_ENABLED |
boolean | false |
Use the reasoning effort tiers models.dev publishes (narrowed to the known effort vocabulary) when neither an operator override nor the provider registry declares any, and treat a declared empty tier list as "no tiers" in /v1/models effort_tiers and combo tier intersections. Off by default: effort_tiers and resolved supportedThinkingEfforts stay exactly as before. |
|
AUTO_REQUEST_RESOLVED_CAPABILITIES |
boolean | false |
auto/* requests build the candidate pool with resolved model capabilities (vision, reasoning, thinking) and observed quality scores in one bulk read (#16419). Off by default: request-time snapshot weights stay exactly as before. On: those signals feed the snapshot weights, so candidate weights and selection can change. | |
AUTO_COMBO_KEYLESS_TRANSPORT_GATE |
boolean | false |
Hold keyless (no-auth) providers whose transport needs a local browser (browserBacked) or a locally installed CLI (isLocalCli) out of the auto/* candidate pool, so a hung member cannot stall an auto request until the per-target timeout (#17036). Off by default: the keyless pool is unchanged. Direct <alias>/<model> calls work either way. |
|
CODEBUDDY_CN_INLINE_REASONING |
boolean | false |
For codebuddy-cn thinking models (DeepSeek-V4 / Kimi-K2 families that need reasoning replay), inline each replayed assistant reasoning_content as a visible <thought> block at the front of the message content, so it survives a gateway that drops the field (#13632). Off by default: requests are sent unchanged; reasoning_content itself is always kept. |
|
PROVIDER_SAFETY_STOPS_TERMINAL |
boolean | false |
Keep an explicit provider safety stop (misalignment_policy_violation, content_policy_violation, or the exact legacy "blocked by our safety systems" rejection labelled provider_safety_rejection) as a terminal, request-scoped refusal: its code is preserved through HTTP, Responses, WebSocket and completed-stream errors, and a combo stops at it instead of retrying other targets (#17049). Off by default: existing handling and routing are unchanged. |
|
LMARENA_SYNTHESIZED_CX_ENABLED |
boolean | false |
Attach a synthesized programmatic cx client-interaction blob (the value arena.ai itself sends for a page with no recorded interaction) to every Arena (lmarena) create-evaluation request that has no operator-supplied providerSpecificData.cx. Off by default: cx is an Arena anti-automation signal, so OmniRoute only forwards a value the operator captured from a real browser session (providerSpecificData.cx) and otherwise sends no cx at all. Unproven upstream benefit; enable only if Arena starts rejecting requests without cx. |
|
CONTENT_POLICY_REFUSAL_COMBO_STOP_ENABLED |
boolean | false |
When a combo target answers with an exact content-policy refusal (code/type cyber_policy or content_policy_violation), stop the combo and return that refusal even when the remaining targets are different models, instead of advancing to the next target (#15917). Off by default: the refusal never cools the account or trips the provider breaker, a same-model remainder still stops, and a heterogeneous combo advances to its next target exactly like any other request-scoped 400. |
|
NATIVE_CODEX_REACTIVE_COMPACTION_ENABLED |
boolean | false |
Let the reactive (threshold) and last-resort context compaction passes also rewrite native Codex passthrough histories (POST /v1/responses to the codex provider) when they exceed the context budget, using the Responses input[] adapter. Off by default: native Codex histories are owned by the Codex client and are never rewritten by compaction; oversized requests keep failing the context budget check exactly as before. Requires global compression to be on and the model not to be excluded. |
|
COOLDOWN_RETRY_SKIP_REFUSALS_ENABLED |
boolean | false |
When every account is cooling down and the cooldown that ends first was caused by a 403 (access refused) or a 410 (gone), return that refusal at once instead of waiting the cooldown out and re-sending the request (#16305). A renewing agentrouter connection-scoped quota 403 is then persisted with errorCode 429 so it stays retryable. Off by default: only a 401 skips the wait, and every refusal is persisted with the status it arrived with. |
|
QUOTA_WINDOW_BOUNDED_PARK |
boolean | false |
Let the per-window quota policy (session/weekly thresholds used by account selection) honour the bounded exhaustion park (#17000): once the capped park deadline has passed, or the cached observation is older than the park cap, the window stops excluding the account until a fresh quota fetch. Off by default: a cached window keeps blocking on its last reported percentage until its own reset time. | |
IMAGE_GENERATION_LONG_JOBS |
boolean | false |
For OpenAI-compatible image generation (#16260): use the connection timeout (providerSpecificData.timeoutMs), else the central upstream fetch timeout (FETCH_TIMEOUT_MS → REQUEST_TIMEOUT_MS → default 600 s) instead of the fixed 120 s image budget; answer 499 when the caller cancels; let the Playground receive long image jobs as an SSE stream with keepalive heartbeats. Off by default: the fixed budget applies and caller cancellation is not propagated. The deadline covering the response body read is always on. |
|
FAL_NATIVE_ENABLED |
boolean | false |
Enable the schema-driven Fal gateway (#18849): the /v1/fal routes, the /api/providers/{id}/fal schema routes, the Fal panel on the provider page, live Fal catalog discovery in the provider model list, and schema validation of Fal requests on the image, video and music routes. Off by default: those routes answer 404, the panel stays hidden, and Fal requests keep their established request shape, endpoint mapping and response format. |
|
CURSOR_GROK_47_DROP_MAX_EFFORT |
boolean | false |
Stop offering and forwarding the max reasoning effort for Cursor Grok 4.7 (#17386): Cursor's docs list only low/medium/high/xhigh, so the grok-4.7-max fallback alias disappears from the catalog and a max effort request is sent without an effort parameter. Off by default: max stays offered and forwarded, as a live AgentService/Run probe accepted it. |
|
RESPONSES_TRANSPORT_KEEPALIVE_ENABLED |
boolean | false |
Send Responses keepalives as a blank line instead of a response.in_progress event, so a synthetic snapshot can never replace the real response in the official SDK. A blank line dispatches no SSE event, so a client watchdog that resets only on events would not be reset during a long silent phase. Off by default: timers send the spec-valid response.in_progress event. | |
COMPRESSION_CACHE_AUTOMATIC_PREFIX_ESTIMATE |
boolean | false |
In the compression cache stats, count a compressed request to an automatic-prefix-caching provider (OpenAI, Codex, Azure, or a custom connection that declares prompt caching with marker stripping) as an estimated cache hit even without cache_control markers (#17114). The estimate is a cache-eligibility signal, not an observed hit, so the reported hit rate for those providers trends toward 100%. Off by default: only a request carrying cache_control markers to a caching provider counts as an estimated hit, so automatic-prefix providers keep reporting 0. |
|
CODEX_SEARCH_AUTO_FALLBACK_ENABLED |
boolean | false |
Let an automatic web search (no explicit provider) use a connected Codex (ChatGPT) account through codex-search: as the last resort ahead of the keyless providers when no credentialed search provider is usable, and as the failover alternate (#17933). Each such search spends ChatGPT subscription quota and takes about 10–40 s. Off by default: codex-search runs only when a request names it explicitly. |
|
CODE_ASSIST_INELIGIBLE_ONBOARD_LEGACY_TIER |
boolean | false |
For Antigravity / Code Assist onboarding, an account whose loadCodeAssist answer lists ineligibleTiers and marks no allowed tier as default onboards with legacy-tier instead of its currentTier (#18060), matching the Antigravity-Manager fetch_project_id order. Not yet confirmed on a real restricted account. Off by default: such an account keeps onboarding with its currentTier. |
CLI (5)
| Key | Type | Default | Restart | Description |
|---|---|---|---|---|
CLI_COMPAT_ALL |
boolean | false |
✓ | Enable compatibility mode for all CLI clients. |
MODEL_ALIAS_COMPAT_ENABLED |
boolean | false |
Enable model alias compatibility layer. | |
PRICING_SYNC_ENABLED |
boolean | false |
Enable automatic pricing data synchronization (also requires the PRICING_SYNC_ENABLED environment variable). |
|
OMNIROUTE_AUTO_SYNC_CODEX_PROFILES |
boolean | false |
After a provider model sync, automatically (re)write ~/.codex/*.config.toml profile files from the live catalog. Never changes the active/default Codex config. Off by default. | |
OMNIROUTE_AUTO_SYNC_CLAUDE_PROFILES |
boolean | false |
After a provider model sync, automatically (re)write ~/.claude/profiles//settings.json Claude Code profiles from the live catalog. Never changes the active/default Claude config. Off by default. |
Health (7)
| Key | Type | Default | Description |
|---|---|---|---|
OMNIROUTE_DISABLE_LOCAL_HEALTHCHECK |
boolean | false |
Disable the local instance health check endpoint. |
OMNIROUTE_DISABLE_TOKEN_HEALTHCHECK |
boolean | false |
Disable the token validation health check. |
SKILLS_SANDBOX_NETWORK_ENABLED |
boolean | false |
Enable network access in the skills sandbox environment. |
PROXY_HEALTH_BLOCKED_RESETS_STREAK |
boolean | false |
In the proxy health sweep, a probe the target refused (401/403/429) resets the proxy's consecutive-failure streak. Off by default: a refusal stays neutral (#10654). A 5xx stays inconclusive either way; a refusal never removes, disables or re-activates a proxy. |
DB_HEALTHCHECK_STARTUP_DEFERRED_ENABLED |
boolean | false |
Run the startup DB integrity/health check after the server starts accepting requests (via setImmediate) instead of blocking startup until it completes (#13717). Off by default: startup blocks exactly like before this PR. |
CREDENTIAL_HEALTH_RETEST_AUTO_DISABLED |
boolean | false |
Let the credential health sweep retest connections the gateway switched off by itself (marked autoDisabledAt; at most once per 6 h each and 5 per sweep) and switch one back on when its retest passes (#16190). Off by default: such connections stay off until an operator acts, exactly like before. Operator-disabled connections (operatorDisabledAt) and connections switched off after a permanent ban (banDisabledAt) are never retested. |
| ----------------------------------------- | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
CREDENTIAL_GATE_AUTH_DIAGNOSES_ONLY |
boolean | false |
Narrow the combo credential gate so a cached failed credential probe blocks a connection only when its diagnosis proves bad credentials (upstream_auth_error, auth_missing, token_expired, token_refresh_failed, reauth_required, account_deactivated, auth_required). Transport diagnoses (network_error, upstream_unavailable, upstream_rate_limited) always remain inconclusive and do not block dispatch, even when this flag is off. When enabled, other inconclusive diagnoses (ambiguous errors, unsupported probes and untyped scheduler errors) are also treated as unknown, allowing traffic. Off by default: other cached probe errors still block dispatch for the cache TTL (5 minutes). |
Note
INPUT_SANITIZER_BLOCK_THRESHOLDand its legacy aliasINJECTION_GUARD_BLOCK_THRESHOLDtune theblockmode ofINJECTION_GUARD_MODE, but they are plain environment variables read bysrc/shared/utils/injectionSeverity.ts, not feature flags: they have no DB override and no dashboard toggle. SeeENVIRONMENT.md.
Note
The
Restartcolumn marks flags withrequiresRestart: true— the value is persisted instantly but only takes effect after the process reloads. Enum flags reject any value outside their allowed set (validated server-side in bothsetFeatureFlagOverride()and the RESTPUThandler).
Toggling Flags
Dashboard
Navigate to Dashboard → Settings → Feature Flags
(/dashboard/settings/feature-flags). The grid
(src/app/(dashboard)/dashboard/settings/components/FeatureFlagsGrid.tsx)
supports:
- Search by key or description, and filter by category (plus a synthetic Requires Restart view).
- A toggle for boolean flags and a dropdown for enum flags
(
src/app/(dashboard)/dashboard/settings/components/FeatureFlagCard.tsx). - A source badge per flag —
DB,ENV, orDEF— showing where the effective value came from. - A Reset button (shown only for
DB-sourced flags) to drop the override, and a Reset All Overrides button at the bottom. - A Restart Server banner when a
requiresRestartflag is changed.
REST API
All operations go through a single route:
src/app/api/settings/feature-flags/route.ts.
Every method requires an authenticated dashboard session (401 otherwise).
With login disabled (requireLogin=false) the route is open, except for the
protected flags: every flag in the Security category plus
OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS, OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS,
MITM_DISABLE_TLS_VERIFY, OMNIROUTE_MCP_ENFORCE_SCOPES and
SKILLS_SANDBOX_NETWORK_ENABLED (isProtectedFeatureFlag() in
protectedFeatureFlags.ts). A PUT on one of them, and a DELETE while
one of them has a DB override, still needs a dashboard session, a
manage-scope API key, an oma_ access token with write scope or higher, or
the CLI token or internal-service token sent from loopback. That set is wider
than with login on, where the route accepts only a session or a manage-scope
key.
GET /api/settings/feature-flags
Returns every flag with its effective value, source, and a summary.
{
"flags": [
{
"key": "REQUIRE_API_KEY",
"label": "Require API Key",
"description": "Require an API key for all incoming requests",
"category": "security",
"type": "boolean",
"enumValues": null,
"defaultValue": "false",
"effectiveValue": "false",
"source": "default", // "db" | "env" | "default"
"requiresRestart": false,
"warningLevel": "caution",
},
// ... all 122 flags
],
"summary": {
"total": 122,
"active": 0,
"inactive": 0,
"overriddenByDb": 0,
"overriddenByEnv": 0,
},
}
PUT /api/settings/feature-flags
Set or remove a single override. Body: { key: string; value?: string }.
Omitting value removes the override (restoring env / default).
# Set a DB override
curl -X PUT http://localhost:20128/api/settings/feature-flags \
-H "Content-Type: application/json" \
-d '{"key":"REQUIRE_API_KEY","value":"true"}'
# Remove the override (no "value")
curl -X PUT http://localhost:20128/api/settings/feature-flags \
-H "Content-Type: application/json" \
-d '{"key":"REQUIRE_API_KEY"}'
The response echoes the new effectiveValue/source, the previousValue/
previousSource, and requiresRestart. Unknown keys and out-of-range enum
values are rejected with 400.
DELETE /api/settings/feature-flags
Clears all DB overrides at once, restoring every flag to its env / default
value. Returns { cleared: <count>, message: "..." }.
Note
Flags with
requiresRestart: trueonly take effect after a process reload. The dashboard's restart flow callsPOST /api/restartand then pollsGET /api/health/pinguntil the server is back up.
Emergency Budget Fallback
OMNIROUTE_EMERGENCY_FALLBACK (category runtime, default true) controls the
emergency free-fallback path in
open-sse/services/emergencyFallback.ts.
When enabled, requests that exhaust their budget are routed to a free fallback
provider/model instead of failing outright. Set it to false (or 0) — via the
dashboard toggle, a DB override, or the OMNIROUTE_EMERGENCY_FALLBACK
environment variable — to disable the behavior and let budget-exhausted requests
fail. (Surfaced as a dashboard toggle in PRs #3741 / #3752.)
A response served by this fallback carries
X-OmniRoute-Emergency-Fallback: from=<provider/model>; to=<provider/model>, so a
client can tell it was rerouted without diffing X-OmniRoute-Provider against its
request. The header is absent on every other response.
See Also
- Environment Variables Reference — most flags have a same-named environment variable documented there (the DB override takes precedence over it).
src/shared/constants/featureFlagDefinitions.ts— source of truth for every flag.src/shared/utils/featureFlags.ts— resolution logic (resolveFeatureFlag,isFeatureFlagEnabled,resolveAllFeatureFlags).src/lib/db/featureFlags.ts— DB override persistence in thefeature_flagsnamespace of thekey_valuetable.