Files
OmniRoute/.env.example

4389 lines
250 KiB
Plaintext
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# ┌─────────────────────────────────────────────────────────────────────────────┐
# │ OmniRoute — .env Contract │
# │ This file documents EVERY environment variable read by the runtime. │
# │ Copy to .env and adjust values. Lines starting with # are commented out │
# │ (optional / off-by-default). Uncomment only what you need. │
# │ Reference: docs/ENVIRONMENT.md for full details and usage scenarios. │
# └─────────────────────────────────────────────────────────────────────────────┘
# ═══════════════════════════════════════════════════════════════════════════════
# 1. REQUIRED SECRETS — Must be set before first run!
# ═══════════════════════════════════════════════════════════════════════════════
# These secrets are critical for security. Generate strong, unique values.
# JWT signing key for dashboard session tokens.
# Used by: src/lib/auth — signs/verifies all authenticated session cookies.
# Generate: openssl rand -base64 48
JWT_SECRET=
# Encryption key for API keys stored in the database.
# Used by: src/lib/db/apiKeys.ts — encrypts API key values at rest in SQLite.
# Generate: openssl rand -hex 32
API_KEY_SECRET=
# Initial admin login password — CHANGE THIS before first use!
# Used by: src/lib/auth/managementPassword.ts — sets the dashboard password at startup
# while none is saved yet; ignored once a password is saved.
# After first login you can change it from Dashboard → Settings → Security.
# CHANGEME (this template's value) is publicly known. npm and source installs copy this
# file to .env, so replace CHANGEME there before first boot, or set INITIAL_PASSWORD=
# (empty) there to create the password in the dashboard's onboarding wizard instead.
INITIAL_PASSWORD=CHANGEME
# ═══════════════════════════════════════════════════════════════════════════════
# 2. STORAGE & DATABASE
# ═══════════════════════════════════════════════════════════════════════════════
# OmniRoute uses SQLite for all persistence. These variables control where
# data lives, encryption, and cleanup policies.
# Base directory for all persistent data (SQLite DB, logs, backups).
# Used by: src/lib/db/core.ts — resolves the SQLite database file path.
# Default: ~/.omniroute/ | Override for Docker or custom installations.
# Hint: When running in Docker, consider mounting a host directory here for data persistence across container restarts
# also if you want to share the same database as "npm run dev" use "./data"
# DATA_DIR=/var/lib/omniroute
# Fallback alias for DATA_DIR, checked only when DATA_DIR is unset.
# Used by: open-sse/executors/promptql/threadSticky.ts — locates the PromptQL
# executor's on-disk thread-sticky session cache. Leave unset to rely on DATA_DIR.
# OMNIROUTE_DATA_DIR=/var/lib/omniroute
# Directory the runtime plugin scanner reads, overriding the home-derived default (#11827).
# Used by: src/lib/plugins/scanner.ts — getDefaultPluginDir(); it is also the root the
# plugin manager installs into. Set it in Docker/K8s to point straight at the bind-mounted
# plugin tree, instead of moving HOME (which changes every other HOME-relative behaviour)
# just to relocate the scan path. Unset = <HOME>/.omniroute/plugins, and
# /tmp/.omniroute/plugins when the process exports no home at all.
# Distinct from the CLI-only variable in section 9 that points the omniroute-cmd-* command
# loader (bin/cli/plugins.mjs) at a package tree — this one drives the server-side scanner.
# OMNIROUTE_PLUGINS_DIR=/opt/omniroute/plugins
# Escape hatch for the test/eval DATA_DIR guard (#10428). A test or node eval/print
# probe (-e/--eval/-p/--print, including --eval=/--print=) that never chose a DATA_DIR
# is redirected to a throwaway temp dir so it cannot open the operator's real database.
# Set to 1 only for a deliberate run against the real DATA_DIR — never for CI.
# Used by: src/lib/dataPaths.ts
# OMNIROUTE_ALLOW_DEFAULT_DATA_DIR=1
# Build provenance (#10427). OMNIROUTE_BUILD_SHA lets a container inject the artifact's git
# SHA when the dist/BUILD_SHA sentinel is absent; it is also what `npm run build:release`
# stamps. OMNIROUTE_RELEASE_REF is the ref the pack gate checks ancestry against, and
# OMNIROUTE_ALLOW_CANARY_BUILD=1
# API key the canary-deploy smoke uses when the target gateway requires auth (#10429).
# Used by: scripts/ops/deploy-canary.mjs — sent as `Authorization: Bearer` on the
# /v1/chat/completions probe. Never needed by the server itself.
# OMNIROUTE_SMOKE_API_KEY=sk-... records a deliberate off-release-line build instead of
# failing it. Used by: scripts/build/buildProvenance.ts, src/lib/monitoring/buildSha.ts
# OMNIROUTE_BUILD_SHA=abc1234
# OMNIROUTE_RELEASE_REF=origin/main
# OMNIROUTE_ALLOW_CANARY_BUILD=1
# Build-phase signal (#10060). Set to 1 by scripts/build/build-next-isolated.mjs and
# inherited by every spawned build worker so the DB layer returns a no-op stub instead
# of loading the native better-sqlite3 addon (which aborts the worker on exit).
# Never set this for the running server. Used by: src/lib/buildPhase.ts, src/lib/db/core.ts
# OMNIROUTE_BUILDING=1
# Skip the optional native-dependency prebuild check for exotic vendored trees.
# This does not make a missing dependency buildable. Used by: scripts/check/check-native-deps.mjs
# Default: 0 | Set to 1 only when native dependencies are supplied out of band.
# OMNIROUTE_SKIP_NATIVE_DEP_CHECK=0
# Encryption key for SQLite database encryption at rest.
# Used by: src/lib/db/encryption.ts — encrypts the entire SQLite database.
# Generate: openssl rand -hex 32 | Leave empty to disable DB encryption.
STORAGE_ENCRYPTION_KEY=
# Version tag for the encryption key — allows future key rotation.
# Used by: scripts/bootstrap-env.mjs, electron/main.js — persists key version.
# Default: v1 | Increment when rotating STORAGE_ENCRYPTION_KEY.
STORAGE_ENCRYPTION_KEY_VERSION=v1
# Routine/pre-write SQLite backups.
# Used by: src/lib/db/backup.ts. Set true only when those backups are managed externally.
# This never disables the migration runner's mandatory, content-addressed safety snapshot
# or its mass-migration guard for an existing persistent database.
# Default: false (routine backups enabled).
DISABLE_SQLITE_AUTO_BACKUP=false
# Opt-in synchronous SQLite adapter timing. Unset means off.
# Used by: src/lib/db/adapters/slowDiagnostics.ts
# OMNIROUTE_SQLITE_SLOW_MS=200
# Background SQLite planner statistics maintenance, independent of retention cleanup.
# Used by: src/lib/db/sqlitePlannerStats.ts via the cleanup scheduler.
# First pass: 30s after startup, after migrations; then every 6 hours.
# Default: true. Set false or 0 to disable all planner-statistics maintenance.
OMNIROUTE_SQLITE_OPTIMIZE_ENABLED=true
# Analysis row sampling limit: default 400; 0 = unlimited, exact analysis.
# Unlimited mode also disables SQLite's periodic optimize sampling cap.
# Decimal integers clamped to [0, 100000]; invalid values fall back to 400.
OMNIROUTE_SQLITE_ANALYSIS_LIMIT=400
# ── Redis (Rate Limiting) ──
# Redis connection URL for the rate limiter backend. OPT-IN: leave this
# commented out to use the built-in in-memory rate limiter. Setting it to a
# non-running localhost (#4878) makes ioredis flood "[REDIS] Error:" logs.
# Used by: src/shared/utils/rateLimiter.ts
# Example: redis://localhost:6379 (or redis://redis:6379 in Docker)
# REDIS_URL=redis://localhost:6379
# Namespace prefix for ALL OmniRoute Redis keys (rate limiter + auth cache +
# quota store + warmup circuit breaker). Prevents key collisions when OmniRoute
# shares a Redis instance with other apps (e.g. on 127.0.0.1:6379). Default when
# unset: omniroute:
# REDIS_KEY_PREFIX=omniroute:
# Optional shared session -> account affinity (slice 1a). Default: sqlite.
# redis requires REDIS_URL; uses the same client and REDIS_KEY_PREFIX.
# sessionAffinityTtlMs must remain positive; Redis calls fall back to SQLite after 100 ms.
# The timeout bounds waiting, not a sent EVAL, which may land after fallback.
# Each Redis affinity store caps outstanding operations at 8; full stores use SQLite immediately.
# SQLite routing keeps the legacy four-field JSON; Redis pins include hashed identity.
# Shared writes CAS against the routing observation (SQLite fallback records count as a miss).
# Redis alone is authoritative while it answers; confirmed mutations never write SQLite.
# Confirmed upserts/touches/deletes remove local entries; eviction uses the local identity guard.
# Only Redis errors, timeouts or admission saturation write local outage decisions,
# with the existing bounded TTL.
# Rejected upsert adopts a still-live eligible winner; unavailable winners keep the local candidate.
# On rejection, lease commits keep the claimed account for this request only, leaving shared unchanged.
# Late sent-mutation replies clean their timeout row by exact serialized-value compare-and-delete.
# During outage instances may re-pin independently; stickiness re-converges when Redis recovers.
# Known account identity overrides contradictory local IDs in resolution and guarded eviction.
# Shared liveness uses atomic value/PTTL reads; local snapshots map Redis's remaining TTL.
# JSON expiresAt is informational on Redis; existing keys retain their format and CAS bytes.
# Guarded eviction clears the failed account locally even when Redis is down.
# Successful shared replies can only remove local pins, never resurrect an evicted account.
# Does not share combo stickiness, native turn pins, concurrency or spend limits.
# OMNIROUTE_SESSION_AFFINITY_STORE=sqlite
# Host interface docker-compose publishes the Redis sidecar on.
# Default: 127.0.0.1 (loopback only). The compose Redis runs WITHOUT
# `requirepass`, and app containers reach it over the compose network
# (redis:6379) — the published port is only for host-side tooling. Setting this
# to 0.0.0.0 exposes an unauthenticated Redis to your whole LAN.
# REDIS_BIND_HOST=127.0.0.1
# Host port for the compose Redis sidecar. Default: 6379.
# REDIS_PORT=6379
# Host interface docker-compose publishes the app's own ports (dashboard,
# API, live-WS) on for the base/web/cli/host profiles and docker-compose.prod.yml.
# Default: 127.0.0.1 (loopback only). Combined with REQUIRE_API_KEY=false
# (the default below), an unqualified publish spec would expose the anonymous
# /v1 LLM proxy to your whole LAN/WAN. Only set this to 0.0.0.0 once you've
# confirmed REQUIRE_API_KEY=true, or that a reverse proxy in front of this
# instance already enforces its own authentication. (#12568)
# APP_BIND_HOST=127.0.0.1
# Host interface docker-compose publishes the Qdrant memory sidecar on.
# Default: 127.0.0.1 (loopback only). Same LAN-exposure reasoning as Redis.
# QDRANT_BIND_HOST=127.0.0.1
# Host interface docker-compose publishes the Bifrost router sidecar on.
# Default: 127.0.0.1 (loopback only). Same LAN-exposure reasoning as Redis.
# BIFROST_BIND_HOST=127.0.0.1
# ═══════════════════════════════════════════════════════════════════════════════
# 3. NETWORK & PORTS
# ═══════════════════════════════════════════════════════════════════════════════
# OmniRoute can run on a single port (default) or split Dashboard/API ports.
# Canonical port for both Dashboard UI and API (single-port mode).
# Used by: src/lib/runtime/ports.ts — base port for the Next.js server.
# Default: 20128
PORT=20128
# Base path (URL subpath) when serving OmniRoute behind a reverse proxy under a subpath.
# Used by: next.config.mjs — sets Next.js `basePath`; auth redirects are basePath-aware.
# Also mirrored to NEXT_PUBLIC_OMNIROUTE_BASE_PATH at build time so the dashboard
# endpoint display (useDisplayBaseUrl) shows https://host/omniroute/v1 instead of
# https://host/v1. Rebuild after changing this value (Next basePath is build-time).
# Default: "" (served at the domain root). Example: /omniroute to serve under https://host/omniroute
# Docker: baked at image build time via build-arg; root-path images can also apply this at
# container start (see docs/guides/DOCKER_GUIDE.md).
# OMNIROUTE_BASE_PATH=
# Client fetch/EventSource under this path are rewritten via installBasePathFetch
# (src/shared/utils/basePathFetch.ts) so absolute `/api/*` and `/v1/*` hits work
# without a reverse-proxy rewrite. Rebuild after changing (Next basePath is build-time).
#
# Browser-visible mirror of OMNIROUTE_BASE_PATH, inlined at build time so the
# dashboard endpoint display can read it client-side. Set it to the same value
# as OMNIROUTE_BASE_PATH; when unset the hook falls back to OMNIROUTE_BASE_PATH.
# Used by: src/shared/hooks/useDisplayBaseUrl.ts
# NEXT_PUBLIC_OMNIROUTE_BASE_PATH=
#
# Optional: set the public origin *with* the same path so OAuth and display URLs
# stay consistent without relying on window.location.origin alone:
# NEXT_PUBLIC_BASE_URL=https://host/omniroute
#
# Client-side fallback port for display URLs when no origin is known (SSR/tests):
# read before PORT so a browser bundle built with a different public port still
# renders the right http://localhost:<port> links (src/shared/hooks/useDisplayBaseUrl.ts).
# NEXT_PUBLIC_PORT=20128
#
# Explicit path probed by the container health check. Unset, the probe derives it
# from OMNIROUTE_BASE_PATH; setting it opts back into the deep monitoring endpoint.
# Used by: scripts/dev/healthcheck.mjs
# OMNIROUTE_HEALTHCHECK_PATH=/api/monitoring/health
# Opt-in iframe embedding of the OmniRoute HTML pages (issue #10273). Off by default:
# every route ships `frame-ancestors 'none'` + `X-Frame-Options: DENY`, which is why the
# VS Code Simple Browser (used by the OmniCopilot extension's "Open Dashboard → editor"
# mode) renders a blank tab. Set this to `vscode` to switch the HTML pages — dashboard,
# login, docs, landing — to `frame-ancestors 'self' vscode-webview:` and drop
# X-Frame-Options for them (XFO cannot express a custom scheme). The API surface
# (/api, /v1, /v1beta, /a2a, /healthz and the root-level aliases) keeps the strict
# headers regardless. Only `vscode` is recognised; `1`/`true` do NOT enable it.
# Used by: next.config.mjs via scripts/build/dashboardEmbed.mjs — build-time, rebuild after changing.
# Docker: pass it as a build arg (`docker build --build-arg DASHBOARD_ALLOW_EMBED=vscode`);
# setting it on an already-built server or image does nothing.
# DASHBOARD_ALLOW_EMBED=vscode
# Split-port mode: serve Dashboard and API on separate ports for network isolation.
# Used by: src/lib/runtime/ports.ts — overrides PORT for each service.
# API_PORT=20129
# API_HOST=0.0.0.0
# DASHBOARD_PORT=20128
# Connection backpressure: cap concurrent in-flight chat connections (503 + Retry-After when full).
# Used by: src/sse/utils/backpressure.ts — disabled when unset/0.
# OMNI_MAX_CONCURRENT_CONNECTIONS=0
# Optional OmniRoute-to-OmniRoute peer chaining guard. Give every instance a
# unique ID and allowlist only the other OmniRoute base URLs it may call.
# Requests to allowlisted peers carry X-OmniRoute-Peer-Trace; repeated instances
# and exhausted hop budgets are rejected with HTTP 508 before provider routing.
# OMNIROUTE_INSTANCE_ID=gateway-a
# OMNIROUTE_PEER_URLS=http://gateway-b:20128/v1
# OMNIROUTE_PEER_MAX_HOPS=4
# Port for the real-time WebSocket live monitoring server.
# Used by: src/server/ws/liveServer.ts, src/app/api/v1/ws/route.ts
# Default: 20132
# LIVE_WS_PORT=20132
# Bind address for the live WebSocket server.
# Default: 127.0.0.1 (loopback only). Set to 0.0.0.0 to expose on LAN —
# remember to also configure LIVE_WS_ALLOWED_ORIGINS when doing so.
# LIVE_WS_HOST=127.0.0.1
# Comma-separated extra origins allowed to open a live WebSocket. The
# loopback dashboard origins are already permitted by default; use this
# var when fronting the server with a domain (e.g. https://omni.local).
# ⚠️ When using NEXT_PUBLIC_LIVE_WS_PUBLIC_URL or exposing the WS server
# beyond loopback, this MUST include the public origin(s) — otherwise
# the Origin allow-list check will reject all browser connections.
# Example: LIVE_WS_ALLOWED_ORIGINS=https://omni.local,https://dashboard.example.com,https://ws.my-ai.com
# LIVE_WS_ALLOWED_ORIGINS=https://omni.local,https://dashboard.example.com
# Comma-separated extra hostnames allowed to open a live WebSocket (LAN/Tailscale).
# Unlike LIVE_WS_ALLOWED_ORIGINS (which matches full origin URLs), this matches
# only the host portion — useful for wildcard-ish LAN/Tailscale setups.
# Used by: src/server/ws/liveServerAllowList.ts
# Example: LIVE_WS_ALLOWED_HOSTS=omni.local,tailscale-host,192.168.1.50
# LIVE_WS_ALLOWED_HOSTS=omni.local,tailscale-host,192.168.1.50
# Public URL for the live dashboard WebSocket (client-side, browser only).
# Set this when fronting the WS server with a reverse proxy or Cloudflare Tunnel.
# The browser will connect to this URL instead of ws://hostname:20132.
# The path portion of this URL (e.g. ws://localhost:20132/live-ws -> /live-ws) is also used by the dev proxy
# (scripts/dev/standalone-server-ws.mjs) and the handshake response to route
# WebSocket upgrades. Default path: /live-ws.
# Used by: src/hooks/useLiveDashboard.ts, src/app/api/v1/ws/route.ts,
# scripts/dev/standalone-server-ws.mjs, and scripts/start-ws-server.mjs.
# Example: NEXT_PUBLIC_LIVE_WS_PUBLIC_URL=wss://ws.my-ai.com/live-ws
# NEXT_PUBLIC_LIVE_WS_PUBLIC_URL=ws://localhost:20132/live-ws
# Enable the real-time dashboard WebSocket server.
# Used by: src/server/ws/liveServer.ts, scripts/start-ws-server.mjs
# Default: ON. Set to 0 or false to disable startup of the live WS server.
# Combine with LIVE_WS_HOST / LIVE_WS_ALLOWED_ORIGINS above when exposing
# beyond loopback.
# OMNIROUTE_ENABLE_LIVE_WS=1
# Per-(token,IP) relay rate limit, requests/minute. In-memory, per instance.
# 0 or negative disables the IP-dimension gate (per-token DB limit still applies).
# Default: 30
# Used by: src/app/api/v1/relay/chat/completions/route.ts
# RELAY_IP_PER_MINUTE=30
# Bundler selection for `npm run dev` and `npm run build`. Set to 0 to fall back to webpack.
# Default is 1 (Turbopack). PR #4092 had forced webpack because earlier
# Turbopack 16.2.x panicked on the OmniRoute module graph with "internal error:
# entered unreachable code: there must be a path to a root"
# (turbopack-core/module_graph/mod.rs:662). That panic no longer reproduces on
# the pinned Next 16.2.9 — verified across a broad cold-compile sweep (36
# dashboard routes + open-sse-heavy API routes incl. /api/v1/chat/completions,
# /api/v1/models, /api/mcp) and repeated HMR rebuilds: zero panics. Turbopack
# also keeps dev memory far lower on the edit→rebuild loop (HMR rebuild RSS stays
# ~flat vs webpack's monotonic growth), which mitigates the dev-server OOM on
# this 60+ route app. The production build (scripts/build/build-next-isolated.mjs)
# reads the same flag: Turbopack by default, 0 builds with webpack (`npm run
# build:contributor` sets it for you).
OMNIROUTE_USE_TURBOPACK=1
# Webpack production builds (OMNIROUTE_USE_TURBOPACK=0) skip webpack's
# persistent filesystem cache by default: writing it adds about 2.5 GB of peak
# build memory at a 6144 MB heap cap. Set to 1 to keep .build/next/cache/webpack
# for faster repeat builds on a machine with RAM to spare (Docker: pass it as
# --build-arg). Read by next.config.mjs.
# OMNIROUTE_WEBPACK_BUILD_CACHE=1
# Disable systemd sd_notify (Type=notify / WatchdogSec=) even when running
# under a systemd unit with NOTIFY_SOCKET set.
# Used by: scripts/dev/systemd-notify.mjs. Set to 1 to disable.
# OMNIROUTE_DISABLE_SD_NOTIFY=1
# Injected by systemd when running under a service unit (sd_notify protocol).
# Read by scripts/dev/systemd-notify.mjs — never set this yourself.
# NOTIFY_SOCKET=/run/systemd/notify
# Skip the SQLite integrity health check on startup (faster boot on large DBs).
# Used by: src/lib/db/core.ts, src/lib/db/healthCheck.ts. Set to 1 to skip.
# OMNIROUTE_SKIP_DB_HEALTHCHECK=1
# Interval (ms) for the background credential health check scheduler.
# Default: 3600000 (60 minutes). Minimum: 10000 (10 seconds).
# Used by: open-sse/config/constants.ts, src/lib/credentialHealth/scheduler.ts
# CREDENTIAL_HEALTH_CHECK_INTERVAL=3600000
# TTL (ms) for cached credential health status.
# Default: 300000 (5 minutes).
# Used by: open-sse/config/constants.ts, src/lib/credentialHealth/cache.ts
# CREDENTIAL_HEALTH_CACHE_TTL=300000
# Set to 1 or true to disable background periodic testing of provider connections.
# Default: false
# Used by: src/lib/credentialHealth/scheduler.ts
# OMNIROUTE_DISABLE_CREDENTIAL_HEALTH_CHECK=false
# DEEP_HEALTH_CHECK_ENABLED: set to 1 to let an authenticated caller append ?deep=1 to
# /api/monitoring/health and sample the completions surface (cached per TTL). Off by default;
# anonymous callers never trigger a probe.
# DEEP_HEALTH_CHECK_ENABLED=0
# Stall threshold (ms) for the boot event-loop recorder: a freeze longer than
# this logs one line at resume and bumps the counter/maximum on
# /api/monitoring/health. Set to 0 to disable; unreadable or negative falls
# back to 5000.
# Used by: src/lib/healthzLag.ts
# OMNIROUTE_EVENT_LOOP_STALL_THRESHOLD_MS=5000
# Set to "true" to emit `[ProxyFetch]` debug logs from the Vercel relay path
# in open-sse/utils/proxyFetch.ts. Off by default to avoid leaking routing
# hints in production logs.
# OMNIROUTE_PROXY_FETCH_DEBUG=true
# Absolute path of the local proxy core binary (a file named `sing-box` for `.json` targets,
# or `mihomo` for `.yaml`/`.yml` targets) used to check a
# generated core configuration before it replaces the adopted file. Unset = write
# `<path>.generated` beside the adopted file only. Host environment only: never stored in the
# database nor accepted through the management API, because the binary is executed.
# A binary that doesn't match the target's core writes beside the adopted file with a warning.
# Used by: src/lib/proxySubscription/coreConfig/sync.ts.
# OMNIROUTE_PROXY_CORE_BINARY_PATH=/usr/bin/sing-box
# OMNIROUTE_PROXY_CORE_BINARY_PATH=/usr/local/bin/mihomo
# How the local proxy core reloads after a verified config replacement.
# Either a JSON argument array run without a shell, e.g.
# ["systemctl-reload-sing-box"] is NOT valid (must be an absolute path array),
# or exactly `external` when an outside observer applies the file.
# Never stored in the database nor exposed via the API.
# Used by: src/lib/proxySubscription/coreConfig/reload.ts.
# OMNIROUTE_PROXY_CORE_RELOAD_COMMAND=["/usr/bin/systemctl","--user","reload","sing-box"]
# Set to "true" or "1" to include client/egress IPs and the account prefix in
# the verbose `[ProxyEgress]` process-log line (src/lib/proxyLogger.ts). Kept
# OFF by default so the process log does not leak IPs or the account prefix.
# PROXY_LOG_INCLUDE_IPS=true
# Set to any non-empty value to emit `[omniroute completion]` diagnostics from
# the CLI shell-completion cache paths (read/refresh/write) in
# bin/cli/commands/completion.mjs. Off by default — these caches fail silently
# so a missing/corrupt cache never breaks tab-completion.
# OMNIROUTE_DEBUG_COMPLETION=1
# Set to 1 to print the full stack trace when a CLI command fails, instead of the
# concise error message. CLI-only diagnostics; HTTP error responses never include stacks.
# Used by: bin/cli/utils/formatCliError.mjs
# OMNIROUTE_DEBUG_STACK=1
# Optional Gemini CLI home used by `omniroute setup-gemini`. `omniroute run
# gemini` always replaces it with a private temporary home for that child.
# Default: the current user's home. Used by: bin/cli/commands/setup-gemini.mjs
# GEMINI_CLI_HOME=/path/to/isolated-gemini-home
# Grace period in milliseconds after forwarding SIGINT/SIGTERM/SIGHUP to a CLI
# child before OmniRoute escalates termination. Default: 5000.
# Used by: bin/cli/commands/run.mjs, launch.mjs, launch-codex.mjs
# OMNIROUTE_CHILD_SIGNAL_TIMEOUT_MS=5000
# Hermetic CLI/test escape hatch. When set to 1, an explicit DATA_DIR does not
# fall through to the user's default ~/.omniroute/.env credential file.
# Default: unset. Used by: bin/omniroute.mjs
# OMNIROUTE_CLI_SKIP_DEFAULT_DATA_ENV=1
# Set to 1 to print per-request timing diagnostics from the CLI quota commands
# to stderr (`[omniroute] GET <path> completed in Nms`).
# Used by: bin/cli/commands/quota.mjs
# OMNIROUTE_DEBUG=1
# Docker production port mappings (docker-compose.prod.yml only).
# These set the HOST-side published ports. Container ports use PORT/API_PORT.
# PROD_DASHBOARD_PORT=20130
# PROD_API_PORT=20131
# Runtime override used by Electron and wrapped environments.
# OMNIROUTE_PORT takes precedence over PORT when running inside wrappers.
# Used by: src/lib/runtime/ports.ts — preserves canonical port in Electron.
# OMNIROUTE_PORT=20128
# Hostname/bind address for the Next.js server.
# Used by: scripts/dev/run-next.mjs (HOST), Playwright runner (HOSTNAME).
# Default: 0.0.0.0 (HOST) / 127.0.0.1 (HOSTNAME inside tests).
# NOTE: Do NOT use `HOSTNAME` — it is a POSIX shell variable automatically set to
# the machine name by bash/zsh. The .env loader cannot override it (first-wins
# semantics). Use OMNIROUTE_SERVER_HOST instead for `omniroute serve`.
# See: https://github.com/diegosouzapw/OmniRoute/issues/6194
# HOST=0.0.0.0
# HOSTNAME=127.0.0.1
# OMNIROUTE_SERVER_HOST=0.0.0.0
# Environment mode — affects Next.js behavior, logging verbosity, and caching.
# Values: production | development | Default: production
NODE_ENV=production
# Container runtime — controls startup script behavior (permissions, advice).
# Values: docker | podman | Default: docker
# Set to "podman" for any Podman topology. The entrypoint cannot determine
# whether the engine is local or reached through Podman Machine, so it prints
# topology-neutral guidance and links contrib/podman/README.md.
CONTAINER_HOST=docker
# Container runtime override for skill sandboxing.
# Used by: src/lib/skills/sandbox.ts + src/lib/skills/containerProvider.ts
# Values: auto | docker | apple | wsl | orbstack | podman
# - auto: OS-aware auto-detect (apple/orbstack on macOS, wsl on Windows, podman on Linux)
# - apple: Apple Container (native OCI on macOS 26+)
# - wsl: WSL Container CLI (wslc.exe on Windows)
# - orbstack: OrbStack (high-perf Linux VM + docker shim on macOS)
# - podman: Podman (rootless, daemonless)
# - docker: Docker (default fallback)
# (defined under SKILLS & SANDBOXING section below)
# ═══════════════════════════════════════════════════════════════════════════════
# 4. SECURITY & AUTHENTICATION
# ═══════════════════════════════════════════════════════════════════════════════
# Salt for generating unique machine IDs (fingerprint diversification).
# Used by: src/lib/auth — combined with hardware identifiers for machine-id hash.
# Default: endpoint-proxy-salt | Change per-deployment for isolation.
MACHINE_ID_SALT=endpoint-proxy-salt
# Salt for deriving CLI machine-ID auth tokens (HMAC-SHA256).
# Used by: src/lib/machineToken.ts — rotates the local CLI auth token without
# touching code. Set to a new value to invalidate existing CLI tokens.
# Default: omniroute-cli-auth-v1
# OMNIROUTE_CLI_SALT=omniroute-cli-auth-v1
# Set true when running behind HTTPS (reverse proxy with TLS termination).
# Used by: src/lib/auth — sets the Secure flag on session cookies.
# Default: false | MUST be true in any non-localhost deployment.
AUTH_COOKIE_SECURE=false
# Require an API key for all /v1/* proxy endpoints.
# Used by: API middleware — rejects unauthenticated requests to the proxy API.
# Default: false | Set true for multi-user/public deployments.
# On: true, 1 or yes (case and surrounding spaces ignored). Any other value is off.
# Leaving this false is only safe when the app is reachable on loopback only
# (see APP_BIND_HOST above) or sits behind a reverse proxy doing its own auth.
REQUIRE_API_KEY=false
# Allow revealing full API key values in the Dashboard UI.
# Used by: src/shared/constants/featureFlagDefinitions.ts — controls show/hide of key values.
# Also configurable from Dashboard > Settings > Feature Flags.
# Default: false | Security risk if enabled on shared instances.
ALLOW_API_KEY_REVEAL=false
# Shared secret for the internal Codex Responses WebSocket bridge.
# Used by: src/app/api/internal/codex-responses-ws/route.ts — authenticates
# bridge requests between the Electron/browser WS relay and OmniRoute.
# ⚠️ REQUIRED for production — if unset, all WS bridge requests are rejected.
# Generate: openssl rand -base64 32
# OMNIROUTE_WS_BRIDGE_SECRET=
# Per-process secret that proves the trusted peer-IP stamp came from OmniRoute's
# own HTTP server (scripts/dev/peer-stamp.mjs). The custom server stamps the real
# TCP peer IP as `<token>|<ip>`; the authz middleware trusts the locality only
# when the token matches. Used by: src/server/authz/policies/management.ts.
# Auto-generated per boot — leave UNSET in normal use. Only set it to pin a fixed
# value across processes (e.g. a multi-process setup that must share the stamp).
# OMNIROUTE_PEER_STAMP_TOKEN=
# Comma-separated API key IDs that skip request logging (GDPR/compliance).
# Used by: src/lib/compliance/index.ts — suppresses logs for specific keys.
# NO_LOG_API_KEY_IDS=key_abc123,key_def456
# Fallback per-day request budget applied to API keys whose `rate_limits`
# column is null. Default (unset/empty) is unlimited (no implicit caps).
# Malformed values preserve the legacy 1000/day, 5000/week, 20000/month windows.
# Set explicitly to "0" to opt out entirely (unlimited fallback). Any
# positive integer N enables N/day, 5N/week, 20N/month.
# Used by: src/shared/utils/apiKeyPolicy.ts — checkRateLimit() fallback.
# DEFAULT_RATE_LIMIT_PER_DAY=1000
# Maximum request body size in bytes (rejects larger payloads). A saved maxBodySizeMb wins.
# Chat Completions and Responses keep a 50 MB default until a limit is saved.
# Used by: src/shared/middleware/bodySizeGuard.ts — prevents oversized uploads.
# Default: 10485760 (10 MB)
# MAX_BODY_SIZE_BYTES=10485760
# Atomic admission for POST /v1/chat/completions (#7846). Large request bodies
# amplify into multiple transient representations during parsing, compression, and
# provider dispatch. Heavyweight capacity is reserved before parsing; excess work
# receives 503 + Retry-After instead of overlapping until the process OOMs.
# Used by: src/shared/middleware/chatBodyAdmission.ts
# Actual bodies at or above this size take the heavyweight lease (BYTE path,
# including POST /v1/responses) and use the same #10437 healthy-headroom escape
# as structure-heavy. Default 262144 (256 KB).
# OMNIROUTE_CHAT_LARGE_BODY_BYTES=262144
# Actual-byte hard cap enforced during bounded ingestion. Default 52428800 (50 MB).
# A saved maxBodySizeMb replaces the default; when set here, this also caps that saved value.
# OMNIROUTE_CHAT_HARD_MAX_BODY_BYTES=52428800
# Legacy request-COUNT cap (#503-fanout). Now binds only when explicitly set here —
# left unset, heavyweight admission is gated by OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES below
# instead (an auto-derived byte budget), fixing coding-agent fan-out (multiple
# subagents/CLIs) collapsing to an effective concurrency of ~1 and 503ing.
# Two overlapping ~750k-token /v1/responses abort ~12 Gi heaps (#7849) — a
# memory-budget warning, not a hard product max of 2. A healthy heap may admit
# more via HEALTHY_HEADROOM. Tens of long SSE clients (40-50) is heap +
# OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES / #10110. Multiply heaps with N independent
# DATA_DIRs (#11024); never replicas>1 on one SQLite.
# OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT=1
# Override for the auto-derived ingest byte budget (#503-fanout). Default: 25% of the
# process's effective memory ceiling (V8 heap limit, or the tighter cgroup/container
# limit) divided by an 8x transient-amplification factor, clamped between 8 MiB and
# 2 GiB; explicit overrides are clamped to the same safe range. Read
# chatAdmission.maxInflightBytes/budgetSource at /api/monitoring/health before overriding.
# OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES=134217728
# Heap-pressure shed ratio (heapUsed/heap_size_limit) for BYTE and STRUCTURE
# heavyweight admission (#10183, #10268, #10437): a concurrent heavyweight request
# past OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT is only shed with a retryable 503 when the
# heap is ALSO under this much pressure — on a healthy heap it is admitted via
# healthy-headroom instead. Range (0, 1]. Default 0.75.
# OMNIROUTE_CHAT_ADMISSION_HEAP_SHED_RATIO=0.75
# Bounded extra capacity for the healthy-heap fast path above OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT
# (#10437, BYTE + STRUCTURE, including bodies >= OMNIROUTE_CHAT_LARGE_BODY_BYTES):
# once this many concurrent leases are active through the healthy-heap bypass,
# further busy requests fall through to the same bounded-wait/shed path used under real heap
# pressure. 0 disables the bypass entirely. Default 1.
# OMNIROUTE_CHAT_ADMISSION_HEALTHY_HEADROOM=1
# Message count that classifies an otherwise small body as heavyweight. Default 200.
# OMNIROUTE_CHAT_HEAVY_MESSAGE_COUNT=200
# Tool count that classifies an otherwise small body as heavyweight. Default 64.
# OMNIROUTE_CHAT_HEAVY_TOOL_COUNT=64
# Conservative string-size token estimate that classifies a request as heavyweight. Default 32000.
# OMNIROUTE_CHAT_HEAVY_ESTIMATED_TOKENS=32000
# Optional opt-in hard message-count cap; excess receives compact-required 413 before
# compression can run. Unset/0 (the default) means no history cap: heap growth is bounded
# by OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT and the heap-pressure shed instead. Set a positive
# value only on memory-constrained deployments that need a hard ceiling.
# OMNIROUTE_CHAT_HARD_MAX_MESSAGES=0
# Skip OmniRoute's local context-window and max-input-token check for direct
# single-model requests. Default: false (dangerous opt-in).
# The upstream provider still enforces its real limits, so enabling this can
# replace an early OmniRoute 400 with an upstream context-length error.
# Prompt compression and the model's own output-token cap remain active.
# Also configurable from Dashboard > Settings > Feature Flags; no restart is
# required. Used by: src/shared/utils/featureFlags.ts and open-sse/handlers/chatCore.ts.
# DISABLE_CONTEXT_WINDOW_CHECKS=false
# How long a heavy request waits for heavyweight capacity before a retryable 503.
# A short bounded wait serializes agent bursts instead of an instant 503; 0 = instant.
# Defaults to RATE_LIMIT_MAX_WAIT_MS (see that var elsewhere in this file for its
# current value), the same budget the resilience layer gives the upstream turn that
# holds the slot — a shorter wait cannot bridge it.
# OMNIROUTE_CHAT_ADMISSION_QUEUE_MS=20000 # example override; default tracks RATE_LIMIT_MAX_WAIT_MS
# Queued-bytes budget for the admission wait: bounds total buffered body bytes parked
# per lane so the wait cannot amplify the heap (#4380). Over-budget waits 503 immediately.
# Default 4194304 (4 MB).
# OMNIROUTE_CHAT_ADMISSION_MAX_QUEUED_BYTES=4194304
# Per-connection virtual admission lanes (#9654): idle-lane eviction TTL. Default 60000 (60s).
# OMNIROUTE_CHAT_VIRTUAL_TTL_MS=60000
# Per-connection virtual admission lanes (#9654): max concurrent sessions (lanes). Default 64.
# OMNIROUTE_CHAT_VIRTUAL_MAX_SESSIONS=64
# Adaptive runtime virtual admission lanes (#9654): master switch for the per-tenant
# adaptive gate (system 2, open-sse/services/admission). NOTE: the TTL/MAX_SESSIONS
# vars above tune the byte-level per-connection lanes (system 1); this switch enables
# the adaptive runtime lanes. Dashboard feature flag of the same name; env wins over
# the dashboard override; restart required. Default: off.
# OMNIROUTE_CHAT_VIRTUAL_LANES=1
# Hard cap (bytes) for a non-streaming upstream response buffered fully into memory
# (#5152). Past this the upstream reader is cancelled and the request fails fast
# instead of growing an unbounded string until the V8 heap is exhausted.
# Used by: open-sse/handlers/chatCore/nonStreamingResponseBody.ts
# Default: 67108864 (64 MB)
# OMNIROUTE_FORWARDING_HEADER_BUDGET_BYTES=768
# OMNIROUTE_MAX_NONSTREAMING_RESPONSE_BYTES=67108864
# Most quota-recovery tickets (pending, running or awaiting confirmation) one
# API key may hold. At the limit, new turns get the original quota error.
# Used by: src/lib/quota/quotaSessionRecovery.ts
# Default: 64
# OMNIROUTE_QUOTA_RECOVERY_MAX_PER_KEY=64
# CORS configuration — controls which cross-origin browser clients can call the API.
# Used by: src/server/cors/origins.ts — sets Access-Control-Allow-Origin.
# Same-origin dashboard requests behind a reverse proxy do not need CORS; they
# use session-bound CSRF protection. No wildcard is sent unless CORS_ALLOW_ALL=true.
# CORS_ALLOWED_ORIGINS=https://your-frontend.example.com
# CORS_ORIGIN=https://your-frontend.example.com # legacy single-origin alias
# CORS_ALLOW_ALL=false
# Turns off the outbound URL guard's host checks, cloud-metadata block included, on the
# provider paths that follow the guard mode: URL validation, model discovery, provider-node
# base URLs (including remote rerank nodes), and the proxy-fallback test, among other
# provider-adjacent outbound paths such as remote image/media fetch. It also allows
# private webhook targets, except cloud-metadata/link-local endpoints, which stay
# blocked even with this flag on. Local providers work with the defaults:
# OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS below (default true) already allows local and LAN
# URLs. A value saved from the dashboard toggle takes precedence over this variable.
# Details: docs/reference/ENVIRONMENT.md.
# Used by: src/shared/network/outboundUrlGuardPolicy.ts
# Default: false
# OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS=true
# Allow provider URLs on local and private addresses (127.0.0.1, localhost, LAN).
# Default: true (OmniRoute is local-first); the guard then blocks cloud-metadata
# endpoints — all of 169.254.0.0/16 plus the known metadata hostnames. Set false to
# block private and loopback hosts too (public-only mode). The guard checks the
# hostname or IP literal as written first; in public-only mode the safe-fetch
# wrapper (validation, model discovery) also resolves the name and refuses
# private answers.
# Built-in local providers skip these checks for key validation and chat.
# A value saved from the dashboard toggle takes precedence over this variable.
# Used by: src/shared/network/outboundUrlGuardPolicy.ts
# OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS=false
# Legacy alias; its dashboard toggle (a DB override) is read before this environment value.
# "false", "0", "no", or "off" in either turns the host checks off the way
# OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS=true does, even when that flag's dashboard toggle
# is saved off. Other values leave the guard to the two flags above.
# Used by: src/shared/network/outboundUrlGuardPolicy.ts
# OUTBOUND_SSRF_GUARD_ENABLED=true
# ── Self-hosted unified OpenAI-compatible entry (RIC-738, D4) ────────────────────
# When set, /v1/chat/completions diverts to the self-hosted provider adapters
# (open-sse/services/selfHostedEntry.ts) instead of the cloud pipeline. YAML inline
# (example) — or point OMNIROUTE_SELF_HOSTED_PROVIDERS_FILE at a YAML file. Secrets
# are runtime-only, never logged. While ANY of these is set, the entry is active;
# config present but unparseable returns a 500 (never silently falls through).
# OMNIROUTE_SELF_HOSTED_PROVIDERS='
# providers:
# - id: local
# kind: openai
# baseUrl: http://127.0.0.1:11434/v1
# model: llama3
# - id: claude
# kind: anthropic
# baseUrl: http://127.0.0.1:8080
# model: claude-sonnet
# '
# OMNIROUTE_SELF_HOSTED_PROVIDERS_FILE=/etc/omniroute/providers.yaml
# Optional shared API key for the unified entry (D5 reserved). When set, require
# `Authorization: Bearer <key>`; empty = open loopback/trusted-network route.
# OMNIROUTE_SELF_HOSTED_API_KEY=
# ── Deterministic routing strategies (M2 / RIC-740, D3 可审计路由) ─────────────
# Optional `strategy:` block — either inline in the providers document above, or a
# standalone document via these env vars. One rule per line; every decision is
# explainable via the `x-omniroute-route-decision` response header. No ML/predict.
# Malformed strategy config returns a 500 (never silently becomes a no-op).
# Example (inline, same shape as `strategy:` inside the providers YAML):
# OMNIROUTE_SELF_HOSTED_STRATEGY='
# blacklist: []
# whitelist: [cheap, fast, premium]
# costPriority: true
# latencyAware:
# enabled: true
# cooldown:
# consecutiveFailures: 2
# cooldownMs: 30000
# fallbackChain: [cheap, fast, premium]
# '
# OMNIROUTE_SELF_HOSTED_STRATEGY_FILE=/etc/omniroute/strategy.yaml
# See docs/routing/DETERMINISTIC_ROUTING.md for the full strategy surface.
# ═══════════════════════════════════════════════════════════════════════════════
# 5. INPUT SANITIZATION & PII PROTECTION (FASE-01)
# ═══════════════════════════════════════════════════════════════════════════════
# Multi-layer defense: request-side injection guard + response-side PII sanitizer.
# ── Request-Side: Prompt Injection Guard ──
# Scans incoming messages for prompt injection patterns before routing.
# Used by: src/middleware/promptInjectionGuard.ts
# Default ON when unset. Set to false/0/no/off to disable. Truthy: true/1/yes/on.
# INPUT_SANITIZER_ENABLED=false
# INPUT_SANITIZER_MODE=warn # warn = log only | block = reject request | redact = legacy (does NOT strip injection; use PII_REDACTION_ENABLED for request PII)
# INPUT_SANITIZER_BLOCK_THRESHOLD=high # high (default) | medium | low — severities at/above this are blocked in block mode
# Legacy aliases for INPUT_SANITIZER_MODE / INPUT_SANITIZER_BLOCK_THRESHOLD (same effect).
# INJECTION_GUARD_MODE=warn
# INJECTION_GUARD_BLOCK_THRESHOLD=high
# PII detection in incoming requests (emails, phone numbers, SSNs, etc.).
# Used by: src/middleware/promptInjectionGuard.ts — extends injection guard.
# PII_REDACTION_ENABLED=false
# Reversible PII vault (needs PII_REDACTION_ENABLED=true). Request PII becomes per-request
# surrogate tokens such as <<PII_EMAIL_QWERTYUI_1>> instead of [EMAIL_REDACTED]; the chat
# handler restores the original values in 2xx responses (SSE and JSON). Error bodies keep the
# tokens. A DB override on the dashboard toggle wins over this value.
# Used by: src/lib/pii/requestTokenVaultScope.ts.
# PII_REVERSIBLE_VAULT_ENABLED=false
# Redacts well-known API-key / secret-token patterns (OpenAI, Anthropic, GitHub,
# Slack, etc.) from request/response payloads before they reach providers/clients.
# Opt-in; mirrors PII_REDACTION_ENABLED. Used by: src/lib/guardrails/credentialMasker.ts.
# CREDENTIAL_REDACTION_ENABLED=false
# Minimum streaming window size for PII detection (bytes). Default: 200.
# Used by: src/lib/streamingPiiTransform.ts.
# PII_WINDOW_SIZE=200
# Test bypass: allow setting PII_WINDOW_SIZE below minimum. Default: false.
# Used by: src/lib/streamingPiiTransform.ts.
# PII_TEST_BYPASS_MIN_WINDOW=false
# ── Response-Side: PII Sanitizer ──
# Scans LLM responses for leaked PII before returning to the client.
# Used by: src/lib/piiSanitizer.ts
# PII_RESPONSE_SANITIZATION=false
# PII_RESPONSE_SANITIZATION_MODE=redact # redact = mask PII | warn = log only | block = drop response
# ── VS Code Tokenized-Route Context Sanitizer ──
# Strips implicit active-editor context (editorContext/activeEditor/currentFile/
# selection/openTabs…) from requests on the /v1/vscode/[token]/* routes before
# forwarding upstream, and redacts the content of explicitly-attached sensitive
# files (.env, private keys, kubeconfig, credentials/secrets). Explicit
# attachments otherwise pass through. Secure-by-default: ON unless set to 0.
# Used by: src/app/api/v1/vscode/contextSanitizer.ts
# OMNIROUTE_VSCODE_SANITIZE_CONTEXT=1 # set to 0 to disable
# ═══════════════════════════════════════════════════════════════════════════════
# 6. TOOL & ROUTING POLICIES
# ═══════════════════════════════════════════════════════════════════════════════
# Tool policy mode — controls which tools LLMs can invoke via function calling.
# Used by: src/lib/toolPolicy.ts — enforces allowlist/denylist on tool_choice.
# Values: allowlist | denylist | disabled | Default: disabled
# TOOL_POLICY_MODE=disabled
# Payload manipulation rules JSON file.
# Used by: open-sse/services/payloadRules.ts — injects/removes upstream payload fields per model/protocol.
# Default: ./config/payloadRules.json
# OMNIROUTE_PAYLOAD_RULES_PATH=./config/payloadRules.json
# Reload interval for payloadRules.json mtime checks in milliseconds.
# Used by: open-sse/services/payloadRules.ts — keeps file-based rules hot-reloadable without restart.
# Default: 5000 | Minimum: 1000
# OMNIROUTE_PAYLOAD_RULES_RELOAD_MS=5000
# Prefer Claude Code OAuth for unprefixed Claude-family model IDs such as
# claude-sonnet-4-6 or newly released IDs like claude-fable-5.
# Used by: open-sse/services/model.ts. Explicit provider prefixes still win.
# Default: false
# OMNIROUTE_PREFER_CLAUDE_CODE_FOR_UNPREFIXED_CLAUDE_MODELS=false
# Set to false to stop OmniRoute adding the redact-thinking-2026-02-12 Anthropic beta
# on its own (thinking text is then returned instead of empty signature-only blocks).
# Requests with thinking.display "summarized" already skip it; client-negotiated or
# CC-compatible requestDefaults.redactThinking opt-ins keep it. Claude OAuth requests keep
# the beta (Claude Code OAuth fingerprint) unless the default-off feature flag
# CLAUDE_OAUTH_SUMMARIZED_THINKING_UNREDACTED is enabled.
# Used by: open-sse/executors/base/redactThinkingBeta.ts
# Default: true
# OMNIROUTE_REDACT_THINKING=true
# Feature flag (also settable from the dashboard Feature Flags page): let Claude OAuth
# requests that ask for thinking.display "summarized" drop the redact-thinking beta.
# Off by default — the beta is part of the Claude Code OAuth wire fingerprint.
# Used by: open-sse/executors/base/redactThinkingBeta.ts
# Default: false
# CLAUDE_OAUTH_SUMMARIZED_THINKING_UNREDACTED=false
# Legacy resolveBareModelToConnectionDefault behaviour (#4825): replace ANY bare
# model name (not only "auto"/empty) with the selected connection's defaultModel.
# Off by default: a concrete bare name such as claude-haiku-4-5 is kept.
# Used by: open-sse/services/model.ts.
# Default: false
# BARE_MODEL_DEFAULT_OVERRIDE_LEGACY=false
# Per-model concurrency cap for round-robin combos (#9100).
# Used by: open-sse/services/comboConfig.ts — the round-robin combo semaphore
# was hard-capped at 3 concurrent requests per model with no override, which
# serialized higher-concurrency traffic behind that cap.
# Validated to >= 1, clamped to <= 32. | Default: 3
# COMBO_CONCURRENCY_PER_MODEL=3
# Opt-in sub-budget for stream-readiness deadline failures in a combo run.
# A stalled upstream fails the readiness window on EVERY target while the
# combo rotates (each rotation re-dispatches the full body after tens of
# seconds to minutes of waiting), multiplying user latency and gateway memory
# before the global-attempts cap — calibrated for fast failures — kicks in.
# Unset/0 (default) = disabled, no behavior change. A positive integer
# terminates the combo with a clean 504 once that many readiness-deadline
# failures accumulated (504 with error.code STREAM_READINESS_TIMEOUT; the
# target that exhausts the budget is still locked out / cooled down).
# Used by: open-sse/services/combo/comboPredicates.ts + executeTargetAttempt.ts
# OMNIROUTE_COMBO_MAX_DEADLINE_FAILURES=3
# Agentic-stall combo failover (opt-in, default OFF).
# Used by: open-sse/services/combo/agenticStall.ts + agenticStallFailover.ts — a combo
# member answering a tool-result turn with "finish: stop + narration + zero tool calls"
# fails over to the next target; if none does better, the stalled answer is returned.
# Streamed turns are held back from the client until the verdict is settled.
# Set to 1 (or true) to enable. | Default: false
# OMNIROUTE_AGENTIC_STALL_FAILOVER=false
# Disable conversation-history tracking (#13150).
# Used by: open-sse/services/conversationTracker.ts. resolveConversationId()
# returns an untracked result before it reads SQLite or parses message history,
# and the switch also covers client-supplied session IDs. Routing sessions are
# unaffected and existing records are not deleted. Use it when the dashboard's
# conversation view is unused and the turn table has grown large.
# Set to 1 to disable. | Default: unset (tracking enabled)
# OMNIROUTE_DISABLE_CONVERSATION_TRACKING=1
# Unpriced successful usage in per-API-key USD limits. Leave unset to use the
# upstream boolean opt-out below, otherwise the default fails closed.
# An explicit enum (DB override before env) takes precedence over the boolean.
# Values: fail_closed | count_as_zero. Lookup failures always fail closed.
# Used by: src/shared/utils/featureFlags.ts (enforcement and admin report).
# UNPRICED_USAGE_BUDGET_POLICY=fail_closed
# USAGE_LIMIT_IGNORE_UNPRICED=false
# Nadir API key for the opt-in `nadir` auto-combo router strategy.
# Used by: open-sse/services/autoCombo/nadirStrategy.ts — fallback for the combo's
# config.nadir.apiKey. Only read when a combo opts in with "routerStrategy": "nadir".
# Optional: keyless calls land on Nadir's anonymous tier, which is rate-limited per IP
# and so is not usable behind a shared gateway.
# Sensitive; prefer the per-combo config.nadir.apiKey when combos use different accounts.
# OMNIROUTE_NADIR_API_KEY=
# Base origin of the Nadir decision API.
# Used by: open-sse/services/autoCombo/nadirStrategy.ts — fallback for the combo's
# config.nadir.baseUrl. Only needed for a self-hosted Nadir, which keeps prompt heads
# inside your own network. A trailing /v1 is tolerated and stripped.
# Default: https://api.getnadir.com
# OMNIROUTE_NADIR_BASE_URL=https://api.getnadir.com
# Weekly window for per-API-key USD usage limits.
# Used by: src/lib/usage/apiKeyUsageLimits.ts (request enforcement, key usage-limit
# status, @@om-usage). Values: provider | calendar | Default: provider
# provider: the week ends at the earliest weekly reset among the upstream
# connections the key can reach (rolling 7 days when none is known).
# calendar: the local week, Monday 00:00 to the next Monday 00:00, the same for
# every key. Recommended when one pool of upstream accounts is shared
# by many individually budgeted keys.
# OMNIROUTE_API_KEY_WEEKLY_WINDOW=calendar
# IANA timezone for the calendar weekly window (e.g. Asia/Shanghai, UTC).
# Used by: src/lib/usage/apiKeyUsageLimits.ts. Unset or invalid: the timezone of
# the OmniRoute process (the TZ of the host or container). Ignored in provider mode.
# OMNIROUTE_API_KEY_WEEKLY_WINDOW_TIMEZONE=Asia/Shanghai
# Default maximum number of tools allowed in a request (OpenAI default 128).
# Used by: open-sse/config/constants.ts (MAX_TOOLS_LIMIT) — caps the tool list
# sent upstream when a provider has no known/proactive limit of its own; a
# provider with a known limit (e.g. grok-cli 200, nvidia 1536) still applies its
# own cap. Positive integers only; unset or invalid values keep 128.
# OMNIROUTE_MAX_TOOLS_LIMIT=128
# Responses -> Chat translation re-sends tool-output images (function_call_output,
# custom_tool_call_output, role "tool") as user image parts. Only the newest images within
# both budgets are kept; each older one becomes a text placeholder with its tool_call_id,
# and the cap logs one warning per request.
# Used by: open-sse/translator/request/openai-responses.ts (selectDroppedToolOutputImages).
# Positive integers only; unset or invalid values keep the defaults.
# OMNIROUTE_TOOL_OUTPUT_IMAGE_MAX_COUNT=16
# OMNIROUTE_TOOL_OUTPUT_IMAGE_MAX_BYTES=20971520
# Inconsistent Responses tool history (an output with no call, a call with no output, a missing,
# overlong or invalid call_id, malformed historical arguments). Off: OmniRoute repairs it and
# dispatches (#15216). On: the request gets a 400 before dispatch instead.
# Used by: open-sse/translator/helpers/responsesToolHistory.ts (isStrictResponsesToolHistoryEnabled).
# Accepts true or 1; anything else keeps the default.
# OMNIROUTE_RESPONSES_STRICT_TOOL_HISTORY=false
# SYNTX.ai prompt-emulated tool calling. Unset = on: SYNTX chat injects the local
# tool catalog into the prompt and parses <tool_call> blocks back into OpenAI
# tool_calls. Set to 0/false/off to skip the local-tool catalog injection.
# Used by: open-sse/executors/syntxChat.ts (isSyntxPromptToolEmulationEnabled).
# OMNIROUTE_PROMPT_EMULATE_TOOLS=1
# ═══════════════════════════════════════════════════════════════════════════════
# 7. URLS & CLOUD SYNC
# ═══════════════════════════════════════════════════════════════════════════════
# URLs used for internal sync jobs, OAuth callbacks, and cloud relay.
# Internal base URL — used by server-side sync jobs to call /api/sync/cloud.
# Keep this as a loopback/container URL even when the app is publicly proxied.
# A2A skills refuse to send an API key over plain http outside the private network.
# Used by: src/lib/cloudSync.ts, src/lib/initCloudSync.ts
# Default: http://localhost:20128
BASE_URL=http://localhost:20128
# Cloud relay URL — premium feature for remote config sync.
# Used by: src/lib/cloudSync.ts — pushes/pulls settings from OmniRoute Cloud.
CLOUD_URL=
# Timeout for cloud sync HTTP requests in milliseconds.
# Used by: src/lib/cloudSync.ts — fetchWithTimeout wrapper.
# Default: 12000 (12 seconds)
# CLOUD_SYNC_TIMEOUT_MS=12000
# Public-facing base URL — required for stable reverse proxy / OAuth callback setups.
# Used by: OAuth redirect_uri computation, Dashboard UI links, and generated public URLs.
# Set to your stable public URL when OAuth callbacks or generated browser links need a
# canonical host behind nginx/Caddy (e.g., https://omniroute.example.com).
#
# Dashboard display behavior: when this variable is unset, the dashboard
# auto-detects the base URL shown in curl examples and CLI tool snippets
# from window.location.origin (the host the user is browsing). Setting it
# explicitly is only required when running behind a reverse proxy with a
# different public hostname, or when OAuth callbacks / generated browser links must point
# to a canonical URL. Authenticated dashboard writes use same-origin requests plus
# session-bound CSRF protection and do not require a static public base URL.
#
# Default: http://localhost:20128
NEXT_PUBLIC_BASE_URL=http://localhost:20128
# Highest-priority OmniRoute public origin override, also used by non-dashboard
# public-origin validation. Set it when external clients reach OmniRoute through
# a stable LAN, tunnel, or public origin that differs from its internal URL.
# Do not include /v1; if included accidentally it will be normalized away.
# OMNIROUTE_PUBLIC_BASE_URL=http://192.168.0.15:20128
# Absolute provider plugin manifest URL advertised to sidecar clients.
# Used by: open-sse/config/providerPluginManifestUrl.ts. When unset, OmniRoute
# derives the URL from request origin or HOST/PORT using OMNIROUTE_PUBLIC_PROTOCOL.
# OMNIROUTE_PROVIDER_MANIFEST_URL=https://omniroute.example.com/api/v1/provider-plugin-manifest
# Protocol used when deriving provider plugin manifest URLs without a request origin.
# Used by: open-sse/config/providerPluginManifestUrl.ts. Defaults to http.
# OMNIROUTE_PUBLIC_PROTOCOL=http
# Public cloud URL — client-side mirror of CLOUD_URL.
NEXT_PUBLIC_CLOUD_URL=
# Legacy alias — fallback for NEXT_PUBLIC_BASE_URL in sync schedulers.
# NEXT_PUBLIC_APP_URL=http://localhost:20128
# Advanced reverse-proxy trust mode for deriving public origin from Forwarded /
# X-Forwarded-* headers when no explicit public base URL is set. Prefer setting
# NEXT_PUBLIC_BASE_URL. Only enable if direct client access to OmniRoute is blocked
# and your proxy strips/rebuilds incoming forwarded headers.
# Values: true/loopback (trust loopback proxy peers), private/lan (also trust LAN peers).
# OMNIROUTE_TRUST_PROXY=
# Proxy addresses whose X-Forwarded-For / X-Real-IP the IP allow/deny list may believe, on top
# of loopback, private-network addresses and Cloudflare edges, which are always trusted. Needed
# only when the reverse proxy in front of OmniRoute has any other (public) address; without
# it that proxy's own address is what the filter judges. Comma-separated IPs or CIDR ranges.
# Used by: scripts/dev/peer-stamp.mjs.
# OMNIROUTE_TRUSTED_PROXIES=198.51.100.7,203.0.113.0/24
# Public callback URL for asynchronous image/audio jobs (kie.ai, etc.).
# Used by: open-sse/utils/kieTask.ts — overrides callbackUrlFromBaseUrl().
# Honor order: KIE_CALLBACK_URL → OMNIROUTE_KIE_CALLBACK_URL → OMNIROUTE_PUBLIC_URL.
#KIE_CALLBACK_URL=
#OMNIROUTE_KIE_CALLBACK_URL=
#OMNIROUTE_PUBLIC_URL=
# Headroom token-saver proxy URL. The dashboard lifecycle (api/headroom/*) spawns
# a local headroom-ai CLI on loopback by default; override only to point at an
# external Docker sidecar proxy. Defaults to http://localhost:8787 when unset.
# Used by: src/lib/headroom/detect.ts.
#HEADROOM_URL=http://localhost:8787
# Upstream quota endpoints used by the Usage page. Override only for
# debugging or when routing through a corporate mirror. Used by:
# open-sse/services/usage.ts.
#OMNIROUTE_CROF_USAGE_URL=https://crof.ai/usage_api/
# ClinePass 5h/weekly/monthly quota endpoint (open-sse/services/usage/clinepass.ts).
#OMNIROUTE_CLINEPASS_USAGE_URL=https://api.cline.bot/api/v1/users/me/plan/usage-limits
#OMNIROUTE_CODEWHISPERER_BASE_URL=https://codewhisperer.us-east-1.amazonaws.com
# Official OpenCode Go usage endpoint, authenticated with the connection API key.
# Override only for relays or test fixtures.
#OMNIROUTE_OPENCODE_QUOTA_URL=https://opencode.ai/zen/go/v1/usage
#OMNIROUTE_OLLAMA_CLOUD_USAGE_URL=https://ollama.com/settings
# Ollama Cloud documented balance endpoint, authenticated with the connection API key
# (open-sse/services/ollamaCloudBalance.ts). Tried before the settings-page scraper.
# Override only for relays or test fixtures.
#OMNIROUTE_OLLAMA_CLOUD_BALANCE_URL=https://ollama.com/api/balance
# OpenCode Go/Zen VPS egress (#5997): on a datacenter VPS, Cloudflare in front of
# opencode.ai/zen/go 403s chat requests that lack OpenCode CLI identity headers.
# When your clients don't already send them, set this to synthesize the CLI headers
# (User-Agent, x-opencode-client, x-opencode-project, canonical request/session ids) on
# absent keys. ON by default — a client value always wins, these only fill gaps.
# Values are overridable via OPENCODE_GO_USER_AGENT / OPENCODE_USER_AGENT / OPENCODE_CLIENT /
# OPENCODE_PROJECT (defaults: opencode/1.18.31 / desktop / global).
#OPENCODE_SYNTHESIZE_CLI_HEADERS=true
#OPENCODE_USER_AGENT=opencode/1.18.31
#OPENCODE_CLIENT=desktop
#OPENCODE_PROJECT=global
# Forward client app-attribution headers (x-session-id / x-title / http-referer) to
# upstream providers, so requests keep their app identity through the router
# (OpenRouter publisher gates key on them). ON by default; operator custom headers
# always win. Set to 0/false/no/off to keep the operator identity instead.
#OMNIROUTE_FORWARD_ATTRIBUTION=1
# Keyless OpenCode models are answered only when the request declares a non-empty tool
# list, and the upstream inspects which names it carries. OmniRoute reuses the list a
# request of the same conversation was last seen getting through, so a request that
# carries none — a title or a summary — goes out with the list its own client already
# declared. Set to off to stop adjusting request bodies entirely; headers are unaffected.
#OPENCODE_FREE_TIER_REQUEST_CONTRACT=off
# Tool names to declare when nothing has been observed yet for a model, comma-separated.
# Empty falls back to a single placeholder the model is told not to call. Only useful on
# an install where no client sends tools, since there is then nothing to learn from.
#OPENCODE_FREE_TIER_PLACEHOLDER_TOOLS=glob,grep,read
# Credential used on the gated free-tier lane (https://opencode.ai/inference/v1, the base
# every free model is routed to). Since 2026-10-21 that lane answers 403 "Model access is
# disabled" to a real API key and serves the anonymous literal instead, so the default is
# "public". Set to "key" to keep sending the operator's API key (an upstream that re-opens
# free-tier access to keyed accounts), "none" to send no credential header, or any other
# literal to send it as the bearer token.
#OPENCODE_FREE_TIER_CREDENTIAL=public
# Bun relay for the keyless OpenCode models. The upstream answers 429 to every HTTP client but
# Bun's native fetch, and only when messages[0] is the genuine OpenCode CLI prompt with the
# CLI tool set declared. With this set, gated requests are rewritten that way (the caller's
# system text follows, its tools are kept, calls to CLI tools it never declared are dropped
# from the reply) and sent to the relay, which re-sends them with Bun. Loopback URLs are
# started with the server when `bun` is on PATH (override: OPENCODE_FREE_RELAY_BUN); otherwise
# run `bun scripts/ops/opencode-free-relay.ts` as a sidecar. Port: OPENCODE_FREE_RELAY_PORT.
# An egress proxy assigned to the request is forwarded to the relay (http/https proxies only).
#OPENCODE_FREE_TIER_RELAY_URL=http://127.0.0.1:20199
# Relay tuning (all optional): OPENCODE_FREE_RELAY_BUN (bun binary), OPENCODE_FREE_RELAY_SCRIPT
# (relay script path), OPENCODE_FREE_RELAY_HOST / OPENCODE_FREE_RELAY_PORT (listen address,
# default 127.0.0.1:20199), OPENCODE_FREE_RELAY_UPSTREAM (default https://opencode.ai).
#OPENCODE_FREE_RELAY_BUN=
#OPENCODE_FREE_RELAY_SCRIPT=
#OPENCODE_FREE_RELAY_HOST=127.0.0.1
#OPENCODE_FREE_RELAY_PORT=20199
# Non-loopback relay: OPENCODE_FREE_TIER_RELAY_URL must be https:// unless the host is loopback
# (localhost, 127.0.0.0/8, ::1). A relay bound to a non-loopback OPENCODE_FREE_RELAY_HOST refuses
# to start without OPENCODE_FREE_RELAY_TOKEN (sent by OmniRoute, required by the relay) and only
# honours caller proxies listed in OPENCODE_FREE_RELAY_PROXY_ALLOWLIST (host or host:port, comma-separated).
#OPENCODE_FREE_RELAY_TOKEN=
#OPENCODE_FREE_RELAY_PROXY_ALLOWLIST=
#OPENCODE_FREE_RELAY_UPSTREAM=https://opencode.ai
# Egress-IP lockout scope (#9611). By default the free-tier opencode family
# (opencode, opencode-go, opencode-cli) is bucketed by egress IP: one upstream
# 429 parks every sibling connection sharing that IP. PAID plans are
# account-bucketed upstream, so operators on paid subscriptions can disable the
# cascade or narrow it to the providers that actually need it.
# unset → default free-tier set (opencode, opencode-go, opencode-cli)
# none / off / false / 0 → egress-IP lockout disabled entirely
# "a,b,c" → exact replacement set (comma-separated provider IDs)
# Used by: open-sse/config/providerErrorRules.ts (isEgressBucketedLockScope)
# OMNIROUTE_EGRESS_IP_LOCK_PROVIDERS=none
# Quota-refusal egress rotation scope. By default only the IP-bucketed family above
# sets a pool member aside when it answers 429 through the member, so the next pick
# egresses elsewhere. The free and keyless providers answer 429 per IP too (there is
# no account key to bucket by), and `all` extends that write to every provider.
# unset → the IP-bucketed family only (default)
# all → every provider; any other value is ignored rather than guessed
# Needs PROXY_SKIP_RECENTLY_FAILED (on by default) for the set-aside to be read.
# The refusal store is keyed by egress address, not by (provider, address), so a widened
# 429 parks that member for every provider until the period elapses (5 min, up to 15).
# Used by: open-sse/config/providerErrorRules.ts (rotatesEgressOnQuotaRefusal)
# OMNIROUTE_EGRESS_QUOTA_ROTATION_PROVIDERS=all
# Ollama Cloud quota scraping. Prefer configuring this per connection in
# Dashboard → Providers → Ollama Cloud. The cookie is sensitive.
#OLLAMA_USAGE_COOKIE=__Secure-session=...
#OLLAMA_CLOUD_USAGE_COOKIE=__Secure-session=...
#OMNIROUTE_OLLAMA_USAGE_COOKIE=__Secure-session=...
# ═══════════════════════════════════════════════════════════════════════════════
# 8. OUTBOUND PROXY (Upstream Provider Calls)
# ═══════════════════════════════════════════════════════════════════════════════
# Route upstream LLM API calls through an HTTP/SOCKS5 proxy.
# Useful for corporate egress, geo-routing, or IP masking.
# Enable SOCKS5 proxy support in both server and client components.
# Used by: open-sse/executors — wraps fetch() calls through the proxy agent.
ENABLE_SOCKS5_PROXY=true
NEXT_PUBLIC_ENABLE_SOCKS5_PROXY=true
# On-by-default feature flag (a dashboard DB override wins over this value): proxy pools
# and per-account rotation stop re-serving a member that just failed (TCP probe refused, or a
# 429 received through it) for a period that doubles on each repeat, up to a cap. No proxy
# status is written. Unset keeps skipping; PROXY_SKIP_RECENTLY_FAILED=false restores plain selection.
# PROXY_SKIP_RECENTLY_FAILED=true
# Allow-list for local-core selector-control targets beyond loopback (comma/space
# separated hosts or IPs, "*" opens LAN/private but never metadata/link-local).
# Loopback (127.0.0.1, ::1, localhost) over http/https is allowed by default.
# A dashboard DB value wins over this variable when set and non-empty.
# Used by: src/lib/proxySubscription/selectorGuard.ts.
# SELECTOR_CONTROL_ALLOWLIST=
# Curve of the 429 set-aside (read once at startup; restart to apply).
# Base period for the first refusal through a proxy, doubled on each repeat.
# Bounded to 1000..3600000; out-of-range or unreadable falls back to 300000 with a warning.
# Used by: open-sse/utils/proxyRefusalMemory.ts.
# PROXY_QUOTA_429_BASE_MS=300000
# Cap of the 429 set-aside (read once at startup; restart to apply).
# Bounded to 1000..3600000; out-of-range or unreadable falls back to 900000 with a warning.
# When the cap is below the base, it falls back to the default 900000.
# Lowering the cap also shortens streak forgetting: entries purge 2 x max after expiry.
# PROXY_QUOTA_429_MAX_MS=900000
# Opt-in feature flag (default off; a dashboard DB override wins over this value): 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.
# PROXY_POOL_SHARED_EGRESS_ORDER=false
# Rebound window capping repeat set-aside webhook alerts per pool member (read on each emit; no restart needed).
# Bounded to 1000..3600000; out-of-range or unreadable falls back to 300000 with a silent default.
# Used by: src/lib/proxyEvents/proxyTransitionBridge.ts.
# PROXY_WEBHOOK_REBOUND_MS=300000
# Standard proxy variables (lowercase variants also supported).
# HTTP_PROXY=http://127.0.0.1:7890
# HTTPS_PROXY=http://127.0.0.1:7890
# ALL_PROXY=socks5://127.0.0.1:7890
# NO_PROXY=localhost,127.0.0.1
# Pin the echo-IP target used by proxy egress probes. Unset, the probe tries
# api64.ipify.org then api4.ipify.org so IPv4-only tunnels are not reported dead.
# Used by: src/lib/proxyEchoTarget.ts.
# OMNIROUTE_PROXY_ECHO_URL=https://api4.ipify.org?format=json
# Max concurrent sockets per cached HTTP/SOCKS proxy dispatcher.
# Long-lived SSE streams such as Codex /v1/responses need more than one
# connection when multiple requests share the same account-level proxy.
# Set to 1 only for legacy diagnostics. Values above 256 are capped.
# OMNIROUTE_PROXY_DISPATCHER_CONNECTIONS=32
# HTTP/2 negotiation for Undici upstream dispatchers (direct, HTTP/SOCKS proxies,
# relays and their retries). Explicit false/0/no/off forces HTTP/1.1.
# Does not control wreq TLS fingerprinting or provider-specific transports.
# Restart OmniRoute after changing this value; dispatchers are cached.
# OMNIROUTE_UPSTREAM_HTTP2_ENABLED=true
# Gzip the request body sent to the official api.anthropic.com (bodies of 4096+ characters, direct
# connections only; skipped behind a proxy, TLS impersonation or NODE_EXTRA_CA_CERTS). The API accepts
# gzip only (br/zstd/deflate answer 415). A refusal is resent uncompressed once and that origin stays
# uncompressed for one hour. Default on; set 0/false/off/no to disable.
# Used by: open-sse/executors/base/gzipRequestBody.ts
# OMNIROUTE_GZIP_REQUEST_BODIES=1
# Extra CA bundle for Node TLS (read by Node at startup). When set, outbound gzip request bodies
# are skipped, as Claude Code does, because a TLS-inspecting middlebox may not decode them.
# NODE_EXTRA_CA_CERTS=
# SOCKS5 handshake (connect) timeout in ms (default 10000, capped at 120000).
# Raise it when a single residential gateway host is hit by high concurrency
# (e.g. 100 simultaneous requests): the real SOCKS5 handshake can exceed 10s
# under a saturated pool even though the proxy is reachable, which otherwise
# surfaces as a false "[Proxy Fast-Fail] Proxy unreachable".
# SOCKS_HANDSHAKE_TIMEOUT_MS=10000
# Proxy fail-open mode (default: false = fail-closed).
# When false, a request whose assigned proxy fails to resolve is REFUSED rather than
# falling back to a direct connection — prevents real-IP leaks in egress-controlled
# deployments. Set true to restore the legacy DIRECT fallback (legacy behaviour).
# Used by: src/sse/handlers/chatHelpers.ts
# PROXY_FAIL_OPEN=false
# TLS fingerprint spoofing (opt-in) — mimics Chrome 124 TLS handshake via wreq-js.
# Reduces risk of JA3/JA4 fingerprint-based blocking by providers (e.g., Google).
# Used by: open-sse/executors — replaces Node.js default TLS fingerprint.
# ENABLE_TLS_FINGERPRINT=true
# New proxied TLS routing requires an explicit, comma-separated provider allowlist.
# Direct TLS keeps its legacy behavior when this is unset.
# TLS_FINGERPRINT_PROVIDERS=codex,openai
# Allow the Claude Turnstile Playwright browser context to ignore HTTPS certificate errors.
# Only enable for local debugging or trusted MITM/corporate proxy environments.
# Used by: open-sse/services/claudeTurnstileSolver.ts
# OMNIROUTE_TURNSTILE_IGNORE_TLS_ERRORS=false
# ═══════════════════════════════════════════════════════════════════════════════
# 9. CLI TOOL INTEGRATION
# ═══════════════════════════════════════════════════════════════════════════════
# Control how OmniRoute discovers and launches CLI sidecars (Claude, Codex, etc.).
# Used by: src/shared/services/cliRuntime.ts
# CLI discovery mode: auto = search PATH | manual = use explicit paths below.
# CLI_MODE=auto
# Additional PATH entries for finding CLI binaries (colon-separated).
# CLI_EXTRA_PATHS=/host-cli/bin:/usr/local/bin
# Home directory override for reading CLI config files (~/.claude, etc.).
# CLI_CONFIG_HOME=/root
# Allow OmniRoute to write CLI config files (token refresh, etc.).
# CLI_ALLOW_CONFIG_WRITES=true
# Force container detection on (1/true) or off (0/false). Leave unset for auto-detect
# via /.dockerenv, /run/.containerenv, cgroup markers, or KUBERNETES_SERVICE_HOST.
# Used by: src/shared/utils/containerEnv.ts — gates ephemeral-home CLI config writes.
# OMNIROUTE_CONTAINER=1
# Allow CLI-tool config writes into an unmounted container path anyway (default off).
# Prefer host-side `omniroute configure` / Remote Mode, or a bind-mounted CLI_CONFIG_HOME.
# CLI equivalent: --allow-container-write. Used by: src/shared/utils/containerEnv.ts
# OMNIROUTE_ALLOW_CONTAINER_CONFIG_WRITE=true
# Docker image only: dashboard "Update Now" writes a JSON update request to this file (it must
# be inside DATA_DIR; relative paths resolve against it). A host-side watcher pulls the image and
# recreates the container — no Docker socket is mounted. Unset = the dashboard shows the manual
# host command instead. Used by: src/lib/system/autoUpdate.ts (see docs/guides/DOCKER_GUIDE.md).
# DOCKER_UPDATE_TRIGGER_FILE=/app/data/update/docker-update.request
# Auto-sync CLI profile files after provider model discovery changes. OPT-IN, default OFF for
# both. When enabled, writes only the tool's profile files (~/.codex/*.config.toml or
# ~/.claude/profiles/<name>/settings.json); never changes the active/default config. Both also
# require CLI_ALLOW_CONFIG_WRITES (default on). Toggle from the CLI Code dashboard, or set here.
# Leave unset to disable. (Feature flags — a DB/dashboard override takes precedence over env.)
# OMNIROUTE_AUTO_SYNC_CODEX_PROFILES=true
# OMNIROUTE_AUTO_SYNC_CLAUDE_PROFILES=true
# Override binary paths for individual CLI tools.
# CLI_CLAUDE_BIN=claude
# CLI_CODEX_BIN=codex
# CLI_DROID_BIN=droid
# CLI_OPENCLAW_BIN=openclaw
# CLI_CURSOR_BIN=agent
# CLI_CLINE_BIN=cline
# CLI_CONTINUE_BIN=cn
# CLI_QODER_BIN=qodercli
# CLI_QWEN_BIN=qwen
# CLI_AIDER_BIN=aider
# CLI_GOOSE_BIN=goose
# CLI_GEMINI_BIN=gemini
# CLI_KILO_BIN=kilocode
# CLI_OPENCODE_BIN=opencode
# CLI_HERMES_BIN=hermes
# CLI_FORGE_BIN=forge
# CLI_JCODE_BIN=jcode
# CLI_DEEPSEEK_TUI_BIN=deepseek-tui
# CLI_CODEWHALE_BIN=codewhale
# CLI_SMELT_BIN=smelt
# CLI_PI_BIN=pi
# CLI_CRUSH_BIN=crush
# CLI_OMP_BIN=omp
# CLI_LETTA_BIN=letta
# CLI_PRIME_AGENT_BIN=prime-agent
# CLI_WHYCODES_BIN=whycodes
# Windsurf has no default binary — set this to enable binary detection for it.
# CLI_WINDSURF_BIN=windsurf
# CLI_AUGGIE_BIN=auggie
# CLI_5DIVE_BIN=5dive
# 5dive keeps root-owned auth profiles under a system state dir (its own STATE_DIR,
# default /var/lib/5dive); override here when it lives elsewhere.
# CLI_5DIVE_STATE_DIR=/var/lib/5dive
# AUGGIE_BIN=auggie
# ── ZCode (Z.ai GLM coding-plan CLI) local provider ──
# The local "zcode" provider talks to the authenticated ZCode app-server over a
# custom framed stdio protocol. Overrides below tune that stdio lifecycle.
# Transport: "app-server" (default) or "gateway". The gateway is EXPERIMENTAL and
# unsupported: it calls the Z.AI Coding Plan HTTP endpoint directly by reproducing
# the ZCode client protocol (pinned to client 0.16.9) and can break on a ZCode update.
# ZCODE_TRANSPORT=app-server
# ZCODE_BIN=zcode
# ZCODE_ARGS=["--some-flag"]
# ZCODE_CWD=
# If unset, native model selection uses the Individual Plan account profile and
# falls back to builtin:zai-coding-plan. Set an exact provider ID to pin one profile.
# ZCODE_PROVIDER_ID=account:zai-individual-coding-plan
# Examples: account:zai-start-plan or builtin:zai-coding-plan
# ZCODE_SERVER_RUNTIME_ROOT=~/.zcode/server
# ZCODE_SERVER_NODE=~/.zcode/server/node
# ZCODE_SERVER_ENTRY=~/.zcode/server/zcode-server.cjs
# ZCODE_STARTUP_TIMEOUT_MS=10000
# ZCODE_RPC_TIMEOUT_MS=30000
# ZCODE_TURN_TIMEOUT_MS=120000
# ZCODE_POLL_INTERVAL_MS=250
# ── MiniMax Code provider ──
# The "minimax-code" provider talks to the managed MiniMax subscription gateway
# (native tool calling) and keeps the credential in the user's own MiniMax
# profile (~/.minimax): it reads that profile to authenticate a request and
# writes the rotated credential back to it.
# Endpoint of the managed MiniMax gateway. This is an internal endpoint of
# the MiniMax Code app, not a documented public API: it can change without
# notice, and the request then fails with a 502 that names the transport.
# MINIMAX_CODE_GATEWAY_URL=https://agent.minimax.io/mavis/api/v1/llm/v1/messages
# MINIMAX_CODE_GATEWAY_TIMEOUT_MS=60000
# MINIMAX_CODE_GATEWAY_RETRIES=1
# Ceiling (in input tokens) of one request that is sent to the managed
# MiniMax gateway. A larger request is refused locally with a 413 instead
# of being forwarded. The default is the context window of the gateway
# (1000000, the window the gateway answers in); this value can lower that
# ceiling, never raise it above the window.
# MINIMAX_CODE_MAX_INPUT_TOKENS=1000000
# The context window the managed gateway is asked for. The default is the
# window the gateway answers in (1000000). Set it to 512000 to narrow the
# request to the window the MiniMax Code model catalog declares as the
# default of the models — the plan counts less of a request in it. Every
# other value is ignored.
# MINIMAX_CODE_CONTEXT_WINDOW=1000000
# MINIMAX_CODE_MAX_TOKENS=8192
# Path of the MiniMax Code auth profile, and of the profile directory it
# lives in.
# MINIMAX_CODE_AUTH_FILE=
# MINIMAX_CODE_PROFILE_DIR=
# Record of the profile to use when it holds several accounts. Empty picks
# the newest generation, which is the one the CLI itself refreshes.
# MINIMAX_CODE_AUTH_RECORD=
# Region of the MiniMax account: it decides the account endpoint that
# refreshes the token and the profile directory the credential is read from.
# MINIMAX_CODE_REGION=en
# Override the Hermes Agent home directory (where OmniRoute reads/writes the
# Hermes CLI config). Matches the env var the Hermes PowerShell installer sets
# on Windows (%LOCALAPPDATA%\hermes); defaults to ~/.hermes when unset.
# Used by: src/lib/cli-helper/config-generator/hermesHome.ts
# HERMES_HOME=~/.hermes
# Override the WhyCodes instance root (config.toml, sessions, memory). Same env
# var WhyCodes itself reads; defaults to ~/.whycodes (%USERPROFILE%\.whycodes on
# Windows) when unset.
# Used by: src/lib/cli-helper/config-generator/whycodesHome.ts
# WHYCODES_HOME=~/.whycodes
# ═══════════════════════════════════════════════════════════════════════════════
# 10. INTERNAL AGENT & MCP INTEGRATIONS
# ═══════════════════════════════════════════════════════════════════════════════
# Used by MCP server, A2A skills, and CLI sidecars to call the running instance.
# Explicit base URL for MCP/A2A tools to reach OmniRoute (overrides localhost auto-detect).
# For browser-visible generated image URLs, prefer OMNIROUTE_PUBLIC_BASE_URL above.
# Used by: open-sse/mcp-server/server.ts, src/lib/a2a/
# OMNIROUTE_BASE_URL=http://localhost:20128
# API key for internal tool calls (MCP tools, A2A skills).
# OMNIROUTE_API_KEY=
# API key ID for MCP audit logging.
# Used by: open-sse/mcp-server/audit.ts — tags audit events with a key identity.
# OMNIROUTE_API_KEY_ID=
# Legacy alias for OMNIROUTE_API_KEY.
# ROUTER_API_KEY=
# Days of A2A task history to keep before the daily purge deletes a row.
# Used by: src/lib/a2a/taskManager.ts (historyRetentionDays). Unset, non-numeric,
# or <= 0 falls back to the default.
# OMNIROUTE_A2A_HISTORY_RETENTION_DAYS=30
# Kill-switch for the A2A memory-hits observability feature (Orchestration Canvas
# Fase 2). Set to "0" to skip the memory recall lookup entirely; any other value
# (including unset) keeps it enabled.
# Used by: src/lib/a2a/taskExecution.ts (collectMemoryHits).
# OMNIROUTE_A2A_MEMORY_HITS=1
# Enable the offline/local Issue Agent recorded-triage endpoint.
# Used by: src/app/api/issue-agent/runs/route.ts. Default: disabled.
# OMNIROUTE_ISSUE_AGENT_ENABLED=false
# Timeout (ms) for a single Issue Agent recorded-triage run. Clamped to an internal
# maximum; falls back to the built-in default when unset or invalid.
# Used by: src/lib/issueAgent/execution.ts.
# OMNIROUTE_ISSUE_AGENT_TIMEOUT_MS=
# CLI remote-mode context/profile for `omniroute` commands (overrides the active
# context in the local contexts store). Equivalent to the `--context <name>` flag.
# Used by: bin/cli/program.mjs, bin/cli/api.mjs (remote mode).
# OMNIROUTE_CONTEXT=
# Disable the optional OS keychain backend for CLI remote-context credentials.
# When enabled, context tokens stay in config.json with mode 0600 and the CLI
# prints a one-time fallback warning. Useful for deliberate headless/container
# operation; leave unset to use keytar when the native backend is available.
# Used by: bin/cli/contexts.mjs.
# OMNIROUTE_CONTEXT_KEYCHAIN_DISABLED=0
# Enforce scope-based access control on MCP tool calls.
# Used by: open-sse/mcp-server/server.ts — rejects calls outside allowed scopes.
# OMNIROUTE_MCP_ENFORCE_SCOPES=false
# Comma-separated scopes granted to this MCP connection.
# Full list: admin, combos, health, models, routing, budget, metrics, pricing, memory, skills
# OMNIROUTE_MCP_SCOPES=admin,combos,health
# Register the Perplexity Deep Research MCP tool. Unset or any value other
# than 1 leaves it unregistered. A research run holds one connection for up to
# 45 minutes, so it stays off unless an operator turns it on.
# Used by: open-sse/mcp-server/tools/perplexityResearch.ts.
# OMNIROUTE_PPLX_RESEARCH_ENABLED=0
# Compress MCP tool descriptions before serializing the manifest.
# Used by: open-sse/mcp-server/descriptionCompressor.ts — reduces token spend
# for clients that read the full tool catalog.
# Accepted disabling values: 0, false, off. Default: enabled.
# OMNIROUTE_MCP_COMPRESS_DESCRIPTIONS=1
# Algorithm/profile used when description compression is enabled.
# Used by: open-sse/mcp-server/descriptionCompressor.ts
# Set to 0/false/off to skip compression entirely. Default: rtk
# OMNIROUTE_MCP_DESCRIPTION_COMPRESSION=rtk
# Abort budget (ms) for MCP-server internal management reads (health, resilience,
# combos, quota, usage). Default: 10000. Used by: open-sse/mcp-server/fetchTimeout.ts
# OMNIROUTE_MCP_FETCH_TIMEOUT_MS=10000
# Abort budget (ms) for MCP hops that wait on a provider (route_request, web_search,
# web_fetch). Default: 60000. Used by: open-sse/mcp-server/fetchTimeout.ts
# OMNIROUTE_MCP_UPSTREAM_TIMEOUT_MS=60000
# Idle TTL (ms) before the sweep reaps an idle MCP streamable session. A session
# with an open stream or an in-flight request is never reaped. Unset,
# non-integer, or non-positive values fall back to the default. Default: 300000.
# Used by: open-sse/mcp-server/httpTransport.ts
# OMNIROUTE_MCP_SESSION_IDLE_MS=300000
# Maximum number of local-corpus index instances cached in memory.
# Used by: src/lib/localCorpus/configured.ts — bounds the LRU cache of
# LocalCorpusIndex objects (one per indexed root directory). Default: 5.
# OMNIROUTE_CORPUS_CACHE_SIZE=5
# Model catalog sync interval in hours.
# Used by: src/shared/services/modelSyncScheduler.ts — periodic model refresh.
# Default: 24
# MODEL_SYNC_INTERVAL_HOURS=6
# Provider limits sync interval in minutes (rate limit windows, quotas).
# Used by: src/lib/usage/providerLimits.ts — polls provider health endpoints.
# Default: 70
PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70
# Gap (ms) between consecutive OAuth quota fetches in a bulk provider-limits sync.
# OAuth providers are fetched one at a time with this spacing so a single host
# never bursts simultaneous usage/refresh requests to the same upstream. Set to 0
# to opt out (restores fully concurrent fetches). Default: 1500
PROVIDER_LIMITS_SYNC_SPACING_MS=1500
# Min interval (ms) between consecutive UPSTREAM quota fetches on the per-request
# preflight/monitor path (e.g. Codex /wham/usage), complementing the bulk-sync
# spacing above. Many accounts on one IP fetching quota in the same second can look
# like automation to the upstream and get an OAuth token revoked (#6009). This gate
# serializes genuine network calls (cache hits are unaffected). Set to 0 to disable.
# Default: 250 (clamped 0..60000).
# OMNIROUTE_QUOTA_FETCH_MIN_INTERVAL_MS=250
# Extra random spacing (ms) per quota request. Default: 120 (clamped 0..60000).
# For multiple Codex accounts, increase the minimum interval first; jitter adds
# unpredictable spacing. This cannot guarantee the upstream won't revoke a token.
# OMNIROUTE_QUOTA_FETCH_JITTER_MS=120
# Timeout (ms) for one Codex quota fetch (chatgpt.com /wham/usage). The preflight
# waits for this fetch before sending the request. On a timeout the last recent
# snapshot is reused unless its window is exhausted or has reset; with none, the
# quota is unknown, not exhausted. Raise it on slow links. Positive integer.
# Default: 8000
# CODEX_QUOTA_FETCH_TIMEOUT_MS=8000
# Delay (ms) before refreshing provider limits after a real usage event (e.g. a
# completed request). Gives the upstream quota API time to register the consumption
# before the dashboard polls. Default: 5000
#PROVIDER_LIMITS_POST_USAGE_REFRESH_DELAY_MS=5000
# Disable all background services (sync, pricing, model refresh, connection recovery,
# credential health, retention cleanup, scheduled VACUUM, settings hot-reload poll).
# Used by: src/lib/env/backgroundServices.ts, src/lib/initCloudSync.ts
# Useful for: CI builds, test environments, or resource-constrained containers.
# OMNIROUTE_DISABLE_BACKGROUND_SERVICES=false
# Source directory for the explicit --prepare Video Bridge validation command.
# Must be an absolute directory containing storage.sqlite. The source is opened
# read-only; copied credentials and test keys stay in a private temporary directory.
# Used only by: scripts/ad-hoc/video-live-isolation.ts (not normal server startup).
# OMNIROUTE_VIDEO_LIVE_SOURCE_DIR=
# Headless mode (R0.1): boot only the proxy engine (/v1/*, /api/monitoring/health,
# auth). Optional boot subsystems are skipped and /dashboard + /home answer 404.
# Same as `omniroute serve --headless`. See docs/guides/HEADLESS.md.
# Used by: src/lib/system/headless.ts. Default: unset (full server).
# OMNIROUTE_HEADLESS=1
# Force runtime background tasks (healthchecks/sync) even under automated test
# detection. Used by: src/lib/config/runtimeSettings.ts — overrides the test
# heuristic in instrumentation-node.ts. Default: unset (tests skip background).
#OMNIROUTE_ENABLE_RUNTIME_BACKGROUND_TASKS=1
# Proactive connection-cooldown recovery (#8): re-validates connections whose
# transient `rate_limited_until` window has elapsed OUTSIDE the request hot path,
# so the first request after a cooldown does not pay the probe latency. Lazy
# recovery in getProviderCredentials still applies regardless. Used by:
# src/lib/quota/connectionRecovery.ts.
# Tick cadence (ms). Default 60000, floor 5000.
# OMNIROUTE_CONNECTION_RECOVERY_INTERVAL_MS=60000
# Disable the proactive recovery scheduler entirely (default: false).
# OMNIROUTE_DISABLE_CONNECTION_RECOVERY=false
# Proactive Claude warmup scheduler (#8848): fires a trivial request to opted-in
# OAuth connections on a cron schedule (America/Los_Angeles) so accounts do not
# hit the 5-hour sliding window cold. Off by default — set ENABLED=1 and flip
# per-connection flags in settings.claudeWarmup.connections to activate.
# Used by: src/lib/warmupScheduler.ts.
# OMNIROUTE_WARMUP_ENABLED=false
# OMNIROUTE_WARMUP_CRON="0 7 * * *"
# OMNIROUTE_WARMUP_CONCURRENCY=3
# OMNIROUTE_WARMUP_MODEL=
# Background job interval for budget reset checks (ms). Default: 600000 (10m).
# Used by: src/lib/jobs/budgetResetJob.ts. Floor: 10000.
#OMNIROUTE_BUDGET_RESET_JOB_INTERVAL_MS=600000
# Cron expression for the call-log export job (destinations configured in the
# dashboard under Integrations > Log export). Default: hourly, on the hour.
# Used by: src/lib/jobs/logExportJob.ts. Timezone: UTC.
#OMNIROUTE_LOG_EXPORT_CRON=0 * * * *
# Isolated log-export child: per-destination wall-clock timeout and V8 old-space cap.
# Prefer a minute-level cron (e.g. */5 * * * *) when exporting request/response bodies.
# Used by: src/lib/logExport/childRunner.ts. Positive integers only; invalid values use defaults.
#OMNIROUTE_LOG_EXPORT_RUN_TIMEOUT_MS=900000
#OMNIROUTE_LOG_EXPORT_CHILD_MAX_OLD_SPACE_MB=1024
# Emergency budget-exhaustion fallback (set false or 0 to disable the reroute to
# nvidia/nvidia/nemotron-3.5-super-vl-120b-a12b when a request fails with a 402 budget error).
# Used by: open-sse/services/emergencyFallback.ts. Default: enabled.
#OMNIROUTE_EMERGENCY_FALLBACK=true
# Reasoning cache cleanup cadence (ms). Default: 1800000 (30m). Floor: 60000.
# Used by: src/lib/jobs/reasoningCacheCleanupJob.ts.
#OMNIROUTE_REASONING_CACHE_CLEANUP_INTERVAL_MS=1800000
# Recover from a reasoning_effort 4xx whose body names no accepted set, by
# probing one tier down and learning that tier when the probe is answered.
# Comma-separated provider ids, or * for all. Default: unset (disabled).
# Off by default because an opaque 4xx carries no signal that the *effort* was
# the cause — a 2xx on the probe could mask an unrelated validation failure and
# pin a reasoning cap that was never proven. Upstreams that DO name their
# accepted set are already handled without this flag.
#OMNIROUTE_REASONING_EFFORT_PROBE_PROVIDERS=
# Opt-in minimum output budget (tokens) for reasoning models (#10281 follow-up).
# When set, a caller max_tokens in [256, floor) on a thinking-capable model is
# raised to the floor so reasoning tokens cannot consume the whole budget
# (zero-content finish_reason=length turns). Unset = never enlarge client budgets (#9507).
#OMNIROUTE_REASONING_MIN_BUDGET=4096
# Spend write batcher cadence (ms) and buffer size before forced flush.
# Used by: src/lib/spend/batchWriter.ts. Defaults: 60000 ms / 1000 entries.
#OMNIROUTE_SPEND_FLUSH_INTERVAL_MS=60000
#OMNIROUTE_SPEND_MAX_BUFFER_SIZE=1000
# Batch request processor retry, backoff, and concurrency settings.
# Used by: open-sse/services/batchProcessor.ts. Defaults shown.
#BATCH_RETRY_DURATION_MS=86400000
#BATCH_BACKOFF_BASE_MS=5000
#BATCH_BACKOFF_MAX_MS=3600000
#BATCH_MAX_CONCURRENT=1
# Config hot-reload polling interval (ms). Default: 5000.
# Used by: src/lib/config/hotReload.ts. Lower than 1000ms is rejected.
#OMNIROUTE_CONFIG_HOT_RELOAD_MS=5000
# Override the migrations directory used by src/lib/db/migrationRunner.ts.
# Default: <repo>/src/lib/db/migrations.
#OMNIROUTE_MIGRATIONS_DIR=
# Additional migration directories, as `namespace=dir` entries separated by the
# platform path delimiter (`:` on POSIX, `;` on Windows). Files found there are
# recorded as `<namespace>-<number>` (e.g. `ee-134`), a version space that cannot
# collide with the upstream numeric slots — so a distribution shipping its own
# migrations never silently loses one to a number the upstream set also claimed.
# A malformed entry, an invalid namespace or a missing directory aborts startup
# rather than skipping the schema. Unset = no extra directories (the default).
#OMNIROUTE_EXTRA_MIGRATIONS_DIRS=ee=/opt/app/enterprise/db/migrations
# Mass-pending-migrations safety threshold (#3416). If more than this many
# migrations are pending on an existing DB, startup aborts (a wiped tracking
# table could cause data loss). Raise it to restore an older backup; set to 0
# to disable the check. Used by: src/lib/db/migrationRunner.ts. Default: 50.
#OMNIROUTE_MAX_PENDING_MIGRATIONS=50
# Working directory for the check:install-upgrade release gate. It builds two ~3 GB
# install trees plus a ~275 MB tarball, so it needs roughly 12 GB — more than the
# 12 GB RAM-backed tmpfs that /tmp is on the self-hosted runner, where it exhausted
# the tmpfs and npm silently truncated the package. Defaults to <repo>/.install-upgrade
# on real disk. Used by: scripts/check/check-install-upgrade.mjs. Default: <repo>/.install-upgrade.
#OMNIROUTE_INSTALL_UPGRADE_WORKDIR=/var/tmp/omniroute-install-upgrade
# Trust user-managed RTK project filter rules without strict signature checks.
# Used by: open-sse/services/compression/engines/rtk/filterLoader.ts. Default: 0.
#OMNIROUTE_RTK_TRUST_PROJECT_FILTERS=0
# Character cap for Lite proactive tool-result truncation when lite.maxToolLength
# is unset. Range 256-1000000. Dashboard setting wins over this env.
# Used by: open-sse/services/compression/lite.ts. Default: 2000.
#OMNIROUTE_LITE_MAX_TOOL_LENGTH=2000
# Maximum concurrent synchronous compression workers. Excess jobs wait FIFO.
# Used by: open-sse/services/compression/compressionWorkerPool.ts. Default: 2.
#OMNI_COMPRESSION_WORKERS=2
# Per-job worker timeout (ms). A timed-out worker is terminated and the request fails open.
# Used by: open-sse/services/compression/compressionWorkerPool.ts. Default: 120000.
#OMNI_COMPRESSION_WORKER_TIMEOUT_MS=120000
# Terminate idle compression workers after this many milliseconds.
# Used by: open-sse/services/compression/compressionWorkerPool.ts. Default: 60000.
#OMNI_COMPRESSION_WORKER_IDLE_MS=60000
# V8 old-generation heap cap (MB) for each compression worker (all modes; floor 128). A job that
# exceeds it fails open (request goes upstream uncompressed) instead of growing the gateway heap.
# Used by: open-sse/services/compression/compressionWorkerPool.ts. Default: 1024.
#OMNI_COMPRESSION_WORKER_MAX_OLD_MB=1024
# T02 stacked-pipeline engine circuit-breaker (OPT-IN, default off). When enabled, a compression
# engine that throws repeatedly across requests is skipped (fail-open) for a cooldown.
# Used by: open-sse/services/compression/pipelineEngineBreaker.ts.
#COMPRESSION_PIPELINE_BREAKER_ENABLED=false # master switch (default false)
#COMPRESSION_PIPELINE_BREAKER_THRESHOLD=3 # consecutive failures before the engine opens
#COMPRESSION_PIPELINE_BREAKER_COOLDOWN_MS=30000 # ms the engine stays skipped before a probe
# T08/H8 — CCR retrieval-feedback ramp factor. Each prior retrieval of a stored block raises its
# effective minChars linearly, so frequently-retrieved content is compressed progressively less
# (>= 3 retrievals = never compressed). 1 disables the ramp (binary skip at the threshold only).
# Used by: open-sse/services/compression/engines/ccr/index.ts. Default: 2.
#COMPRESSION_CCR_RETRIEVAL_RAMP_FACTOR=2
# CCR durable block store (#9061). The in-memory store loses blocks to LRU eviction, the TTL, a
# restart, or a retrieve landing on another instance, while the model is told it can retrieve them
# verbatim. Set to false to keep blocks in memory only, at the cost of that promise. Blocks over
# 512KB and cloud runtimes are memory-only regardless.
# Used by: open-sse/services/compression/engines/ccr/index.ts. Default: true.
#COMPRESSION_CCR_DURABLE_STORE=true
# T08/H5 — usage-observed prefix freeze (OPT-IN, default off). When enabled, a system prompt seen
# >= THRESHOLD times is treated as a stable cacheable prefix and preserved from compression even
# for providers the static cache-aware heuristic does not recognize (freeze = preserve, never
# mutates). Used by: open-sse/services/compression/prefixFreeze.ts.
#COMPRESSION_PREFIX_FREEZE_ENABLED=false # master switch (default false)
#COMPRESSION_PREFIX_FREEZE_THRESHOLD=3 # observations before a prefix is frozen
# Skip the postinstall native-runtime warm-up (useful in CI / headless installs). Default: 0.
# Used by: scripts/postinstall.mjs.
#OMNIROUTE_SKIP_POSTINSTALL=0
# Operator-supplied JSON credentials for the offline compression-eval CLI
# (parsed with JSON.parse; leave unset for a dry run). Developer tooling only.
# Used by: scripts/compression-eval/index.ts. Default: {} (empty).
#OMNIROUTE_EVAL_CREDENTIALS={}
# Skip the DB healthcheck entirely on startup (useful for short-lived tasks / tests).
# Used by: src/lib/db/core.ts, src/lib/db/healthCheck.ts. Set to 1 to disable. Default: 0.
#OMNIROUTE_SKIP_DB_HEALTHCHECK=0
# Force a DB healthcheck regardless of cadence. Default: 0.
# Used by: src/lib/db/core.ts::shouldRunDbHealthCheck().
#OMNIROUTE_FORCE_DB_HEALTHCHECK=0
# DB healthcheck cadence override (ms). Default: 21600000 (6h).
# Used by: src/lib/db/core.ts::getDbHealthCheckIntervalMs().
#OMNIROUTE_DB_HEALTHCHECK_INTERVAL_MS=21600000
# Removed: periodic live wal_checkpoint(TRUNCATE) could SIGBUS the process (issue
# #13973). The variable is inert: a positive value logs a one-time deprecation warning,
# while 0 or unset stays silent. The WAL is kept small
# by the PASSIVE scheduler below and truncated by the shutdown checkpoint.
#OMNIROUTE_WAL_TRUNCATE_INTERVAL_MS=21600000
# Frequent wal_checkpoint(PASSIVE) cadence (ms). Set to 0 to disable. Default: 300000 (5m).
# Used by: src/lib/db/walMaintenance.ts.
#OMNIROUTE_WAL_PASSIVE_INTERVAL_MS=300000
# WAL size (MB) above which a PASSIVE tick runs wal_checkpoint(RESTART) so the
# WAL starts over without rewriting the mapped wal-index. Default: 256.
# Used by: src/lib/db/walMaintenance.ts.
#OMNIROUTE_WAL_GUARD_MAX_MB=256
# Explicit path to sql-wasm.wasm for the sql.js fallback adapter. Default: auto-detect.
# Used by: src/lib/db/adapters/sqljsAdapter.ts.
#OMNIROUTE_SQLJS_WASM_PATH=
# Days a terminal (completed/failed/cancelled/expired) Batch API job's checkpoints,
# referenced files, and row are kept by the automatic cleanup sweep. Default: 30
# (matches OpenAI's own Batch API output retention window). Only takes effect once
# BATCH_AND_FILE_AUTO_CLEANUP_ENABLED is turned on.
# Used by: src/lib/db/cleanup.ts::getBatchRetentionDays().
#OMNIROUTE_BATCH_RETENTION_DAYS=30
# Let the automatic cleanup sweep delete terminal Batch API jobs (and their
# checkpoints) past OMNIROUTE_BATCH_RETENTION_DAYS, and clear the 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.
# Used by: src/lib/db/cleanup.ts (feature flag; see docs/reference/FEATURE_FLAGS.md).
#BATCH_AND_FILE_AUTO_CLEANUP_ENABLED=false
# Skip the Redis-backed auth cache used by API key lookups (forces DB reads).
# Used by: src/lib/db/apiKeys.ts. Set to 1 to disable. Default: enabled.
#OMNIROUTE_DISABLE_REDIS_AUTH_CACHE=0
# Flag set by bootstrap script after initial setup is complete.
# Used by: src/app/(dashboard)/dashboard/page.tsx — shows setup wizard vs. dashboard.
# OMNIROUTE_BOOTSTRAPPED=false
# Allow request body to override the Antigravity project field.
# Used by: open-sse/executors/antigravity.ts — escape hatch for multi-project setups.
# OMNIROUTE_ALLOW_BODY_PROJECT_OVERRIDE=0
# Control Antigravity Google One AI credit usage. Used by:
# open-sse/services/antigravityCredits.ts — accepts off, retry, or always.
# off (default): never use credits; retry: use credits once after eligible quota 429;
# always: use credits on the first request (higher account and spend risk).
#ANTIGRAVITY_CREDITS=off
# Upstream 429s tolerated per Antigravity (agy/antigravity) request, across all
# hosts, before the 429 is returned to the caller (1..12). A request body that
# spent this budget is answered locally on re-send for 2 min (doubling up to
# 30 min, or the upstream retry hint) so a client retry loop never reaches Google.
# Used by: open-sse/services/antigravity429Guard.ts. Default: 2.
#ANTIGRAVITY_MAX_429_ATTEMPTS=2
# Preferred API-key account response-start failover (opt-in, all providers).
# Only when an eligible sibling exists; one hop, no shared-account cooldown.
# Default: 20s; Antigravity/agy: 5s; Antigravity Gemini 3.8 Flash: 12s.
# Per-provider and per-model overrides are available in Settings > Resilience.
# An environment change requires restart; saved UI settings do not.
# OMNIROUTE_PREFERRED_ACCOUNT_FAILOVER_ENABLED=false
# Override the path to the Antigravity CLI (agy) token file read by the
# "auto-detect local login" import. Used by:
# src/app/api/providers/agy-auth/apply-local/route.ts — for non-standard installs.
# Default: ~/.gemini/antigravity-cli/antigravity-oauth-token
#AGY_TOKEN_FILE=
# ═══════════════════════════════════════════════════════════════════════════════
# 11. OAUTH PROVIDER CREDENTIALS
# ═══════════════════════════════════════════════════════════════════════════════
# Built-in default credentials for localhost development.
# For remote/VPS deployments, register your own at each provider's developer console.
# The bootstrap-env script auto-populates these in .env if missing.
# Can also be overridden via data/provider-credentials.json where supported.
# ── Claude Code (Anthropic) ──
CLAUDE_OAUTH_CLIENT_ID=9d1c250a-e61b-44d9-88ed-5944d1962f5e
# Custom redirect URI override for Claude OAuth callback.
# CLAUDE_CODE_REDIRECT_URI=https://platform.claude.com/oauth/code/callback
# ── Codex / OpenAI ──
CODEX_OAUTH_CLIENT_ID=app_EMoamEEZ73f0CkXaXp7hrann
# Milliseconds to wait between consecutive Codex token refreshes.
# Used by: open-sse/services/refreshSerializer.ts. Default: 0 (no spacing).
# CODEX_REFRESH_SPACING_MS=0
# ── Trae (ByteDance) ──
# Trae stream idle timeout (ms). Default: 300000 (5 min).
# Used by: open-sse/executors/trae.ts.
# TRAE_STREAM_TIMEOUT_MS=300000
# Trae OAuth token override. Used by: open-sse/executors/trae.ts.
# TRAE_TOKEN=
# Trae web client Origin/Referer override (fleet-wide bump if Trae moves hosts
# again without a code change). Default: https://work.trae.ai.
# Used by: open-sse/executors/trae.ts.
# TRAE_WEB_ORIGIN=https://work.trae.ai
# ── Gemini / Antigravity (Google-based) ──
# These providers ship public OAuth client_id/secret values embedded in their
# public CLIs. Defaults are baked into the code via
# open-sse/utils/publicCreds.ts — leave the env vars unset to use them. Only
# set these if you registered your own OAuth app and want to use your own
# credentials instead. See docs/security/PUBLIC_CREDS.md for context.
#
# GEMINI_OAUTH_CLIENT_ID=
# GEMINI_OAUTH_CLIENT_SECRET=
# ANTIGRAVITY_OAUTH_CLIENT_ID=
# ANTIGRAVITY_OAUTH_CLIENT_SECRET=
# ── Kimi Coding (Moonshot) ──
KIMI_CODING_OAUTH_CLIENT_ID=17e5f671-d194-4dfb-9706-5516cb48c098
# ── Muse Code (Meta) ──
# Public device-flow client id is baked into open-sse/utils/publicCreds.ts (muse_id).
# Set this only to override the Muse CLI client. Do not put the public id here.
# MUSE_CODE_OAUTH_CLIENT_ID=
# ── GitHub Copilot ──
GITHUB_OAUTH_CLIENT_ID=Iv1.b507a08c87ecfe98
# ── GitHub Enterprise (GHE) Copilot ──
# Optional override for GHE Copilot's OAuth client id. Falls back to the public
# GITHUB_OAUTH_CLIENT_ID default when unset. Used by: src/lib/oauth/constants/oauth.ts.
# GHE_COPILOT_OAUTH_CLIENT_ID=
# ── GitLab Duo ──
# Register an OAuth app at: https://gitlab.com/-/profile/applications
# Set redirect URI to: http://localhost:20128/callback (or your NEXT_PUBLIC_BASE_URL + /callback)
# Required scopes: ai_features, read_user (matches GITLAB_DUO_CONFIG.scope in src/lib/oauth/constants/oauth.ts)
# GITLAB_DUO_OAUTH_CLIENT_ID=***
# GITLAB_DUO_OAUTH_CLIENT_SECRET=*** # optional — PKCE flow does not require a secret
#
# Self-managed GitLab Duo instance overrides.
# Used by: src/lib/oauth/gitlab.ts and src/lib/oauth/constants/oauth.ts —
# fall back to these when the _DUO_ variants above are unset.
#GITLAB_DUO_BASE_URL=https://gitlab.com
#GITLAB_BASE_URL=https://gitlab.com
#GITLAB_OAUTH_CLIENT_ID=
#GITLAB_OAUTH_CLIENT_SECRET=
# ── Qoder ──
# Public OAuth client secret embedded in the Qoder CLI binary. Required only
# when QODER_OAUTH_AUTHORIZE_URL / TOKEN_URL / USERINFO_URL / CLIENT_ID are
# also set (see QODER_CONFIG.enabled in src/lib/oauth/constants/oauth.ts).
# Extract the value from the public Qoder CLI binary if you intend to use it.
# QODER_OAUTH_CLIENT_SECRET=
# ── Qoder Browser OAuth (experimental) ──
# OmniRoute only enables the browser OAuth flow when ALL 5 variables below are set:
# - QODER_OAUTH_AUTHORIZE_URL
# - QODER_OAUTH_TOKEN_URL
# - QODER_OAUTH_USERINFO_URL
# - QODER_OAUTH_CLIENT_ID
# - QODER_OAUTH_CLIENT_SECRET
#
# Redirect URI to register in the Qoder OAuth app:
# - Localhost dev with PORT=20128: http://localhost:20128/callback
# - LAN access (example): http://192.168.0.15:20128/callback
# - Public domain (recommended): https://omniroute.example.com/callback
#
# Behind reverse proxy / public domain, also set NEXT_PUBLIC_BASE_URL to the same public origin.
# If these values are not available, prefer QODER_PERSONAL_ACCESS_TOKEN below.
# QODER_OAUTH_AUTHORIZE_URL=
# QODER_OAUTH_TOKEN_URL=
# QODER_OAUTH_USERINFO_URL=
# QODER_OAUTH_CLIENT_ID=
# QODER_OAUTH_CLIENT_SECRET=
# ── Qoder Personal Access Token (direct API key fallback) ──
# Used by: open-sse/executors/qoder.ts — bypasses OAuth when set.
# QODER_PERSONAL_ACCESS_TOKEN=
# QODER_CLI_WORKSPACE=
# OMNIROUTE_QODER_WORKSPACE=
# Override the Qoder CLI config dir (isolated PAT session, avoids clobbering a browser login).
# QODER_CLI_CONFIG_DIR=
# Every qodercli --print run is a separate ~750 MB Node process. Set a cap to
# bound how many run at once (others queue FIFO) and how long a request may wait
# for a slot (then 429 qodercli_busy + Retry-After). Unset = no cap (default).
# QODER_CLI_MAX_CONCURRENCY=2
# QODER_CLI_QUEUE_TIMEOUT_MS=120000
# "acp" keeps one persistent `qodercli --acp` process per PAT and runs each request
# as an ACP session instead of spawning qodercli per request (default: print).
# QODER_CLI_TRANSPORT=print
# QODER_CLI_ACP_IDLE_TIMEOUT_MS=600000
# QODER_CLI_ACP_STARTUP_TIMEOUT_MS=60000
# QODER_CLI_ACP_MAX_SESSIONS_PER_PROCESS=500
# ── Blackbox Web validated-token override (issue #2252) ──
# Used by: open-sse/executors/blackbox-web.ts. Blackbox `/api/chat` rejects
# requests whose `validated` field doesn't match the frontend `tk` token,
# returning HTTP 403 even with a valid session cookie + active subscription.
# Set this to the `tk` value exported from app.blackbox.ai's Next.js bundle
# to bypass the random-UUID fallback. Leave empty to keep the legacy behavior.
# BLACKBOX_WEB_VALIDATED_TOKEN=
# ── Vision Bridge OpenAI-compatible endpoint override (issue #2232) ──
# Used by: src/lib/guardrails/visionBridgeHelpers.ts. By default the
# vision-bridge guardrail sends non-Anthropic image-description calls to
# `https://api.openai.com/v1`, which fails with 401 if your operator doesn't
# have an OpenAI key or wants to use a different vision model
# (e.g., `google/gemini-2.0-flash` via the Gemini OpenAI-compat endpoint, or
# any model registered in OmniRoute via the self-loop endpoint).
#
# Set these two env vars to point the bridge at any OpenAI-compatible URL:
# - VISION_BRIDGE_BASE_URL=http://localhost:20128/v1 (OmniRoute self-loop)
# - VISION_BRIDGE_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai
# - VISION_BRIDGE_BASE_URL=https://openrouter.ai/api/v1
# Anthropic models (anthropic/*) keep their dedicated path and are unaffected.
# VISION_BRIDGE_BASE_URL=
# VISION_BRIDGE_API_KEY=
# How long a "no usable vision candidate" outcome is remembered, in ms.
# Invalid or negative values fall back to the default; 0 disables the negative cache.
# OMNIROUTE_VISION_BRIDGE_NEGATIVE_CACHE_MS=30000
# ─────────────────────────────────────────────────────────────────────────────
# ⚠️ GOOGLE OAUTH (Antigravity) & OTHER PROVIDERS — REMOTE SERVERS
# ─────────────────────────────────────────────────────────────────────────────
# The default Client IDs above ONLY work when OmniRoute runs on localhost.
# For remote/VPS hosting (including Docker containers on remote servers):
# 1. By default, the browser will attempt OAuth redirects back to localhost, which will fail.
# 2. Set NEXT_PUBLIC_BASE_URL=https://your-domain.com to fix the redirect URI.
# 3. You MUST create your own OAuth App in each provider's developer console (Google Cloud, etc.)
# and set the Authorized redirect URI to your domain (e.g., https://your-domain.com/callback).
# 4. Replace the _OAUTH_CLIENT_ID and _SECRET values above with your own credentials.
# ─────────────────────────────────────────────────────────────────────────────
# ── OAuth sidecar/CLI bridge (internal) ──
# Used by: src/lib/oauth/config/index.ts — internal CLI↔OmniRoute auth bridge.
# OMNIROUTE_SERVER=http://localhost:20128
# OMNIROUTE_TOKEN=
# OMNIROUTE_USER_ID=cli
# CLI_TOKEN= # legacy alias for OMNIROUTE_TOKEN
# CLI_USER_ID= # legacy alias for OMNIROUTE_USER_ID
# SERVER_URL= # legacy alias for OMNIROUTE_SERVER
# ═══════════════════════════════════════════════════════════════════════════════
# 12. PROVIDER USER-AGENT OVERRIDES
# ═══════════════════════════════════════════════════════════════════════════════
# Customize the User-Agent header sent to each upstream provider.
# Format: {PROVIDER_ID}_USER_AGENT=custom-value
# Used by: open-sse/executors/base.ts — buildHeaders() dynamic lookup.
# Update these when providers release new CLI versions to avoid blocks.
# Optional override (leave unset: the built-in pinned version is used; prefer CLAUDE_CODE_CLIENT_VERSION).
# A claude-cli/X.Y.Z value older than the pinned version is ignored at runtime (#15740).
# CLAUDE_USER_AGENT="claude-cli/2.1.280 (external, cli)"
# Disable the deterministic tool-name cloak applied on both Anthropic-bound paths
# (executors/base.ts native OAuth + executors/cliproxyapi.ts CLIProxyAPI) —
# third-party-harness tool names are aliased to
# Claude Code canonical or PascalCase forms so Anthropic does not refuse the
# stream with a misleading 400 out-of-extra-usage placeholder. Set to true to
# forward the original names verbatim (debugging only).
# CLAUDE_DISABLE_TOOL_NAME_CLOAK=false
# Optional override; leave unset to follow the shared Codex client version.
# CODEX_USER_AGENT="codex-cli/0.155.0 (Windows 10.0.26200; x64)"
GITHUB_USER_AGENT="GitHubCopilotChat/0.54.0"
# Optional override for the Antigravity CLI (`agy`) build changelist reported as `cl=` in
# the CLI User-Agent. Google's Piper changelist is not derivable from the version and is not
# exposed by the public auto-updater manifests, so it is seeded from a live capture per
# version (1.4.4 -> 1003595037). Unset on an unknown version omits `cl=` entirely rather
# than advertising another build's changelist.
# ANTIGRAVITY_CLI_CL=1003595037
KIRO_USER_AGENT="AWS-SDK-JS/3.0.0 kiro-ide/1.0.0"
# KIRO_VERIFY_FULL_CRC=false # opt-in: full per-frame message CRC validation on the Kiro event stream (debug corrupted streams; prelude CRC + TLS already protect framing)
# Optional override for the Kiro social device-code OAuth clientId. Kiro's
# device endpoint accepts any non-empty string and behaves like a User-Agent
# rather than a secret. Only override if AWS ever starts enforcing this field.
# Used by: src/lib/oauth/constants/oauth.ts (KIRO_CONFIG.socialClientId).
# KIRO_OAUTH_CLIENT_ID=kiro-cli
# Enable full per-frame message CRC validation for Kiro streams. Off by default
# because it is O(frame bytes) on the main thread; use only for debugging
# suspected corrupted-stream issues.
# Used by: open-sse/executors/kiro.ts
# KIRO_VERIFY_FULL_CRC=false
# USD price of one Kiro credit. Kiro bills each request in credits reported by
# `meteringEvent` frames; they are converted with this price into the exact
# per-request cost used by quotas, budgets and analytics.
# Used by: open-sse/executors/kiroCredits.ts
# KIRO_CREDIT_PRICE_USD=0.02
# Fail a Kiro response that ends without credit metering (and validate every
# metering frame strictly) instead of recording it with no billable cost.
# Used by: open-sse/executors/kiro.ts
# KIRO_REQUIRE_CREDITS=false
QODER_USER_AGENT="Qoder-Cli"
CURSOR_USER_AGENT="Cursor/3.4"
# Override Codex client version sent in headers independently of the
# CODEX_USER_AGENT string. Used by: open-sse/config/codexClient.ts.
# CODEX_CLIENT_VERSION=0.155.0
#
# Override x-grok-client-version for inference, model sync, and device-code OAuth,
# plus the default User-Agent for inference and model sync. Accepts SemVer (including
# prerelease/build metadata), up to 128 characters; surrounding spaces are trimmed.
# Unset, empty, invalid, or line-break-containing values fall back to the shipped pin.
# Used by: open-sse/config/grokBuild.ts. GROK_CLI_USER_AGENT still overrides the full UA.
# GROK_CLI_CLIENT_VERSION=1.0.41
#
# Override the advertised Claude Code client version independently of
# CLAUDE_USER_AGENT. Anthropic gates some models (Fable 5.1) on this
# value; a UA-only override is not enough (#12417). Used by:
# src/shared/constants/claudeCodeClient.ts.
# CLAUDE_CODE_CLIENT_VERSION=2.1.259
#
# Override the 3-character suffix OmniRoute appends to `cc_version=` in the
# Claude billing block (captured pin: `1e2`). Bump it alongside the version:
# pinning only the version advertises a `version.revision` pair that no real
# binary emits. Used by: src/shared/constants/claudeCodeClient.ts.
# CLAUDE_CODE_CLIENT_BUILD_REVISION=1e2
#
# Override the advertised GitHub Copilot CLI version independently of
# GITHUB_USER_AGENT. Used by: open-sse/config/providerHeaderProfiles.ts.
# GITHUB_COPILOT_CLI_VERSION=1.0.91
#
# Pin the `copilot-integration-id` header sent to standard GitHub Copilot,
# overriding the default copilot-developer-cli identity (and disabling the
# automatic 403-identity fallback to copilot-chat). Set this only if your
# Copilot account/org requires a specific integration id. Used by:
# open-sse/config/providerHeaderProfiles.ts, open-sse/executors/copilotIdentityFallback.ts.
# COPILOT_INTEGRATION_ID=copilot-chat
# Kill-switch to strip non-standard `codex.*` SSE events (e.g. codex.rate_limits)
# from the Codex Responses stream. These frames break the OpenAI SDK's
# responses.stream() with a 502 "Controller is already closed". Off by default;
# set to true/1/yes to enable. Used by: open-sse/executors/codex.ts.
# OMNIROUTE_CODEX_DROP_NONSTANDARD_EVENTS=true
# Codex app-server WebSocket transport (opt-in). When a WebSocket URL and a
# capability token are both provided, Codex requests are routed through a local
# `codex app-server` sidecar over JSON-RPC instead of the HTTP Responses API.
# Each var is also settable per-connection via providerSpecificData; the env var
# is the process-wide fallback. Used by:
# open-sse/executors/codex/appServerConfig.ts.
#
# WebSocket endpoint of the codex app-server (ws:// or wss://). Required to
# enable the transport; leaving it unset keeps Codex on its HTTP transports.
# OMNIROUTE_CODEX_APPSERVER_WS=ws://127.0.0.1:8081
# Inline capability/bearer token presented to the app-server.
# OMNIROUTE_CODEX_APPSERVER_WS_TOKEN=deadbeef...
# Path to a file holding the capability token (produced by
# `codex app-server --ws-token-file <path>`). Used when the inline token above
# is not set.
# OMNIROUTE_CODEX_APPSERVER_WS_TOKEN_FILE=/run/codex-ws-token
# Working directory the app-server turn runs in (defaults to /tmp).
# OMNIROUTE_CODEX_APPSERVER_CWD=/tmp
# Approval policy passed to the app-server turn (e.g. never, on-request).
# OMNIROUTE_CODEX_APPSERVER_APPROVAL=never
# Sandbox policy passed to the app-server turn (e.g. read-only,
# workspace-write, danger-full-access). When unset, the executor defaults to
# "workspace-write" (hardened; used to be "danger-full-access").
# OMNIROUTE_CODEX_APPSERVER_SANDBOX=read-only
# Auto-approve the app-server's own approval prompts (command/file/permission
# execution on the host). Defaults to OFF — prompts are auto-denied. Set to
# true/1/yes only when you trust the deployment to run codex-decided host
# commands. Per-connection override: providerSpecificData.codexAppServerAutoApprove.
# OMNIROUTE_CODEX_APPSERVER_AUTO_APPROVE=false
# ═══════════════════════════════════════════════════════════════════════════════
# 13. CLI FINGERPRINT COMPATIBILITY (Anti-Detection)
# ═══════════════════════════════════════════════════════════════════════════════
# When enabled, OmniRoute reorders HTTP headers and JSON body fields to match
# the exact signature of official CLI tools, reducing account flagging risk.
# Your proxy IP is preserved — you get both stealth AND IP masking.
# Used by: open-sse/config/cliFingerprints.ts, open-sse/executors/base.ts
# Enable per-provider:
# CLI_COMPAT_CODEX=1
# CLI_COMPAT_CLAUDE=1
# CLI_COMPAT_GITHUB=1
# CLI_COMPAT_ANTIGRAVITY=1
# CLI_COMPAT_CURSOR=1
# CLI_COMPAT_KIMI_CODING=1
# CLI_COMPAT_KILOCODE=1
# CLI_COMPAT_CLINE=1
# Or enable for all providers at once:
# CLI_COMPAT_ALL=1
# Allow the Antigravity request translator to skip its strict CLI request-signature
# validation when the upstream refuses real signatures (debug/antiquated-CLI mode).
# Default: real signatures enforced (unset) — signature bypass disabled.
# Used by: open-sse/translator/request/openai-to-gemini.ts
# ANTIGRAVITY_ALLOW_SIGNATURE_BYPASS=0
# ── Kimi Coding CLI identity overrides ──
# Used by: src/lib/oauth/providers/kimi-coding.ts — sent in OAuth + API headers.
# Leave unset to use the captured defaults baked into the OmniRoute build.
#KIMI_CLI_VERSION=1.36.0
#KIMI_CODING_DEVICE_ID=
# ═══════════════════════════════════════════════════════════════════════════════
# 14. API KEY PROVIDERS
# ═══════════════════════════════════════════════════════════════════════════════
# API keys for direct-authentication providers.
# Preferred setup: Dashboard → Providers → Add API Key.
# Setting here is an alternative for Docker/headless deployments.
# Static API keys for direct-authentication providers wired through the runtime.
# OmniRoute loads provider credentials from the encrypted database or
# data/provider-credentials.json. The variables below are documented escape
# hatches that are referenced in code today.
# DEEPSEEK_API_KEY=
# NVIDIA_API_KEY=
# Jina Foundation API + Reader fallback when no dashboard jina-ai / jina-reader
# connection exists. Dashboard keys always win (fill-first).
# JINA_AI_API_KEY=
# JINA_API_KEY=
# Gemini / Google AI Studio embeddings fallback when no dashboard gemini
# connection exists. Dashboard keys always win (fill-first).
# GEMINI_API_KEY=
# GOOGLE_API_KEY=
# Windsurf / Devin CLI direct API key.
# Used by: open-sse/executors/devin-cli.ts — bypasses OAuth when set.
# WINDSURF_API_KEY=
# Embedding Providers (optional — used by /v1/embeddings)
# OpenAI/Mistral/Together/Fireworks/NVIDIA configured via Dashboard → Providers
# also work for embeddings.
# ═══════════════════════════════════════════════════════════════════════════════
# 15. TIMEOUT SETTINGS
# ═══════════════════════════════════════════════════════════════════════════════
# All timeout values are in milliseconds.
# Used by: src/shared/utils/runtimeTimeouts.ts — centralized timeout resolution.
#
# Hierarchy: REQUEST_TIMEOUT_MS acts as a global override.
# If set, it becomes the default for FETCH_TIMEOUT_MS, STREAM_IDLE_TIMEOUT_MS,
# and STREAM_READINESS_TIMEOUT_MS. STREAM_ACTIVE_TIMEOUT_MS is independent.
# The fine-grained variables below override their respective defaults only when set.
# ── Global shortcut ──
# REQUEST_TIMEOUT_MS=600000 # Overrides both fetch and stream idle defaults
# ── Upstream fetch (provider calls) ──
# FETCH_TIMEOUT_MS=600000 # Total request timeout (default: 600000 = 10 min)
# # Also drives anthropic-compatible-cc-* X-Stainless-Timeout.
# FETCH_HEADERS_TIMEOUT_MS=600000 # Time to receive response headers
# Maximum response-header wait (ms) for streaming requests. Default: 110000; 0 disables.
# OMNIROUTE_FETCH_START_TIMEOUT_CAP_MS=110000
# FETCH_BODY_TIMEOUT_MS=600000 # Time to receive full response body
# FETCH_CONNECT_TIMEOUT_MS=30000 # TCP connection establishment (default: 30s)
# FETCH_KEEPALIVE_TIMEOUT_MS=4000 # Keep-alive socket idle timeout (default: 4s)
# OMNIROUTE_CODEX_IMAGE_RESPONSE_START_TIMEOUT_MS=600000 # First response headers for
# # dedicated Codex images/generations and images/edits
# # POSTs (ms; 10 min by default). These long-running
# # paid submissions are never replayed after a timeout
# # or transport failure, including when proxied.
# # Edge relays stay single-attempt too, but keep their
# # own OMNIROUTE_RELAY_FETCH_TIMEOUT_MS deadline.
# OMNIROUTE_DIRECT_HEADERS_TIMEOUT_MS=30000 # Bounded response-start window per direct
# # (no-proxy) attempt (#10214). A silently-dropped
# # pooled keep-alive socket surfaces no transport
# # error, so without this bound a direct request can
# # stall until undici's headersTimeout (600s) or the
# # caller's deadline; on expiry the request retries
# # once on a fresh no-keep-alive socket. 0 disables
# # the bound (default: 30000 = 30s).
# OMNIROUTE_LOCAL_DIRECT_HEADERS_TIMEOUT_MS=300000 # Floor for local/self-hosted targets
# # (host.docker.internal, 192.168.x.x, localhost).
# # Used when the direct upstream URL is private/LAN
# # so native Ollama cold-start TTFB can exceed 30s.
# # Default: 300000 = 5 min. See docs/guides/LOCAL_OLLAMA_DOCKER.md
# OMNIROUTE_DIRECT_IMAGE_HEADERS_TIMEOUT_MS=300000 # Floor for direct image requests: image
# # generation/edit endpoints (/images/generations,
# # /images/edits, ...) and bodies with a hosted
# # "image_generation" tool. Raise-only; 0 removes it.
# # Codex image POSTs use their own deadline
# # (OMNIROUTE_CODEX_IMAGE_RESPONSE_START_TIMEOUT_MS).
# # Default: 300000 = 5 min.
# OMNIROUTE_DIRECT_HEADERS_VOLUME_ADAPTIVE=1 # Raise the direct response-start window by
# # payload tier (>512KB ×2, >2MB ×3, capped at 180s,
# # never lowering a higher floor). Set 0/false/off
# # to pin the flat window. Default: 1.
# OMNIROUTE_DIRECT_RESPONSE_RETRY_TIMEOUT_MS=600000 # Ceiling (ms) for the fresh-socket
# # RETRY attempt above (#13703). Only applies when
# # the caller already attached its own deadline
# # signal (the resolved connection/model/provider/
# # FETCH_TIMEOUT_MS cascade) — that signal is the
# # real bound and fires first in the intended path,
# # so this is a generous backstop rather than a flat
# # cap: without it the retry reused the same short
# # OMNIROUTE_DIRECT_HEADERS_TIMEOUT_MS window as the
# # pooled attempt and 504'd healthy slow-TTFB
# # reasoning models. Never allowed below the flat
# # floor above (default: 600000 = 10 min).
# Default timeout (ms) for src/shared/utils/fetchTimeout.ts. Acts as the
# fallback when FETCH_TIMEOUT_MS is unset. Default: 120000 (2 min).
# OMNIROUTE_DEFAULT_FETCH_TIMEOUT_MS=120000
# ── Provider probe (credential validation / model discovery) ──
# Timeout in ms for provider validationRead and modelsProbe presets.
# Default: 8000 (was 5000). Raise it if slow endpoints (Cerebras, Cloudflare AI, Groq)
# cause flapping between active/error in the dashboard.
# Used by: src/shared/network/safeOutboundFetch.ts — centralized timeout resolution.
# OMNIROUTE_PROVIDER_PROBE_TIMEOUT_MS=8000
# ── Proxy/relay fetch (connection pooling, #9158) ──
# Used by: open-sse/utils/proxyFetch.ts.
# A hung relay must fail BEFORE the client/agent timeout (typically 30s) so the
# caller sees a relay-specific failure instead of a generic upstream timeout.
# Capped at 29000ms so this timeout always fires first. Default: 25000 (25s).
# OMNIROUTE_RELAY_FETCH_TIMEOUT_MS=25000
# Shared retry backoff (ms) for the direct/relay/proxy retry-once paths.
# 0 = retry immediately. Default: 10.
# OMNIROUTE_RETRY_BACKOFF_MS=10
# ── Firecrawl web-fetch executor ──
# Point at a self-hosted Firecrawl instance (defaults to the public cloud API).
# When set to a non-cloud base URL, the API key becomes optional.
# FIRECRAWL_BASE_URL=https://api.firecrawl.dev
# FIRECRAWL_TIMEOUT_MS=30000 # Per-request timeout (default: 30000 = 30s)
# ── Tavily quota tracker ──
# Point the Tavily /usage quota fetcher at a self-hosted or proxied Tavily-compatible
# base URL (ignored when it points at api.tavily.com; unset = use the connection's base URL).
# TAVILY_BASE_URL=
# ── Claude TLS transport (Chromium-fingerprinted client) ──
# Used by: open-sse/services/claudeTlsClient.ts — native wreq-js request timeout
# plus the absolute JS hard-deadline grace when the native request is wedged.
# OMNIROUTE_CLAUDE_TLS_TIMEOUT_MS=60000
# OMNIROUTE_CLAUDE_TLS_GRACE_MS=10000
# ── Perplexity TLS transport (Firefox-fingerprinted client) ──
# Used by: open-sse/services/perplexityTlsClient.ts — native wreq-js request
# timeout plus the absolute JS hard-deadline grace.
# OMNIROUTE_PPLX_TLS_TIMEOUT_MS=30000
# OMNIROUTE_PPLX_TLS_GRACE_MS=10000
# ── Perplexity web: built-in-search hint ──
# Used by: open-sse/executors/perplexity-web/protocol.ts — appends "You have
# built-in web search. Answer questions directly using search results." to the
# caller's system message. Off by default: Perplexity's answer engine searches
# anyway, and for coding clients the sentence leaks into replies as
# meta-commentary. Set to 1/true/yes/on to restore the old behavior.
# OMNIROUTE_PPLX_SEARCH_HINT=0
# ── Grok web TLS transport (Chrome-fingerprinted client) ──
# Used by: open-sse/services/grokTlsClient.ts — native wreq-js request timeout
# plus the absolute JS hard-deadline grace.
# OMNIROUTE_GROK_TLS_TIMEOUT_MS=60000
# OMNIROUTE_GROK_TLS_GRACE_MS=10000
# ── Notion web TLS transport (Chrome-fingerprinted client) ──
# Used by: open-sse/services/notionTlsClient.ts — native wreq-js request timeout
# plus the absolute JS hard-deadline grace. The notion-web executor raises the
# native timeout per request to 180000 for long generations.
# OMNIROUTE_NOTION_TLS_TIMEOUT_MS=30000
# OMNIROUTE_NOTION_TLS_GRACE_MS=10000
# ── Grok web quota fetcher (auth.json override) ──
# Used by: open-sse/services/grokQuotaFetcher.ts — path of the Grok CLI
# auth.json used to fetch the grok-web weekly quota. Defaults to
# ~/.grok/auth.json; override for tests or a non-standard CLI install.
# GROK_AUTH_PATH=
# ── Browser-backed web-cookie chat (Playwright shared pool) ──
# Used by: open-sse/services/browserPool.ts + browserBackedChat.ts. The shared
# browser pool warms a headless context for web-cookie providers (e.g. claude-web)
# that need a real browser to satisfy anti-bot challenges. Set OMNIROUTE_BROWSER_POOL=off
# to fully disable the pool; set WEB_COOKIE_USE_BROWSER=1 to opt a web-cookie chat
# request into the browser-backed path.
# OMNIROUTE_BROWSER_POOL=on
# WEB_COOKIE_USE_BROWSER=0
# Gemini Web (gweb) opt-in for gemini-4-argon (#16573). Used by:
# open-sse/config/providers/registry/gemini/web/index.ts and
# open-sse/executors/gemini-web/modeSelection.ts. Off by default: its mode-menu
# selectors are not yet checked against a live Gemini Web account. Set 1 to list
# the model and allow its mode selection; read at startup (restart to apply).
# OMNIROUTE_GEMINI_WEB_ARGON_ENABLED=0
# Obscura (https://github.com/h4ckf0r0day/obscura) is the primary headless
# engine: a lightweight CDP server the pool and cloudflare-playground connect
# to before falling back to Chromium. Unset OBSCURA_BIN to auto-detect from
# PATH; set OBSCURA_CDP_ENDPOINT to reuse an already-running Obscura instead
# of spawning one; set OBSCURA_PORT to pin the spawned serve port.
# Used by: open-sse/services/obscura.ts
# OBSCURA_BIN=
# OBSCURA_CDP_ENDPOINT=
# OBSCURA_PORT=
# ── Kimi Web (international kimi.ai Connect-RPC) ──
# Used by: open-sse/executors/kimi-web.ts. Override the base/chat URLs only if
# you need a mirror or proxy endpoint; defaults target https://www.kimi.ai with
# the Connect-RPC chat path /apiv2/kimi.gateway.chat.v1.ChatService/Chat.
# KIMI_WEB_BASE_URL=https://www.kimi.ai
# KIMI_WEB_CHAT_URL=https://www.kimi.ai/apiv2/kimi.gateway.chat.v1.ChatService/Chat
# When OIDC is enabled, disable password login so users can only authenticate
# via OIDC Single Sign-On. The bare alias OIDC_DISABLE_PASSWORD_LOGIN is also
# accepted; the Dashboard Feature Flag takes precedence. Used by:
# src/app/api/auth/login/route.ts, src/app/api/settings/require-login/route.ts.
# OMNIROUTE_OIDC_DISABLE_PASSWORD_LOGIN=false
# OIDC_DISABLE_PASSWORD_LOGIN=false
# Lost-device recovery for the opt-in dashboard two-factor login (TOTP).
# When true, the second factor is skipped ONLY for a sign-in from the host itself
# (loopback peer + loopback Host); every other origin still needs the code.
# Sign in locally, disable two-factor under Settings > Security (the code may be
# left blank while this is set; the password is still required), then unset it.
# Used by: src/server/auth/dashboardMfa.ts.
# OMNIROUTE_DISABLE_MFA=false
# ── Adobe Firefly browser sign-in (system Chrome/Edge CDP) ──
# Used by: open-sse/services/adobeFireflyBrowserLogin.ts. The Firefly login
# flow drives a real, system-installed Chrome or Microsoft Edge via CDP so the
# user can sign in interactively; the executable is auto-detected from common
# install paths per OS. Set this to override that detection (e.g. a portable
# install or a non-standard path) when auto-detection fails.
# OMNIROUTE_LOGIN_BROWSER_PATH=
# ── Circuit breaker thresholds and reset windows ──
# Used by: open-sse/config/constants.ts → src/lib/resilience/settings.ts.
# Defaults match historical PROVIDER_PROFILES values (post-scaling for
# 500+ connections). Lower the threshold to react faster, raise it to
# tolerate more transient failures before short-circuiting.
# OMNIROUTE_CIRCUIT_BREAKER_OAUTH_THRESHOLD=8
# OMNIROUTE_CIRCUIT_BREAKER_OAUTH_RESET_MS=60000
# OMNIROUTE_CIRCUIT_BREAKER_API_KEY_THRESHOLD=12
# OMNIROUTE_CIRCUIT_BREAKER_API_KEY_RESET_MS=30000
# OMNIROUTE_CIRCUIT_BREAKER_LOCAL_THRESHOLD=2
# OMNIROUTE_CIRCUIT_BREAKER_LOCAL_RESET_MS=15000
# Per-key cooldown (ms) for multi-key API-key rotation when a 429 carries no
# Retry-After. Used by: open-sse/services/apiKeyRotator.ts (#14573). Default 60000.
# OMNIROUTE_API_KEY_COOLDOWN_MS=60000
# ── Anti-avalanche failover guard (opt-in, off by default) ──
# Used by: open-sse/services/accountFallback/antiAvalanche.ts → src/sse/handlers/chat.ts.
# Only an explicit "true" enables it. When on, a 429 that names a tokens-per-minute limit
# (or a context-overflow 400) stops the cascading failover across the remaining keys of the
# provider. A quota-exhausted 429 keeps failing over however large the prompt is, 413 keeps
# the #13350 retry-on-another-account behaviour, and the burst cooldown never shortens a
# longer upstream reset.
# OMNIROUTE_AVALANCHE_PROTECTION_ENABLED=false
# OMNIROUTE_AVALANCHE_BURST_COOLDOWN_MS=60000
# ── Provider-level circuit breaker thresholds and cooldowns ──
# Used by: open-sse/config/constants.ts (PROVIDER_PROFILES → accountFallback).
# These control the provider-level fuse (entire provider cooldown after repeated
# failures) — distinct from the per-key breaker above. Defaults match the
# historical PROVIDER_PROFILES values. Raise to tolerate transient upstream
# sheds without blacklisting the provider; lower to fail over faster.
# OMNIROUTE_PROVIDER_BREAKER_OAUTH_FAILURE_THRESHOLD=10
# OMNIROUTE_PROVIDER_BREAKER_OAUTH_FAILURE_WINDOW_MS=900000
# OMNIROUTE_PROVIDER_BREAKER_OAUTH_COOLDOWN_MS=300000
# OMNIROUTE_PROVIDER_BREAKER_OAUTH_DEGRADATION_THRESHOLD=5
# OMNIROUTE_PROVIDER_BREAKER_OAUTH_MAX_BACKOFF_MULTIPLIER=8
# OMNIROUTE_PROVIDER_BREAKER_OAUTH_BACKOFF_ESCALATION_COUNT=2
# OMNIROUTE_PROVIDER_BREAKER_API_KEY_FAILURE_THRESHOLD=15
# OMNIROUTE_PROVIDER_BREAKER_API_KEY_FAILURE_WINDOW_MS=1800000
# OMNIROUTE_PROVIDER_BREAKER_API_KEY_COOLDOWN_MS=600000
# OMNIROUTE_PROVIDER_BREAKER_API_KEY_DEGRADATION_THRESHOLD=7
# OMNIROUTE_PROVIDER_BREAKER_API_KEY_MAX_BACKOFF_MULTIPLIER=4
# OMNIROUTE_PROVIDER_BREAKER_API_KEY_BACKOFF_ESCALATION_COUNT=3
# OMNIROUTE_PROVIDER_BREAKER_LOCAL_FAILURE_THRESHOLD=2
# OMNIROUTE_PROVIDER_BREAKER_LOCAL_FAILURE_WINDOW_MS=300000
# OMNIROUTE_PROVIDER_BREAKER_LOCAL_COOLDOWN_MS=60000
# ── Context-cache pin health gate ──
# Used by: open-sse/services/combo.ts. When a context-cache pin points at a
# provider that is durably unhealthy, the pin is dropped to allow failover.
# PIN_DROP_BACKOFF_LEVEL gates how deep a connection's backoff must be before the
# pin is considered durably unhealthy; PIN_DROP_GRACE_MS is the anti-flap window
# that tolerates brief transient cooldowns before dropping the pin.
# PIN_DROP_BACKOFF_LEVEL=2
# PIN_DROP_GRACE_MS=20000
# Whether OmniRoute may emit SSE `:` comment lines (e.g. the `: keepalive` heartbeat).
# Some strict OpenAI-compatible clients parse every SSE line as JSON and crash on `:`
# comments. Set to `off` to suppress comment-shaped heartbeats (they become a no-op);
# `data:` heartbeats are unaffected. Default: enabled.
# Used by: open-sse/utils/sseHeartbeat.ts.
# OMNIROUTE_SSE_COMMENTS=off
# ── Opt-in SSE output coalescing (all OFF by default; the default stream is unchanged) ──
# Merge consecutive Claude `content_block_delta` events (same block index + same delta type)
# sent to Claude clients into one event per window, losslessly. Helps clients that render one
# UI update per SSE event (e.g. the Claude Code VS Code extension) keep up with fast upstreams.
# SSE_COALESCE_MS sets every delta type; the per-type vars override it. 0/unset = off.
# Used by: open-sse/utils/sseDeltaCoalesce.ts.
# SSE_COALESCE_MS=0
# SSE_COALESCE_THINKING_MS=0
# SSE_COALESCE_TEXT_MS=0
# SSE_COALESCE_INPUT_JSON_MS=0
# Batch SSE frames forwarded within this window into ONE write to the client (fewer socket
# writes under high concurrency). The first frame and terminal frames are never delayed.
# 0/unset = off (one write per frame). Used by: open-sse/utils/sseOutputSink.ts.
# SSE_FRAME_COALESCE_MS=0
# Byte-stall watchdog implementation: `timer` (default, one timer re-armed per upstream chunk)
# or `interval` (one low-frequency check per stream; fires within the stall budget + 1-5s).
# Used by: open-sse/utils/streamStallWatchdog.ts.
# SSE_STALL_WATCHDOG=timer
# ── Stream idle detection ──
# STREAM_IDLE_TIMEOUT_MS=600000 # Max silence between SSE chunks (default: 600000)
# # Extended-thinking models rarely pause >90s.
# STREAM_ACTIVE_TIMEOUT_MS=1260000 # Max total active SSE lifetime (default: 21 min = the largest registered model timeoutMs + 1 min; 0 disables)
# # Unset: a target that declares a longer timeoutMs (connection, model or provider,
# # e.g. GLM) gets that budget + 1 min instead. Set: a hard cap for every target.
# # Independent of REQUEST_TIMEOUT_MS and byte activity.
# STREAM_READINESS_TIMEOUT_MS=80000 # Time to receive the first non-ping SSE event
# STREAM_READINESS_MAX_TIMEOUT_MS=180000 # Cap for adaptive first-event extensions
# # (large/tool-heavy/high-reasoning requests).
# OMNIROUTE_AGENT_GOAL_POLICY_ENABLED=true # Kill-switch for the /goal heuristic below.
# # Set to false to fully disable detection —
# # readiness timeouts and stream recovery are
# # never elevated by request body/headers when off.
# OMNIROUTE_AGENT_GOAL_READINESS_MAX_TIMEOUT_MS=600000 # Auto cap for detected /goal agent runs
# OMNIROUTE_AGENT_GOAL_STREAM_RECOVERY=true # Auto early stream recovery for /goal runs.
# # NOTE: this can only ADD recovery on top of the
# # operator default — it never overrides an explicit
# # STREAM_RECOVERY_ENABLED / DB settings opt-out.
# ── TLS client (wreq-js fingerprint proxy) ──
# TLS_CLIENT_TIMEOUT_MS=600000 # Inherits from FETCH_TIMEOUT_MS by default
# TLS_FIRST_BYTE_WATCHDOG_MS=10000 # #12656: bounds time-to-first-byte on the wreq body (0 disables)
# OPENCODE_RESPONSES_STALL_ROTATION=false # #13484 feature flag (Settings → Feature Flags wins): rotate once when a streamed Responses reply stalls before its first byte
# OPENCODE_PARK_AND_RESUME=false # #13924 feature flag (Settings → Feature Flags wins): park the request with a heartbeat after repeated transient 429s, then replay one capped leg of up to 3 accounts
# OPENCODE_PARK_REPLAY_SERVE_SETASIDE=false # #14851 opt-in: when every cooldown-ready account in the park replay leg is set aside, serve them anyway instead of an empty leg
# STREAM_READINESS_STALL_RETRY=false # feature flag (Settings → Feature Flags wins): when a streaming first body stalls before usable output, issue one bounded second attempt through the same routing path
#OPENCODE_POOL_STRAIN_MARKER_PATH=/tmp/opencode-pool-strain.json # #13924: pool-strain marker path (JSON {since, reason, ttl_s}); fresh marker parks without recounting
# OPENCODE_POOL_RESELECT=false # feature flag (Settings → Feature Flags wins): after a 429 from an egress-bucketed provider on a proxy-less account under an ambient pool context, ask the pool for another member for the next attempt instead of retrying the same address
# RESPONSES_FIRST_BYTE_TIMEOUT_MS=15000 # #13484: OpenCode Responses first-byte window, only used when the OPENCODE_RESPONSES_STALL_ROTATION flag is on (0 disables)
# OPENCODE_RESPONSES_HEADERS_WAIT_MS=30000 # opt-in bound on waiting for upstream response headers on streamed Responses calls before moving to the next account (0 = off, suggested 30000)
# OPENCODE_RESPONSES_HEADERS_WAIT_MAX_ROTATIONS=2 # rotation budget for the headers-wait bound above
# FLUSH_EMPTY_RETRY_ENABLED=false # #14213 feature flag (Settings → Feature Flags wins): retry empty translated streaming turns through the normal credential path (up to STREAM_RECOVERY.EMPTY_TURN_RETRY_MAX retries)
# EMPTY_STREAM_SIBLING_RECOVERY_ENABLED=false # #16438 feature flag (Settings → Feature Flags wins): Claude/Codex empty-stream content probe + bounded retry on a sibling connection (no cooldown/lockout)
# STREAM_LATE_OUTPUT_PROBE_ENABLED=false # #16927 feature flag (Settings → Feature Flags wins): keep sampling 1 forwarded chunk in 16 after chunk 64 so late output counts as emitted (lone post-output 5xx stays request-scoped)
# ── API Bridge (/v1 proxy server) ──
# API_BRIDGE_PROXY_TIMEOUT_MS=600000 # Proxy hop timeout (default: 10min)
# API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS=600000 # Overall server request timeout (default: 10min)
# API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS=60000 # Time to send response headers
# API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS=5000 # Keep-alive idle timeout
# API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS=0 # Raw socket timeout (0 = disabled)
# ── Graceful shutdown ──
# Time to wait for in-flight requests before force-exiting on SIGTERM/SIGINT.
# Used by: src/lib/gracefulShutdown.ts
# Default: 30000 (30 seconds)
# SHUTDOWN_TIMEOUT_MS=30000
# ═══════════════════════════════════════════════════════════════════════════════
# 16. LOGGING
# ═══════════════════════════════════════════════════════════════════════════════
# Used by: src/lib/logEnv.ts, src/lib/logRotation.ts, src/shared/utils/logger.ts
# Application log level — controls console and file log verbosity.
# Values: debug | info | warn | error | Default: info
# APP_LOG_LEVEL=info
# Log output format.
# Values: text | json | Default: text
# APP_LOG_FORMAT=text
# Write logs to file in addition to stdout.
# Default: true | Set false to disable file logging.
APP_LOG_TO_FILE=true
# Path to the application log file.
# Default: <DATA_DIR>/logs/application/app.log (DATA_DIR defaults to ~/.omniroute)
# APP_LOG_FILE_PATH=logs/application/app.log
# Maximum single log file size before rotation.
# Accepts: plain bytes or suffixed (50M, 1G, 512K). Default: 50M
# APP_LOG_MAX_FILE_SIZE=50M
# Days to keep rotated application log files before auto-deletion.
# Default: 7
# APP_LOG_RETENTION_DAYS=7
# Maximum number of rotated log file backups to keep.
# Default: 20
# APP_LOG_MAX_FILES=20
# How often OmniRoute checks whether the active log file has exceeded
# APP_LOG_MAX_FILE_SIZE and triggers a rotation. Set lower for very verbose
# services to prevent log files from growing large between checks.
# Accepts milliseconds. Default: 60000 (1 minute)
# APP_LOG_ROTATION_CHECK_INTERVAL_MS=60000
# Days to keep request/call log entries in the database before auto-cleanup.
# Default: 7
# CALL_LOG_RETENTION_DAYS=7
# Maximum call log entries stored in-memory buffer.
# Default: 10000
# CALL_LOG_MAX_ENTRIES=10000
# Maximum rows in the call_logs SQLite table before oldest entries are pruned.
# Default: 100000
# CALL_LOGS_TABLE_MAX_ROWS=100000
# Size cap, in MiB, for the generated media kept under DATA_DIR/media (video results). When a
# new file pushes the folder past the cap, the oldest files are removed first. The file just
# written always stays. Whole number above 0; any other value is ignored.
# When set, it wins over the Storage setting "Media store size cap" in the dashboard.
# Used by: src/lib/media/mediaStore.ts. Default: 2048 (2 GiB)
# MEDIA_STORE_MAX_MB=2048
# Force detailed request logging on or off, overriding the dashboard setting.
# Values: true | false | Default: unset (follow dashboard setting)
# ENABLE_REQUEST_LOGS=false
# Maximum age for orphaned active request log entries before the in-memory
# pending-request reaper removes them. Accepts milliseconds.
# Default: 3600000 (1 hour)
# MAX_PENDING_REQUEST_AGE_MS=3600000
# Maximum number of pending request details retained in memory. The count cap is applied
# by the 5-minute sweep (the 256 MiB byte ceiling applies at insert); the pending-id
# correlation map is capped at insert. Must be a positive integer.
# Default: 5000
# MAX_PENDING_DETAILS=5000
# Whether call log pipeline capture stores stream chunks when enabled in settings.
# Only applies when call_log_pipeline_enabled=true.
# Default: false (opt-in — saves disk: stream chunks are the biggest call-log artifact)
# CALL_LOG_PIPELINE_CAPTURE_STREAM_CHUNKS=true
# Maximum call log artifact size for pipeline captures, in KB.
# Only applies when call_log_pipeline_enabled=true.
# Default: 512
# CALL_LOG_PIPELINE_MAX_SIZE_KB=512
# Minimum free disk space, in MB, on the volume that holds the call log artifacts
# (DATA_DIR/call_logs, next to storage.sqlite). Below it, artifact writes are skipped and the
# row shows detail_state "missing", so artifacts cannot take the last bytes that the usage
# ledger and call log row writes need. 0 turns the check off. A failed check never drops a log.
# Used by: src/lib/usage/callLogArtifacts.ts (hasRoomForCallLogArtifact)
# Default: 512
# CALL_LOG_MIN_FREE_DISK_MB=512
# Call log payload truncation limits — controls how much of request/response
# bodies is retained in the database.
# Used by: open-sse/handlers/chatCore.ts — cloneBoundedChatLogPayload()
# CHAT_LOG_TEXT_LIMIT=65536 # Max string length before truncation (default: 64 KB)
# CHAT_LOG_ARRAY_TAIL_ITEMS=1000 # Number of array items retained from tail (default: 1000)
# CHAT_LOG_MAX_DEPTH=20 # Max nesting depth before truncation (default: 20)
# CHAT_LOG_MAX_OBJECT_KEYS=80 # Max object keys retained (default: 80, 0 = no limit)
# CHAT_LOG_MAX_BODY_KB=1024 # Whole request/response body size before it's replaced by a bare
# {_truncated, messageCount, ...} summary instead of the full clone
# (default: 1024 KB / 1MB). Raise this if the dashboard's "Full
# Conversation" transcript panel shows a placeholder instead of the
# actual messages for long agentic conversations.
# Maximum rows in the proxy_logs SQLite table.
# Default: 100000
# PROXY_LOGS_TABLE_MAX_ROWS=100000
# Include client/egress IPs and account prefixes in [ProxyEgress] console logs.
# Default: false (the dashboard/database proxy-log records retain full details).
# PROXY_LOG_INCLUDE_IPS=false
# Record the time to the first useful body byte of each upstream send on its
# proxy-log row (first_chunk_ms). Opt-in: when on, every upstream body is piped
# through a lazy passthrough stream and the row is patched once the byte lands.
# Default: false (only the free headers timing, headers_ms, is recorded).
# PROXY_LOG_FIRST_CHUNK_TIMING=false
# ═══════════════════════════════════════════════════════════════════════════════
# 17. MEMORY OPTIMIZATION (Low-RAM / Docker)
# ═══════════════════════════════════════════════════════════════════════════════
# Node.js V8 heap limit in MB, passed to the server via --max-old-space-size.
# Used by the standalone launcher (Docker CMD) and `omniroute serve`.
# Clamped to [64, 16384]. Default: 512 (safe for a 1 GB / 1 core VPS). Size it to
# roughly half the box's RAM, leaving the rest for native memory (better-sqlite3,
# buffers — ~300 MB) and the OS:
# 1 GB RAM → 512 (default)
# 2 GB RAM → 1024
# 4 GB RAM → 2048
# In a memory-capped container, set this EXPLICITLY: Node reads the HOST's RAM,
# not the cgroup limit, so leaving it to a RAM heuristic can oversize the heap and
# get the container OOM-killed. (#2939)
# OMNIROUTE_MEMORY_MB=512
# Log compact V8 heap metrics only when heapUsed exceeds a configured threshold.
# Used by: src/lib/healthzLag.ts (event-loop stall sampler). Disabled by default;
# logs sizes and inflight count only, never bodies or heap snapshots.
# OMNIROUTE_EVENT_LOOP_STALL_THRESHOLD_MS=0 stops that sampler, and this diagnostic with it.
# OMNIROUTE_HEAP_DIAGNOSTICS_ENABLED=0
# Heap-use threshold in MiB for the opt-in diagnostic (default: 900).
# A high-heap log is rate-limited to once per 60 seconds.
# OMNIROUTE_HEAP_DIAGNOSTICS_THRESHOLD_MB=900
# Absolute process-RSS fuse (MB) for native/external memory invisible to V8 heapUsed — new requests
# get 503 resource_pressure above it. Only active when OMNIROUTE_MEMORY_MB is set (default
# max(3072, 2 x OMNIROUTE_MEMORY_MB)); set this to override. RSS rarely falls after a spike, so
# pair it with OMNIROUTE_PRESSURE_SELF_RESTART. Used by: open-sse/utils/resourcePressure.ts.
# OMNIROUTE_RSS_PRESSURE_MB=3072
# Heap-pressure shed threshold (MB) — chatCore returns 503 when V8 heapUsed exceeds
# it, to avoid hard OOM under concurrent large-context load.
# LEAVE UNSET: it now AUTO-CALIBRATES to 85% of the actual V8 heap ceiling, so it
# tracks OMNIROUTE_MEMORY_MB above and never sits below the ~260 MB runtime baseline
# (a fixed 200 here used to reject every request). Used by: open-sse/utils/heapPressure.ts.
# Override only to hand-tune for a known workload.
# HEAP_PRESSURE_THRESHOLD_MB=
# Exit the process after critical resource pressure persists, so a supervisor
# (systemd Restart=always, Docker restart policy) brings back a clean process.
# Accepts 1/true/yes/on. Default: false. Used by: open-sse/utils/resourcePressure.ts.
# OMNIROUTE_PRESSURE_SELF_RESTART=false
# How long (ms) critical pressure must persist before that exit fires. Default: 120000 (2m).
# OMNIROUTE_PRESSURE_SELF_RESTART_AFTER_MS=120000
# Ignore host-wide memory PSI (/proc/pressure/memory: psi_some / psi_full) for a
# noisy-neighbor host where this process is fine (#13124). Cgroup and V8 heap
# guards stay on, and PSI also stops counting as kernel throttle proof for the
# cgroup_high guard: a raw cgroup total above memory.high then only turns
# critical on a memory.events high/max increase. Accepts 1/true/yes/on.
# Default: false. Used by: open-sse/utils/resourcePressurePolicy.ts.
# OMNIROUTE_PRESSURE_PSI_DISABLED=false
# ── CLI helpers (bin/cli/) ──
# Override UI language for CLI output. Accepts BCP-47 locale (e.g. en, pt-BR).
# Falls back to LC_ALL / LC_MESSAGES / LANG / en if unset.
# OMNIROUTE_LANG=en
# Show server logs inline when running in supervised mode (omniroute serve).
# Set to "1" to forward server stdout/stderr to the terminal.
# Equivalent to the --log flag on `omniroute serve`.
# OMNIROUTE_SHOW_LOG=1
# Bearer token injected as x-omniroute-cli-token header for machine-auth (task 8.12).
# Auto-generated on first run if machine-id is available; set manually to override.
# OMNIROUTE_CLI_TOKEN=
# Sync token used by `omniroute sync bundle` (GET /api/sync/bundle accepts only a sync token,
# not an API key). Create one with `omniroute sync tokens create --name <name>`.
# Equivalent to the --token flag. Used by: bin/cli/commands/sync.mjs.
# OMNIROUTE_SYNC_TOKEN=
# Per-attempt HTTP timeout for CLI → server calls (milliseconds). Default: 30000.
# OMNIROUTE_HTTP_TIMEOUT_MS=30000
# How long `omniroute serve` waits for the health endpoint before printing the
# readiness-timeout warning (milliseconds). Also --ready-timeout. Default: 60000.
# OMNIROUTE_READY_TIMEOUT_MS=60000
# Set to 1 to print retry/backoff details to stderr during CLI commands.
# OMNIROUTE_VERBOSE=0
# Custom directory for CLI plugin discovery (omniroute-cmd-* packages).
# Default: ~/.omniroute/plugins/ Override in dev/CI to point at a local plugin tree.
# CLI-only: the server-side plugin scanner is pointed by OMNIROUTE_PLUGINS_DIR (section 2).
# OMNIROUTE_PLUGIN_PATH=
# Suppress the CLI's update notification when the process exits.
# Default: unset. Any non-empty value disables the notice.
# Used by: bin/omniroute.mjs
# OMNIROUTE_NO_UPDATE_NOTIFIER=1
# Override the liveness URL probed by `omniroute doctor`.
# Default: the local dashboard's /api/health/degradation endpoint. A programmatic
# livenessUrl option takes precedence; otherwise this value is used verbatim.
# Used by: bin/cli/commands/doctor.mjs
# OMNIROUTE_DOCTOR_LIVENESS_URL=http://127.0.0.1:20128/api/health/degradation
# Override the provider catalog path used by CLI provider commands. Absolute paths
# are used as-is; relative paths resolve from the project root. A programmatic
# catalogPath option takes precedence. Default: src/shared/constants/providers/.
# Used by: bin/cli/provider-catalog.mjs
# OMNIROUTE_PROVIDER_CATALOG_PATH=src/shared/constants/providers
# Global fallback model for CLI provider connection tests. Resolution order is:
# configured connection model, provider-specific override, this value, then the
# provider's built-in test model. Default: provider-specific built-in model.
# Used by: bin/cli/provider-test.mjs
# OMNIROUTE_PROVIDER_TEST_MODEL=
# ── Prompt cache (system prompt deduplication) ──
# Used by: open-sse/services — caches identical system prompts across requests.
# PROMPT_CACHE_MAX_SIZE=50 # Max cached entries (default: 50)
# PROMPT_CACHE_MAX_BYTES=2097152 # Max total cache size in bytes (default: 2 MB)
# PROMPT_CACHE_TTL_MS=300000 # Cache entry TTL (default: 5 minutes)
# ── Semantic cache (deterministic response dedup, temperature=0) ──
# Used by: open-sse/services — caches identical temperature=0 responses.
# SEMANTIC_CACHE_MAX_SIZE=100 # Max cached entries (default: 100)
# SEMANTIC_CACHE_MAX_BYTES=4194304 # Max total cache size in bytes (default: 4 MB)
# SEMANTIC_CACHE_MAX_ENTRY_BYTES=262144 # Max size of one in-memory entry; larger answers stay in SQLite only (default: 256 KB)
# SEMANTIC_CACHE_TTL_MS=1800000 # Cache entry TTL (default: 30 minutes)
# SQLite pruning only; does not change TTL, memory LRU or vector cache behavior.
# All four: empty/non-numeric/non-finite/negative values use defaults; fractions round down.
# Interval 0 disables both startup and periodic pruning; other values below 60000 use 1800000.
# Values above 2147483647ms clamp to Node's maximum timer delay to avoid 1ms overflow polling.
# OMNIROUTE_SEMANTIC_CACHE_PRUNE_INTERVAL_MS=1800000
# Rows per DELETE, clamped to [100, 50000].
# OMNIROUTE_SEMANTIC_CACHE_PRUNE_BATCH_SIZE=2000
# Shared DELETE batch budget per run (expiry + optional cap), clamped to [1, 10000].
# OMNIROUTE_SEMANTIC_CACHE_PRUNE_MAX_BATCHES=50
# 0 = no row cap. Positive caps evict oldest created_at then rowid, including live rows.
# OMNIROUTE_SEMANTIC_CACHE_MAX_ROWS=0
# Expiry uses expires_at <= run start; first run after 1s, then every interval.
# A bounded run may leave backlog/rows above the cap for later runs.
# ── Local corpus index cache ──
# How many local-corpus roots keep a live in-memory index at once. The cache is
# LRU: reaching the limit evicts the least-recently-used root's index, which is
# then rebuilt on its next query. Clamped to a minimum of 1; a non-numeric value
# falls back to the default. Used by: src/lib/localCorpus/configured.ts
# OMNIROUTE_CORPUS_CACHE_SIZE=5
# ── In-memory log buffers ──
# Maximum recent stream events kept in memory for the Dashboard live view.
# STREAM_HISTORY_MAX=50
# ── Context length default ──
# Global context-length override (tokens) for every provider without a
# per-provider variable; when set it replaces catalog/registry values for them.
# Unset = built-in chain (last resort 128000).
# Per-provider form: CONTEXT_LENGTH_ + provider ID upper-cased, non [A-Z0-9]
# chars replaced by an underscore (agentrouter -> ..._AGENTROUTER). It wins over
# the global value. See docs/reference/ENVIRONMENT.md, "Per-provider context length".
# Used by: open-sse/services/contextManager.ts
# CONTEXT_LENGTH_DEFAULT=128000
# ── Usage token buffer ──
# Extra token headroom reserved when tracking usage quotas (prevents over-limit).
# Used by: open-sse/utils/usageTracking.ts
# USAGE_TOKEN_BUFFER=100
# ═══════════════════════════════════════════════════════════════════════════════
# 18. PRICING SYNC
# ═══════════════════════════════════════════════════════════════════════════════
# Automatic model pricing synchronization from external sources.
# Used by: src/lib/pricingSync.ts
# Enable periodic pricing data sync. Default: false (opt-in only).
# PRICING_SYNC_ENABLED=false
# Sync interval in seconds. Default: 86400 (24 hours).
# PRICING_SYNC_INTERVAL=86400
# Comma-separated data sources. Default: litellm
# PRICING_SYNC_SOURCES=litellm
# ═══════════════════════════════════════════════════════════════════════════════
# 18b. ARENA ELO SYNC
# ═══════════════════════════════════════════════════════════════════════════════
# Auto-update model intelligence from Arena AI leaderboard ELO scores (powers the
# Free Provider Rankings page). ON by default — fetches from api.wulong.dev on startup
# (non-blocking, never fatal). Set to false to opt out of the outbound sync.
# Also configurable from Dashboard > Settings > Feature Flags.
# Used by: src/shared/constants/featureFlagDefinitions.ts, src/lib/arenaEloSync.ts
# ARENA_ELO_SYNC_ENABLED=true
# How model ids are prefixed in GET /v1/models. "dual" (default) advertises BOTH the
# short alias prefix and the canonical provider prefix for each model (cc/claude-sonnet-4-6
# AND claude/claude-sonnet-4-6) so client configs that hardcoded either form keep working —
# which roughly doubles the catalog. "alias" emits one id per model; "canonical" emits only
# the full provider-id prefix (providers whose alias is already canonical keep their one id).
# A client can override per request with GET /v1/models?prefix=alias instead.
# Also configurable from Dashboard > Settings > Feature Flags.
# Used by: src/shared/constants/featureFlagDefinitions.ts, src/app/api/v1/models/catalog.ts
# MODELS_CATALOG_PREFIX_MODE=dual
# Sync interval in seconds. Default: 86400 (24 hours).
# ARENA_ELO_SYNC_INTERVAL=86400
# ═══════════════════════════════════════════════════════════════════════════════
# 19. MODEL SYNC (Dev)
# ═══════════════════════════════════════════════════════════════════════════════
# Enable the models.dev capability sync. Default: false (opt-in only).
# Also settable from Dashboard > Settings > AI. This variable wins over that
# setting whenever it is set to anything non-empty, in either direction, so a
# deployment can pin the sync on or off without depending on database state
# surviving a rebuild. Leave it unset to let the dashboard toggle decide.
# On: 1, true, yes or on (any casing). Any other value is off.
# Used by: src/lib/modelsDevSync.ts
# MODELS_DEV_SYNC_ENABLED=false
# Development-time model catalog sync interval in seconds.
# Used by: src/lib/modelsDevSync.ts
# Default: 86400 (24 hours)
# MODELS_DEV_SYNC_INTERVAL=86400
# Self-correcting context-window reconciler interval in seconds (feature 5004).
# Pins provider-declared windows from /models discovery as auto:discovery overrides
# when they diverge from the catalog. Set to 0 to disable. Never overwrites manual overrides.
# Used by: src/lib/contextWindowResolver.ts
# Default: 86400 (24 hours)
# CONTEXT_WINDOW_RECONCILE_INTERVAL=86400
# ═══════════════════════════════════════════════════════════════════════════════
# 20. PROVIDER-SPECIFIC SETTINGS
# ═══════════════════════════════════════════════════════════════════════════════
# ── Strict system-message-first providers ──
# Comma-separated, case-insensitive provider ids that require the `system`
# role message to be the first message (any later `system` message is
# rejected with HTTP 400 by the upstream chat template) — the same
# constraint documented for xiaomi-mimo/mimo (#6135, #7293). Extends the
# built-in list without a source change; useful for self-hosted connections
# in front of Qwen3.5+/3.6 or other strict-template backends.
# Used by: src/lib/memory/injection.ts::systemMessageMustBeFirst
# Default: unset (only xiaomi-mimo/mimo are flagged)
# OMNIROUTE_STRICT_SYSTEM_PROVIDERS=coding-agent
# ── OpenRouter ──
# OpenRouter model catalog cache TTL in ms.
# Used by: src/lib/catalog/openrouterCatalog.ts
# Default: 86400000 (24 hours)
# OPENROUTER_CATALOG_TTL_MS=86400000
# Enrich the dashboard providers list with OpenRouter weekly ranking stats.
# ON by default; set false to skip the background fetch entirely (#9324).
# Used by: src/lib/catalog/openrouterProviderStats.ts
# OPENROUTER_PROVIDER_STATS_ENABLED=true
# Cache TTL for the OpenRouter provider stats snapshot, in ms.
# Default: 86400000 (24 hours)
# OPENROUTER_PROVIDER_STATS_TTL_MS=86400000
# ── Model catalog response shape ──
# Include display-friendly name fields in /v1/models responses.
# Disable for clients that expect model IDs only.
# Defined in: src/shared/constants/featureFlagDefinitions.ts
# Used by: src/app/api/v1/models/catalog.ts
# Default: true
# MODEL_CATALOG_INCLUDE_NAMES=true
# Cold-path wait bound for a coalesced GET /v1/models catalog rebuild (#12627).
# Used by: src/app/api/v1/models/catalogCache.ts
# Default: 8000 (8 seconds). On timeout, a last-good 200 is served when available.
# CATALOG_BUILD_TIMEOUT_MS=8000
# Age after which a connection's synced model list stops being authoritative for routing (#12849).
# A stale (or never-timestamped) synced catalog fails open to the provider registry.
# Used by: src/lib/db/models/activeSyncedCatalog.ts
# Default: 2592000000 (30 days)
# OMNIROUTE_SYNCED_CATALOG_STALE_AFTER_MS=2592000000
# Response cache for GET /api/usage/analytics (#15629). Only responses that took at
# least MIN_COMPUTE_MS to build are kept, per query string, for TTL_MS.
# Used by: src/lib/usage/analyticsResponseCache.ts
# Default: 60000 (60 seconds; 0 disables) and 100 (100 ms)
# OMNIROUTE_ANALYTICS_CACHE_TTL_MS=60000
# OMNIROUTE_ANALYTICS_CACHE_MIN_COMPUTE_MS=100
# Opt-in: serve the usage-history part of GET /api/cache (prompt-cache totals
# and trend) from the shared analytics response cache. Unset (default) = the
# history is read live on every request. Set to N >= 0 to keep history payloads
# that took at least N ms to build, per clamped trendHours window, for
# OMNIROUTE_ANALYTICS_CACHE_TTL_MS (history may then lag up to that TTL;
# semantic/idempotency counters stay live; DELETE /api/cache invalidates it).
# Used by: src/app/api/cache/route.ts via src/lib/usage/analyticsResponseCache.ts
# Default: unset (off). Example: 1000 matches the analytics minimum.
# OMNIROUTE_CACHE_METRICS_MIN_COMPUTE_MS=1000
# ── NanoBanana (Image Generation) ──
# Polling config for async image generation jobs.
# Used by: open-sse/handlers/imageGeneration.ts
# NANOBANANA_POLL_TIMEOUT_MS=120000 # Max wait for job completion (default: 120s)
# NANOBANANA_POLL_INTERVAL_MS=2500 # Poll frequency (default: 2.5s)
# ── Adobe Firefly (Image / Video Generation) ──
# Optional absolute path to a system Chrome or Edge executable used for interactive sign-in
# and off-screen risk-session renewal. Auto-detected when unset.
# OMNIROUTE_LOGIN_BROWSER_PATH=
# Browser renewal and durable session cache are enabled by default; set either to 0 to opt out.
# ADOBE_FIREFLY_BROWSER_REFRESH=1
# ADOBE_FIREFLY_SESSION_DISK=1
# Minimum gap between generate submissions and extra gap after every third success (ms).
# ADOBE_FIREFLY_MIN_SUBMIT_GAP_MS=12000
# ADOBE_FIREFLY_BATCH_EXTRA_GAP_MS=15000
# Base backoff after a transient 408 response (ms); five attempts maximum.
# ADOBE_FIREFLY_SUBMIT_BASE_DELAY_MS=8000
# ── Adobe Firefly (Image Upscale) ──
# Base delay (ms) for the submit-retry exponential backoff when Adobe Firefly's
# upscale job submission is rate-limited. Used by:
# open-sse/services/adobeFireflyUpscale.ts::submitRetryDelayMs.
# Default: 8000 (20 under NODE_ENV=test/VITEST/NODE_TEST_CONTEXT).
# ADOBE_FIREFLY_SUBMIT_BASE_DELAY_MS=8000
# ── AWS Bedrock (Kiro / Audio) ──
# Region used to construct AWS Bedrock endpoints. Used by:
# src/lib/providers/validation.ts and open-sse/handlers/audioSpeech.ts.
# AWS_REGION takes precedence over AWS_DEFAULT_REGION when both are set.
# AWS_REGION=us-east-1
# AWS_DEFAULT_REGION=us-east-1
# ── Cloudflare Workers AI ──
# Account ID override for Cloudflare Workers AI executor.
# Used by: open-sse/executors/cloudflare-ai.ts
# CLOUDFLARE_ACCOUNT_ID=
# ── Cloudflare AI Playground ──
# Full desktop Chrome binary path, used when Playwright's bundled Chromium is
# blocked by the headless fingerprint check.
# Used by: open-sse/executors/cloudflare-playground.ts
# CLOUDFLARE_PLAYGROUND_CHROME_PATH=
# ── CodeBuddy (CN + International) system-prompt length cap ──
# CodeBuddy swaps a caller system prompt for a short neutral one when it carries
# a coding-agent identity marker (Tencent's content filter rejects those). Long
# system prompts are kept by default. Set an integer > 0 to also replace any
# system prompt longer than that many characters; unset, 0 or any non-integer
# value disables the length cap. Each replacement logs which rule fired.
# Used by: open-sse/executors/codebuddy/shared.ts
# CODEBUDDY_SYSTEM_PROMPT_MAX_LEN=
# ── Deno Deploy proxy relay (#4643 / 9router#1437) ──
# Override the Deno Deploy REST API base used by the proxy-pool relay deployer.
# Default: https://api.deno.com/v2 (omit unless mocking).
# Used by: src/app/api/settings/proxy/deno-deploy/route.ts
# DENO_DEPLOY_API_BASE=https://api.deno.com/v2
# Default Deno Deploy app name suggested in the "Deploy Relay" modal.
# Used by: src/app/(dashboard)/dashboard/settings/components/proxy/DenoRelayModal.tsx
# NEXT_PUBLIC_DENO_RELAY_DEFAULT_PROJECT=omniroute-deno-relay
# Set to "false" to hide the Deno Deploy relay option from the Proxy Pool tab.
# Used by: src/app/(dashboard)/dashboard/settings/components/proxy/ProxyPoolTab.tsx
# NEXT_PUBLIC_DENO_RELAY_ENABLED=true
# ── Cloudflare Workers proxy relay (#4640 / 9router#1360) ──
# Override the Cloudflare REST API base used by the proxy-pool relay deployer.
# Default: https://api.cloudflare.com/client/v4 (omit unless mocking).
# Used by: src/app/api/settings/proxy/cloudflare-deploy/route.ts
# CLOUDFLARE_API_BASE=https://api.cloudflare.com/client/v4
# Default worker project name suggested in the "Deploy Relay" modal.
# Used by: src/app/(dashboard)/dashboard/settings/components/proxy/CloudflareRelayModal.tsx
# NEXT_PUBLIC_CLOUDFLARE_RELAY_DEFAULT_PROJECT=omniroute-relay
# Set to "false" to hide the Cloudflare Workers relay option from the Proxy Pool tab.
# Used by: src/app/(dashboard)/dashboard/settings/components/proxy/ProxyPoolTab.tsx
# NEXT_PUBLIC_CLOUDFLARE_RELAY_ENABLED=true
# ── Cloudflare Tunnel (cloudflared) ──
# Custom path to cloudflared binary for tunnel management.
# Used by: src/lib/cloudflaredTunnel.ts
# CLOUDFLARED_BIN=/usr/local/bin/cloudflared
#
# Transport protocol for the tunnel. One of: http2 (default), quic, auto.
# CLOUDFLARED_PROTOCOL=http2
#
# ── Named / persistent tunnel (stable hostname) ──
# By default OmniRoute runs an ephemeral quick tunnel (random *.trycloudflare.com
# URL that changes on every restart). To bind a stable, named hostname instead,
# create a locally-managed tunnel with the cloudflared CLI:
# cloudflared tunnel login
# cloudflared tunnel create <name>
# cloudflared tunnel route dns <name> ai.example.com
# then write a ~/.cloudflared/config.yml with `tunnel:`, `credentials-file:`, and
# `ingress:` rules routing your hostname to http://localhost:<PORT> (default 20128).
# Point OmniRoute at that config to switch into named-tunnel mode — it runs
# `cloudflared tunnel --config <path> run`.
# CLOUDFLARED_CONFIG=/home/you/.cloudflared/config.yml
# CLOUDFLARED_HOSTNAME is optional — when unset, OmniRoute reads the public hostname
# from the config's first ingress rule. Set it to override what is reported as
# publicUrl/apiUrl.
# CLOUDFLARED_HOSTNAME=ai.example.com
# ── Search cache ──
# TTL for search API response caching (Perplexity, Brave, etc.).
# Used by: open-sse/services/searchCache.ts
# Default: 300000 (5 minutes)
# SEARCH_CACHE_TTL_MS=300000
# ── CC-compatible provider (experimental) ──
# Enable the Claude Code compatible provider endpoint.
# This is only for third-party relays that accept Claude Code clients exclusively.
# OmniRoute rewrites requests to pass those relays' Claude Code client validation.
# If you only want to use Claude Code CLI, or you are not sure what these relays are,
# keep this disabled and add a regular Anthropic-compatible provider instead.
# Used by: src/shared/utils/featureFlags.ts
# ENABLE_CC_COMPATIBLE_PROVIDER=false
# ── 9router embedded service ──
# Override the host/port where the embedded 9router instance listens.
# Rarely needed — defaults match the bootstrap config (127.0.0.1:20130).
# Used by: open-sse/executors/ninerouter.ts
# NINEROUTER_HOST=127.0.0.1
# NINEROUTER_PORT=20130
# ── Embedded service WebSocket proxy ──
# Standalone WebSocket proxy that tunnels WS connections to embedded services.
# Binds to loopback by default. Only change EMBED_WS_PROXY_HOST if you know
# what you are doing — exposing this to non-loopback bypasses local-only policy.
# Used by: src/lib/services/embedWsProxy.ts
# EMBED_WS_PROXY_HOST=127.0.0.1
# EMBED_WS_PROXY_PORT=20131
# ── opencode CLI server (opencode-server provider) ──
# The provider talks to the opencode CLI's local headless server (`opencode serve`)
# Requests never start it: launch it from Providers > Services > OpenCode (the
# local-only /api/services/opencode-server/* routes; loopback URLs only) or run
# `opencode serve` yourself. The CLI binary is env-only (never a dashboard setting)
# and the started server gets a minimal environment, not OmniRoute's secrets.
# Used by: open-sse/executors/opencodeServer.ts, open-sse/services/opencodeServerLauncher.ts
# Server URL (the opencode_server_url dashboard setting is the fallback). Default: http://127.0.0.1:4096
# OPENCODE_SERVER_URL=http://127.0.0.1:4096
# Absolute path to the opencode executable when it is not on PATH.
# OPENCODE_SERVER_BIN=
# Working directory of the server started from the dashboard. Default: the OmniRoute process cwd.
# OPENCODE_SERVER_CWD=
# Per-request timeout and server start-up timeout, in milliseconds.
# OPENCODE_SERVER_TIMEOUT_MS=180000
# OPENCODE_SERVER_START_TIMEOUT_MS=45000
# Directory for opencode-serve.log / opencode-serve.err.log. Default: ~/.omniroute/logs
# OMNIROUTE_LOG_DIR=
# ── CLIProxyAPI bridge (legacy) ──
# Connection settings for external CLIProxyAPI instances.
# Used by: open-sse/executors/cliproxyapi.ts
# CLIPROXYAPI_HOST=127.0.0.1
# CLIPROXYAPI_PORT=5544
# CLIPROXYAPI_CONFIG_DIR=~/.cli-proxy-api
# Data-plane key fallback; the cliproxyapi_api_key setting takes precedence.
# CLIPROXYAPI_API_KEY=
# Management key for an externally managed instance. Embedded instances use
# OmniRoute's encrypted service key.
# CLIPROXYAPI_MANAGEMENT_KEY=
# Host interface docker-compose publishes the cliproxyapi sidecar on (the
# --profile cliproxyapi Docker service, port 8317). Default: 127.0.0.1
# (loopback only) — its data volume holds provider OAuth/API credentials, and
# the pinned image has no env-based data-plane api-keys override (only a
# mounted config.yaml), so an unqualified publish spec would put a
# credential-bearing service on your whole LAN. (#12578)
# CLIPROXY_BIND_HOST=127.0.0.1
# ── Mux embedded service ──
# Override the port where the embedded Mux (coder/mux) agent-orchestration
# daemon listens. Always bound to 127.0.0.1 — never configurable to 0.0.0.0.
# Rarely needed — defaults to 8322.
# Used by: src/lib/services/bootstrap.ts, src/app/api/services/mux/_lib.ts
# MUX_SERVICE_PORT=8322
# ── open-wa embedded service ──
# Override the port where the embedded open-wa (WhatsApp Web automation)
# daemon listens. Always bound to 127.0.0.1 — never configurable to 0.0.0.0.
# Rarely needed — defaults to 8323.
# Used by: src/lib/services/bootstrap.ts
# OPENWA_SERVICE_PORT=8323
# ── Dario embedded service ──
# Override the host/port the embedded Dario (Claude Code subscription proxy)
# daemon binds to and is reached at. Always bound to 127.0.0.1 — never
# configurable to 0.0.0.0. Rarely needed — defaults to 127.0.0.1:3456.
# Used by: src/lib/services/installers/dario.ts, src/lib/services/bootstrap.ts,
# src/app/api/services/dario/_lib.ts, src/app/api/services/dario/admin/_lib.ts,
# open-sse/executors/dario.ts
# DARIO_HOST=127.0.0.1
# DARIO_PORT=3456
# ── LLMLingua embedded service ──
# Override the port and base URL for the embedded LLMLingua-2 prompt compression
# sidecar daemon. Always bound to 127.0.0.1 — never configurable to 0.0.0.0.
# Defaults to port 20135 and http://127.0.0.1:20135.
# Used by: src/lib/services/bootstrap.ts, src/lib/services/installers/llmlingua.ts,
# open-sse/services/compression/engines/llmlingua/index.ts
# LLMLINGUA_PORT=20135
# LLMLINGUA_BASE_URL=http://127.0.0.1:20135
# Hugging Face model id the sidecar loads (LLMLingua-2 JS port).
# LLMLINGUA_MODEL=atjsh/llmlingua-2-js-tinybert-meetingbank
# ── Local hostnames (Docker networking) ──
# Comma-separated additional hostnames treated as "local" for provider routing.
# Used by: open-sse/config/providerRegistry.ts — allows Docker service names.
# LOCAL_HOSTNAMES=omlx,mlx-audio
# ═══════════════════════════════════════════════════════════════════════════════
# 21. PROXY HEALTH
# ═══════════════════════════════════════════════════════════════════════════════
# Fine-tune proxy health checking behavior.
# Used by: src/lib/proxyHealth.ts
# Timeout for fast-fail health checks (ms). Default: 2000
# PROXY_FAST_FAIL_TIMEOUT_MS=2000
# Time window (hours) for calculating the average latency of candidate proxies
# in the latency-optimized pool strategy. Default: 3
# Used by: src/lib/db/proxies.ts
# PROXY_LATENCY_WINDOW_HOURS=3
# Health check result cache TTL (ms). Default: 30000 (30s)
# PROXY_HEALTH_CACHE_TTL_MS=30000
# Trailing window (hours) for the reasoning_effort=none compliance reader on
# GET /v1/models/health. Default: 24
# Used by: src/lib/db/reasoningEffortCompliance.ts
# NONE_HONORED_WINDOW_HOURS=24
# Cache TTL (ms) for the none-compliance snapshot (15-30s). Default: 20000
# Used by: src/lib/db/reasoningEffortCompliance.ts
# NONE_HONORED_CACHE_TTL_MS=20000
# Minimum none requests before a model reads honored/not-honored; below this
# the model reads unknown. Default: 3
# Used by: src/lib/db/reasoningEffortCompliance.ts
# NONE_HONORED_MIN_SAMPLE=3
# Unhealthy health check result cache TTL (ms). Default: 2000 (2s)
# Keeps transient fast-fail timeouts from poisoning a proxy for the full
# healthy-result cache window under high concurrency.
# PROXY_HEALTH_UNHEALTHY_CACHE_TTL_MS=2000
# Background proxy health scheduler (src/lib/proxyHealth/scheduler.ts).
# Periodically probes every registered proxy and (optionally) removes dead ones.
# Set "false" to disable the scheduler entirely. Default: enabled.
# PROXY_HEALTH_ENABLED=true
# Sweep interval in ms (minimum 60000). Default: 600000 (10min).
# PROXY_HEALTH_INTERVAL_MS=600000
# Probe interval in ms for edge-relay proxies (deno/vercel/cloudflare), whose probes wake a
# billed serverless isolate (#14984). Minimum 60000. Default: 21600000 (6h).
# PROXY_HEALTH_RELAY_INTERVAL_MS=21600000
# Background recovery-pass interval in ms: how often the scheduler re-probes proxies it
# previously marked unhealthy, so a proxy that comes back is picked up without a restart.
# Values below 60000 fall back to the default.
# PROXY_HEALTH_RECOVERY_INTERVAL_MS=600000
# Reachability probe target for the scheduler and the auto-test endpoint.
# Point it at an internal/self-hosted URL to avoid the public default.
# PROXY_HEALTH_TEST_URL=https://httpbin.org/ip
# Probes started at once per batch, for the scheduler and the auto-test endpoint.
# Floored at 1 and capped at 50. Default: 10.
# PROXY_HEALTH_TEST_CONCURRENCY=10
# Delay in ms between two probe departures inside a batch. Without it the whole batch
# leaves at once and a shared egress IP can trip a rate-limited target. 0 disables the
# spacing; capped at 5000. Default: 100.
# PROXY_HEALTH_TEST_STAGGER_MS=100
# Set "false" to stop probing the real host of a proxy's assigned provider (GET /models,
# no API key) and always use the generic target above instead. Default: enabled.
# PROXY_HEALTH_USE_PROVIDER_TARGET=true
# Set "true" to let the scheduler auto-remove proxies after repeated failures.
# PROXY_AUTO_REMOVE=false
# Consecutive failures before an auto-remove fires. Default: 3.
# PROXY_AUTO_REMOVE_AFTER=3
# Set "true" to let the scheduler auto-disable (status "dead") proxies after
# repeated failures instead of deleting them. Non-destructive alternative to
# PROXY_AUTO_REMOVE — the row stays in the registry, drops out of pool/rotation
# resolution immediately, and is automatically re-activated once it starts
# answering probes again. Shares the PROXY_AUTO_REMOVE_AFTER threshold above.
# If both PROXY_AUTO_REMOVE and PROXY_AUTO_DISABLE are "true", auto-remove wins.
# PROXY_AUTO_DISABLE=false
# Let automated reachability probes (the scheduler + the "Test All" button) WRITE
# a proxy's status. Default "false": probes are read-only and never deactivate a
# proxy — only the operator sets active/inactive (a flaky probe must not strand an
# assigned proxy; #6246). Set "true" to restore the legacy test-and-set behaviour.
# PROXY_HEALTH_AUTO_DEACTIVATE=false
# Opt-in feature flag (default off; a dashboard DB override wins over this value): 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). "true" (or 1, yes) enables it.
# PROXY_POOL_EGRESS_OBSERVATION=false
# Opt-in: skip the scheduler probe for proxies already proven by recent
# production traffic (single provider, no recent proxy failure). Default: off.
# PROXY_HEALTH_PASSIVE_SKIP=false
# Window in ms of production traffic the passive skip looks at (60000..599999).
# Default: 300000 (5min).
# PROXY_PASSIVE_WINDOW_MS=300000
# Opt-in feature flag (default off; a dashboard DB override wins over this value): accept
# operator-pushed dated observed addresses per pool member and merge them with the journal
# read for display and pool order. "true" (or 1, yes) enables the push route and the merge.
# PROXY_OPERATOR_EGRESS_ENABLED=false
# Observation window for operator-pushed egress rows (read on every read; no restart
# needed). Bounded to 1..168; out-of-range, non-numeric, or empty falls back to 24 with a
# single process-wide warning, never a throw.
# Used by: src/lib/db/proxyOperatorEgress.ts.
# PROXY_OPERATOR_EGRESS_WINDOW_HOURS=24
# Allow OAuth and provider validation flows to bypass a pinned proxy and connect
# directly when proxy reachability pre-checks fail. Default: false.
# Also configurable from Dashboard > Settings > Feature Flags.
# OMNIROUTE_CONTROL_PLANE_PROXY_DIRECT_FALLBACK=false
# Rate limit maximum wait time before failing a request (ms). Default: 30000 (30s)
# Used by: open-sse/services/rateLimitManager.ts
# RATE_LIMIT_MAX_WAIT_MS=30000
# Limiter-managed execution backstop (Bottleneck `expiration`): bounds a job's
# post-dispatch execution, never queue wait. Must stay ABOVE upstream
# fetch-start timeouts on non-incremental gateways. Default: 600000 (10 min)
# Used by: open-sse/services/rateLimitManager.ts
# RATE_LIMIT_EXECUTION_MAX_WAIT_MS=600000
# Rate limit queue admission cap: reject with 429 queue_full once this many requests
# are already queued (0 = disabled/unbounded, the default). Used by: open-sse/services/rateLimitManager.ts
# RATE_LIMIT_MAX_QUEUE_DEPTH=0
# Force the auto-enable rate limit safety net on/off regardless of the persisted
# Dashboard setting. Used by: open-sse/services/rateLimitManager.ts.
# Accepted values: true|1|on (force on), false|0|off (force off), unset (use Dashboard).
# RATE_LIMIT_AUTO_ENABLE=
# Provider cooldown tracking: minimum time (ms) before a failed provider/connection
# can be retried. Prevents subsequent requests from re-walking failing providers.
# Scaled exponentially: minCooldown * 2^(failures-1), capped at maxRetryCooldownMs.
# Used by: open-sse/services/providerCooldownTracker.ts
# PROVIDER_COOLDOWN_MIN_MS=5000
# Provider cooldown tracking: maximum time (ms) before a failed provider/connection
# is retried regardless. Hard cap to prevent providers from being skipped indefinitely.
# Used by: open-sse/services/providerCooldownTracker.ts
# PROVIDER_COOLDOWN_MAX_MS=300000
# Enable/disable global provider cooldown tracking. Opt-in: this global
# cross-request cooldown overlaps the existing Connection Cooldown / Provider
# Circuit Breaker layers, so it is OFF by default. When disabled, only the
# existing per-request/per-connection cooldown state is used (previous behavior).
# Used by: open-sse/services/providerCooldownTracker.ts
# Accepted values: true|1|on (enable). Unset or anything else = disabled (default).
# PROVIDER_COOLDOWN_ENABLED=true
# Transparent stream recovery (free-claude-code port). When enabled, the opening SSE
# window is briefly held (up to STREAM_RECOVERY.HOLDBACK_MS) so an upstream truncation
# before any byte reaches the client can be retried invisibly. Opt-in: holding the
# window adds up to that much time-to-first-token latency on every stream, so it is
# OFF by default. Seeds ResilienceSettings.streamRecovery.enabled.
# Used by: open-sse/services/streamRecovery.ts, open-sse/handlers/chatCore.ts
# Accepted values: true|1|on (enable). Unset or anything else = disabled (default).
# STREAM_RECOVERY_ENABLED=true
# Mid-stream continuation (Fase 4.4): when an upstream stream truncates AFTER bytes
# already reached the client, re-request with the partial text as an assistant prefill
# and stitch the missing suffix (plain-text OpenAI-compatible streams only; never with a
# tool call in flight). OFF by default — the recovered tail arrives as one burst, not
# token-by-token. Independent of STREAM_RECOVERY_ENABLED (different risk profile).
# Seeds ResilienceSettings.streamRecovery.continueMidStream.
# Used by: open-sse/services/streamRecovery.ts, open-sse/handlers/chatCore.ts
# Accepted values: true|1|on (enable). Unset or anything else = disabled (default).
# STREAM_RECOVERY_MIDSTREAM_ENABLED=true
# Active-stream throughput watchdog (#9709). Detects streams that keep sending
# heartbeats/chunks but produce too little useful assistant text. Separate from
# STREAM_IDLE_TIMEOUT_MS (silence) and the hard upstream attempt deadline. OFF by
# default. Tool-call/reasoning phases suspend judgement; post-commit streams are
# never blindly replayed.
# STREAM_THROUGHPUT_WATCHDOG_ENABLED=true
# STREAM_THROUGHPUT_WATCHDOG_WARMUP_MS=30000
# STREAM_THROUGHPUT_WATCHDOG_WINDOW_MS=30000
# STREAM_THROUGHPUT_WATCHDOG_MIN_BYTES_PER_SECOND=4
# STREAM_THROUGHPUT_WATCHDOG_MIN_USEFUL_BYTES=1
# Stagger interval (ms) between provider token healthchecks at startup.
# Used by: src/lib/tokenHealthCheck.ts. Default: 3000.
# HEALTHCHECK_STAGGER_MS=3000
# Randomized jitter range (ms) added on top of HEALTHCHECK_STAGGER_MS between
# provider token healthchecks, to prevent bursting (Issue #1220).
# Used by: src/lib/tokenHealthCheck.ts. Defaults: min=500, max=5000.
# HEALTHCHECK_JITTER_MIN_MS=500
# HEALTHCHECK_JITTER_MAX_MS=5000
# Concurrent-check batch size for the startup token-healthcheck sweep. Larger
# values check more connections in parallel; smaller values reduce burst load.
# Used by: src/lib/tokenHealthCheck.ts. Default: 20 (Issue #7875, regression of #7719).
# HEALTHCHECK_BATCH_SIZE=20
# ═══════════════════════════════════════════════════════════════════════════════
# 22. DEBUGGING
# ═══════════════════════════════════════════════════════════════════════════════
# These variables enable verbose debugging output. NEVER enable in production.
# Cursor executor verbose debug (decoded SSE chunks, etc.).
# CURSOR_STREAM_DEBUG is kept as a backward-compatible alias.
# Used by: open-sse/executors/cursor.ts
# CURSOR_DEBUG=1
# Enable verbose trace logging for OmniRoute internals.
# Used by: open-sse/handlers/chatCore.ts.
# OMNIROUTE_TRACE=true
# Standard DEBUG flag (same effect as OMNIROUTE_TRACE).
# DEBUG=true
# CURSOR_STREAM_DEBUG=1
# When CURSOR_DEBUG=1, also append raw decoded chunks to this file path.
# CURSOR_DUMP_FILE=/tmp/cursor-stream.log
# Cursor stream idle timeout (ms). Default: 300000 (5 min).
# Used by: open-sse/executors/cursor.ts.
# CURSOR_STREAM_TIMEOUT_MS=300000
# Grace window (ms) after a composer kv_after_text soft terminator when bytes remain
# buffered — gives a trailing exec_mcp tool call time to complete its frame. 2s covers
# every exec_mcp-behind-kv ordering observed live.
# CURSOR_KV_GRACE_MS=2000
# Cursor tool-commit directive toggle. Default-on: when a request declares
# tools, a directive is prepended so composer-2.5 reliably issues tool calls
# instead of narrating intent. Set to 0 to disable.
# Used by: open-sse/executors/cursor.ts.
# CURSOR_TOOL_DIRECTIVE=1
# Operator-defined system prompt text appended to the system message AFTER
# translation (post-translation injection), so it reaches codex/Responses and
# /v1/messages paths. Also used as the directive prefix stripped from echoed
# system preamble blocks. Leave unset to disable.
# Used by: open-sse/translator/request/claude-to-openai.ts, open-sse/translator/response/openai-to-claude.ts.
# OMNIROUTE_SYSTEM_INSTRUCTION_APPEND=
# Set to "1" to also strip echoed system-prompt PREAMBLE blocks
# (<analysis>/<system-reminder>/<summary> blocks, prose reproductions of the skill
# section) from the start of an openai->claude stream. OFF by default: it recognises
# constructs by English-prose heuristics and DOES mutate the response payload, so a
# reply that genuinely opens with such a section would lose it. Turn it on only when
# you actually hit the system-echo leak.
# Used by: open-sse/translator/response/openai-to-claude.ts, open-sse/utils/directivePreambleStripper.ts.
# OMNIROUTE_STRIP_SYSTEM_PREAMBLE=0
# Per-image fetch timeout (ms) for remote image_url vision input. Default: 15000.
# Used by: open-sse/utils/cursorImages.ts.
# CURSOR_IMAGE_FETCH_TIMEOUT_MS=15000
# Cursor state DB path override (for IDE cursor version detection).
# Used by: open-sse/utils/cursorVersionDetector.ts. Default: probed automatically.
# CURSOR_STATE_DB_PATH=
# Cursor Agent CLI build id for AgentService/Run impersonation (YYYY.MM.DD-<hash>).
# Used by: open-sse/utils/cursorAgentCliVersion.ts. Default: detect local install, else pin.
# CURSOR_AGENT_CLI_VERSION=2026.07.08-0c04a8a
# Path to the Cursor Agent binary used for image generation.
# Used by: open-sse/handlers/imageGeneration/providers (CURSOR_IMAGE.md).
# CURSOR_AGENT_BIN=/path/to/agent
# Cursor image-generation wall clock (ms). Default: 210000.
# CURSOR_IMG_TIMEOUT_MS=210000
# UC (uncensored.com) image-generation result-poll cadence + wall clock (ms).
# Used by: open-sse/handlers/imageGeneration/providers/ucImage.ts. Defaults: 2000 / 60000.
# UC_IMAGE_POLL_INTERVAL_MS=2000
# UC_IMAGE_POLL_TIMEOUT_MS=60000
# UC (uncensored.com) video-generation result-poll cadence + wall clock (ms).
# Used by: open-sse/handlers/videoGeneration/providers/ucVideo.ts. Defaults: 3000 / 300000.
# UC_VIDEO_POLL_INTERVAL_MS=3000
# UC_VIDEO_POLL_TIMEOUT_MS=300000
# Shared-seat concurrency gate for Cursor image jobs. Default: 2.
# CURSOR_IMG_MAX_CONCURRENT=2
# Override Cursor CLI --model for image jobs. Default: request model / auto.
# CURSOR_IMG_MODEL=auto
# Cursor Agent CLI data directory override (versions live under <dir>/versions/).
# Used by: open-sse/utils/cursorAgentCliVersion.ts. Default: ~/.local/share/cursor-agent (unix)
# or %LOCALAPPDATA%\cursor-agent (win32). Official agent CLI also honors this var.
# CURSOR_DATA_DIR=
# Direct Cursor bearer token used by scripts/ad-hoc/cursor-tap.cjs (developer tooling).
# CURSOR_TOKEN=
# Log Responses API SSE-to-JSON translation details.
# DEBUG_RESPONSES_SSE_TO_JSON=true
# Log request shape (content-type + content-length) for large chat payloads.
# Used by: src/app/api/v1/chat/completions/route.ts. Set to "0" to silence.
# Default: disabled (opt-in).
# OMNIROUTE_LOG_REQUEST_SHAPE=1
# Write raw (untruncated) request/response JSON in call log artifacts.
# When enabled, serializeArtifactForStorage skips size-based truncation.
# Also enabled automatically when APP_LOG_LEVEL=debug.
# WARNING: produces large files — use only for temporary debugging.
# CHAT_DEBUG_FILE=true
# Surf empty textContent chunks in the Claude response translation path for debugging.
# Used by: open-sse/handlers/responseTranslator.ts. Set to "true" to enable.
# Default: disabled (opt-in).
# DEBUG_CLAUDE_NONSTREAM=true
# Enable E2E test mode — relaxes auth and enables test harness hooks.
# NEXT_PUBLIC_OMNIROUTE_E2E_MODE=true
# ═══════════════════════════════════════════════════════════════════════════════
# 23. GITHUB INTEGRATION (Issue Reporting)
# ═══════════════════════════════════════════════════════════════════════════════
# Allow users to report issues directly from the Dashboard to GitHub.
# Used by: src/app/api/v1/issues/report/route.ts
# GitHub repository in owner/repo format.
# GITHUB_ISSUES_REPO=owner/repo
# GitHub Personal Access Token with issues:write scope.
# GITHUB_ISSUES_TOKEN=ghp_xxxx
# Generic GitHub access token consumed by issue triage / agent helpers.
# Used by: src/app/api/v1/issues/* and src/lib/cloudAgent/* — falls back to
# GITHUB_ISSUES_TOKEN when unset.
# GITHUB_TOKEN=
# ═══════════════════════════════════════════════════════════════════════════════
# 24. PROVIDER QUOTAS, TUNNELS & SANDBOXED SKILLS
# ═══════════════════════════════════════════════════════════════════════════════
# Provider quota endpoints, network tunnels (Tailscale, Ngrok, MITM debug
# proxy), 1Proxy egress pool, skills sandbox runtime, and miscellaneous CLI
# binaries referenced by the executor layer or the dashboard runtime.
# ── Alibaba (Bailian) coding plan quota ──
# Host/full URL override used by: open-sse/services/bailianQuotaFetcher.ts.
# When unset the fetcher uses the production Alibaba endpoints.
# ALIBABA_CODING_PLAN_HOST=
# ALIBABA_CODING_PLAN_QUOTA_URL=
# ── Qwen Cloud / Model Studio personal Token Plan quota ──
# Cookie-authenticated console-gateway fetcher (issue #9603). Used by:
# open-sse/services/qwenTokenPlanQuotaFetcher.ts. Prefer the per-connection
# Dashboard fields (qwenCloudCookie / qwenCloudSecToken) — these env vars are
# global fallbacks. Cookie/sec_token are SENSITIVE session credentials.
# Getting the cookie: log in to home.qwencloud.com > Billing > Subscription,
# press F12 > Network, reload, filter by api.json, click any request to
# cs-data.qwencloud.com and copy the WHOLE Cookie value from Request Headers
# (it contains login_qwencloud_ticket). Paste it on ONE line — the value may
# contain '=' and ';'. It expires with the browser session; re-paste it when
# the dashboard reports an expired session.
# QWEN_CLOUD_COOKIE=
# QWEN_CLOUD_SEC_TOKEN=
# QWEN_TOKEN_PLAN_HOST=
# QWEN_TOKEN_PLAN_DASHBOARD_URL=
# ── Xiaomi MiMo Token Plan quota ──
# Console-cookie live fetch + self-tracked fallback (issue #15753). Used by:
# open-sse/services/usage/xiaomi-mimo.ts. Prefer the per-connection Dashboard
# fields (xiaomiMimoConsoleCookie / monthlyTokenLimit) — these env vars are
# global fallbacks. The cookie is a SENSITIVE session credential.
# Getting the cookie: log in to platform.xiaomimimo.com, open the Token Plan
# page, press F12 > Network, reload, click any request to
# platform.xiaomimimo.com and copy the WHOLE Cookie value from Request Headers
# (it contains api-platform_serviceToken and userId). Paste it on ONE line —
# the value may contain '=' and ';'. It expires with the browser session;
# re-paste it when the dashboard reports an expired session.
# XIAOMI_MIMO_CONSOLE_COOKIE=
# Monthly budget (Credits) for the OmniRoute-tracked fallback without a cookie.
# Default: 4100000000 (Lite tier). Standard 11000000000 / Pro 38000000000 /
# Max 82000000000.
# XIAOMI_MIMO_MONTHLY_TOKEN_LIMIT=
# ── Alibaba Model Studio free-tier quota sync ──
# Console front-end path overrides for the free-tier quota fetcher. Used by:
# open-sse/services/alibabaFreeTierQuotaFetcher.ts. When unset, the fetcher
# uses the production Bailian console paths.
# ALIBABA_FREE_TIER_VISION_FE_PATH=
# ALIBABA_FREE_TIER_MULTIMODAL_FE_PATH=
# ALIBABA_FREE_TIER_AUDIO_FE_PATH=
# Optional path to a local JSON override for the built-in text free-tier
# allowlist. Used by: open-sse/services/alibabaFreeTierAllowlist.ts. When
# unset, the fetcher falls back to $DATA_DIR/alibaba-free-tier-allowlist.json
# then config/alibaba-free-tier-allowlist.json.
# ALIBABA_FREE_TIER_ALLOWLIST_PATH=
# ── Context window tuning ──
# Tokens reserved for completion output when computing prompt budgets.
# Used by: open-sse/services/contextManager.ts. Default: 1024.
# CONTEXT_RESERVE_TOKENS=1024
# How many of the newest inline images to keep when pruning older ones to fit
# the context window (#8560). Used by: open-sse/services/contextManager.ts.
# Default: 2.
# CONTEXT_KEEP_LATEST_IMAGES=2
# ── Model alias rewriting (legacy compatibility) ──
# Toggle the legacy model-alias compatibility layer used by older clients.
# Used by: open-sse/services/model.ts. Default: enabled.
# MODEL_ALIAS_COMPAT_ENABLED=true
# ── Devin CLI binary path ──
# Used by: open-sse/executors/devin-cli.ts. Default: looked up via PATH.
# CLI_DEVIN_BIN=devin
# Agentic bridge-only binary override. The bridge still executes ACP stdio only.
# CLI_DEVIN_AGENTIC_BIN=devin
# Required isolated HOME for the agentic Devin child process.
# DEVIN_AGENTIC_HOME=/home/bridge
# Bounded ACP turn timeout in milliseconds. Default: 120000.
# DEVIN_AGENTIC_ACP_TIMEOUT_MS=120000
# Agentic bridge model aliases. Values must keep the devin-cli-agentic/ prefix.
# DEVIN_BRIDGE_MODEL=devin-cli-agentic/swe-1-7
# DEVIN_BRIDGE_SONNET_MODEL=devin-cli-agentic/swe-1-7
# DEVIN_BRIDGE_OPUS_MODEL=devin-cli-agentic/swe-1-7
# DEVIN_BRIDGE_HAIKU_MODEL=devin-cli-agentic/swe-1-7
# DEVIN_BRIDGE_SUBAGENT_MODEL=devin-cli-agentic/swe-1-7
# ── Devin Desktop upstream compatibility versions ──
# Desktop ide_version. Must use x.y.z format; invalid/unset values use 3.6.27.
# DEVIN_DESKTOP_VERSION=3.6.27
# Bundled Codeium/language-server extension_version, distinct from Desktop.
# Must use x.y.z format; invalid/unset values use the bundled default 1.48.2.
# DEVIN_DESKTOP_EXTENSION_VERSION=1.48.2
# Optional override for the Codeium seat-management API used by Devin CLI quota.
# Used by: open-sse/services/usage/devinCli.ts. Default: https://server.codeium.com
# DEVIN_SEAT_API_URL=https://server.codeium.com
# ── Command Code (custom CLI) callback ──
# Local port used for OAuth-style callbacks from the Command Code CLI helper.
# Used by: src/app/api/providers/command-code/auth/shared.ts.
# COMMAND_CODE_CALLBACK_PORT=
# ── Command Code CLI version header ──
# Value sent as the x-command-code-version header to the Command Code upstream.
# Overrides the built-in default; bump if the upstream requires a newer CLI version.
# Used by: open-sse/executors/commandCode.ts
# Default: 0.33.2
# COMMAND_CODE_VERSION=0.33.2
# Base URL for the Command Code usage/quota upstream, used by smartphone
# quota-fetcher telemetry.
# Used by: open-sse/services/usage/command-code.ts
# Default: https://api.commandcode.ai
# COMMANDCODE_API_URL=https://api.commandcode.ai
# ── MITM debug proxy (development only) ──
# Used by: src/mitm/server.cjs — captures upstream traffic for inspection.
# MITM_LOCAL_PORT=443
# MITM_DISABLE_TLS_VERIFY=0
# Idle socket timeout (ms) for proxied connections; sockets idle past this are torn
# down to avoid leaking half-open tunnels (src/mitm/socketTimeouts.ts, server.cjs).
# MITM_IDLE_TIMEOUT_MS=60000
# Routing-decision log verbosity: 0 silences, higher values log more bypass/route
# decisions (src/mitm/server.cjs, _internal/bypass.cjs).
# MITM_VERBOSE=1
# Strip the leading `sudo` from MITM cert-trust commands (src/mitm/systemCommands.ts) —
# for root-less / user-namespaced deployments (e.g. rootless Docker/Podman)
# where the operator trusts the CA manually (e.g. via Node's extra-CA-certs mechanism).
# OMNIROUTE_NO_SUDO=0
# ── Antigravity MITM bridge (bin/antigravity-bridge.mjs) ──
# Local HTTPS listener that fronts the Antigravity IDE and forwards to the router.
# BRIDGE_PORT: port the bridge listens on. Defaults to 20129.
# ROUTER_URL: where it forwards /v1/antigravity traffic. Defaults to the local router.
# CERT_DIR: directory holding server.key/server.crt for the bridge's TLS listener.
# Defaults to ~/.omniroute/mitm (the MITM CA directory).
# BRIDGE_PORT=20129
# ROUTER_URL=http://127.0.0.1:20128/v1/antigravity
# CERT_DIR=~/.omniroute/mitm
# Explicit opt-out: skip provisioning /etc/hosts DNS entries for the Antigravity
# proxy hostnames entirely (containers with no sudo/root available).
# Used by: src/mitm/dns/provision.ts.
# SKIP_ANTIGRAVITY_DNS=true
# Skip writing to the hosts file when adding/removing DNS entries (e.g. sandboxed
# or read-only test environments). Used by: src/mitm/dns/dnsConfig.ts.
# OMNIROUTE_SKIP_DNS_WRITE=1
# Opt in to the root-CA + per-host-leaf cert model for the MITM proxy (#6684).
# Fresh installs and installs with this set to "true" get a persisted root CA that
# signs per-host leaves; installs with a pre-existing trusted legacy leaf keep the
# legacy fixed-SAN cert unless opted in. Used by: src/mitm/manager.ts.
# MITM_ROOT_CA_ENABLED=true
# Set BY the MITM manager for the spawned proxy process ("root-ca" | "legacy") —
# reflects the migration decision above; not meant to be set manually.
# Read by: src/mitm/server.cjs.
# MITM_CERT_MODE=legacy
# ── Test/CI-only guards (never needed in production) ──
# Set automatically by tests/_setup/isolateDataDir.ts and the CI workflows: the
# test suite must NEVER mutate the OS trust store (a fake test PEM installed via
# update-ca-certificates broke all system TLS on a persistent runner, 2026-07-05).
# OMNIROUTE_SKIP_SYSTEM_TRUST=1
# check-changelog-integrity.mjs (anti CHANGELOG-eat gate): explicit base ref override.
# Intentional transformations require an exact reviewed entry in
# config/release/changelog-reconciliations.json; there is no runtime bypass.
# CHANGELOG_BASE_REF=origin/release/v0.0.0
# check-migration-numbering.mjs: explicit base ref for the comparison with the base
# (defaults in CI to the PR merge ref's first parent / merge_group.base_sha / merge-base).
# MIGRATION_BASE_REF=origin/release/v0.0.0
# Test-only: stand-in for scripts/check/migration-commutation.ts in the gate's tests.
# MIGRATION_COMMUTATION_SCRIPT=
# ── Remote audio provider nodes ──
# Used by: src/app/api/v1/_shared/audioProviderNodes.ts — lets the /v1/audio/*
# routes use an OpenAI-compatible provider node hosted outside localhost.
# OFF by default: routing audio to a remote host changes egress identity, so it
# must be an explicit operator decision. Loopback/private nodes (localhost,
# 127.0.0.1, 172.16-31.x) are always allowed and unaffected by this flag.
# When enabled, the node authenticates with the API key stored on its connection.
# AUDIO_REMOTE_PROVIDER_NODES=false
# Used by: src/app/api/v1/_shared/rerankProviderNodes.ts — lets POST /v1/rerank (and
# the memory engine's loopback rerank step) use an OpenAI-compatible provider node
# hosted outside localhost, e.g. a LAN box or Tailscale peer running TEI/Infinity/vLLM.
# OFF by default: routing to a remote host changes egress identity, so it must be an
# explicit operator decision. Loopback/private nodes (localhost, 127.0.0.1,
# 172.16-31.x) are always allowed and unaffected by this flag. A remote node's base URL
# must also pass the provider outbound URL policy (see OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS).
# RERANK_REMOTE_PROVIDER_NODES=false
# Used by: src/shared/network/localNodeHosts.ts — hostnames (comma or whitespace
# separated) that provider-node routing treats as local, e.g. the Docker/Compose service
# name of a reranker or TEI sidecar on OmniRoute's own Docker network, so the node does
# not need a hard-coded container IP. Listed hosts are eligible for the /v1/rerank and
# /v1/audio/* provider-node routes and the local health check without turning on
# RERANK_/AUDIO_REMOTE_PROVIDER_NODES for every remote node, and are called directly
# (never through HTTP(S)_PROXY or a connection's pinned proxy). They still send the
# connection's API key. Only single-label names and .internal/.local names are
# accepted; public FQDNs, IP literals and cloud-metadata names are ignored with a warning.
# Empty by default (no change).
# OMNIROUTE_LOCAL_PROVIDER_NODE_HOSTS=reranker,tei
# ── Free Proxy Pool (auto-sync scheduler) ──
# Background refresh of the free-proxy pool. Opt-in, OFF by default (parallels
# Hard Rule #20's default-off posture for data-mutating background features).
# Used by: src/lib/freeProxyProviders/scheduler.ts
# FREE_PROXY_AUTO_SYNC_ENABLED=true
# Sync interval in ms (default: 1800000 = 30 min).
# FREE_PROXY_AUTO_SYNC_INTERVAL_MS=1800000
# ── Free Proxy Pool (1proxy source) ──
# Used by: src/lib/freeProxyProviders/oneproxy.ts
# Set FREE_PROXY_1PROXY_ENABLED=false to disable this source.
# FREE_PROXY_1PROXY_ENABLED=true
# FREE_PROXY_1PROXY_API_URL=https://1proxy-api.aitradepulse.com/api/v1/proxies/advanced
# FREE_PROXY_1PROXY_MAX=500
# FREE_PROXY_1PROXY_MIN_QUALITY=50
# ── Free Proxy Pool (Proxifly source) ──
# Used by: src/lib/freeProxyProviders/proxifly.ts
# Enabled by default; set to false to disable.
# FREE_PROXY_PROXIFLY_ENABLED=true
# FREE_PROXY_PROXIFLY_QUANTITY=100
# FREE_PROXY_PROXIFLY_ANONYMITY=elite
# ── Free Proxy Pool (IPLocate source) ──
# Used by: src/lib/freeProxyProviders/iplocate.ts
# Opt-in only; must set FREE_PROXY_IPLOCATE_ENABLED=true to activate.
# FREE_PROXY_IPLOCATE_ENABLED=false
# FREE_PROXY_IPLOCATE_BASE_URL=https://raw.githubusercontent.com/iplocate/free-proxy-list/main/protocols
# ── Free Proxy Pool (Webshare source) ──
# Used by: src/lib/freeProxyProviders/webshare.ts
# Paid, per-account proxy list — requires FREE_PROXY_WEBSHARE_API_KEY to activate,
# regardless of FREE_PROXY_WEBSHARE_ENABLED.
# FREE_PROXY_WEBSHARE_ENABLED=true
# FREE_PROXY_WEBSHARE_API_KEY=
# FREE_PROXY_WEBSHARE_API_URL=https://proxy.webshare.io/api/v2/proxy/list/
# FREE_PROXY_WEBSHARE_MAX=500
# ── Vercel Relay ──
# Used by: src/app/api/settings/proxy/vercel-deploy/route.ts
# Hides the "Deploy Relay" button when set to false.
# NEXT_PUBLIC_VERCEL_RELAY_ENABLED=true
# VERCEL_API_BASE=https://api.vercel.com
# Default project name pre-filled in the Vercel Relay deploy modal.
# NEXT_PUBLIC_VERCEL_RELAY_DEFAULT_PROJECT=omniroute-relay
# ── Tailscale tunnel binaries ──
# Optional explicit paths to tailscale/tailscaled binaries used by the
# dashboard's tunnel manager. Used by: src/lib/tailscaleTunnel.ts.
# TAILSCALE_BIN=/usr/local/bin/tailscale
# TAILSCALED_BIN=/usr/local/bin/tailscaled
# Pre-shared Tailscale auth key for non-interactive / headless `tailscale up`
# (passed via --auth-key=). When unset, login falls back to the interactive
# browser auth URL. Used by: src/lib/tailscaleTunnel.ts.
# TAILSCALE_AUTHKEY=
# ── Ngrok tunnel ──
# Used by: src/lib/ngrokTunnel.ts — authenticates outbound tunnels.
# NGROK_AUTHTOKEN=
# ── Database backups ──
# Used by: src/lib/db/backup.ts.
# DB_BACKUP_MAX_FILES=20
# DB_BACKUP_RETENTION_DAYS=0
# Tick interval (ms) of the server-side job that executes backup-schedule.json.
# Must stay well under the 1-minute cron granularity; values below 5000 (or
# unparseable) fall back to the 30000 default.
# Used by: src/lib/jobs/backupScheduleJob.ts
# OMNIROUTE_BACKUP_SCHEDULE_JOB_INTERVAL_MS=30000
# ── Skills sandbox (experimental) ──
# Used by: src/lib/skills/builtins.ts. All values support comma lists where
# noted in the source.
# SKILLS_MAX_FILE_BYTES=1048576
# SKILLS_MAX_HTTP_RESPONSE_BYTES=256000
# SKILLS_MAX_SANDBOX_OUTPUT_CHARS=100000
# SKILLS_SANDBOX_TIMEOUT_MS=10000
# SKILLS_SANDBOX_NETWORK_ENABLED=0
# SKILLS_ALLOWED_SANDBOX_IMAGES=
# Container runtime used by the skill sandbox. Accepted values:
# auto — pick the best installed runtime per host OS (default)
# docker — Docker Engine / Docker Desktop
# apple — Apple Container (macOS native, micro-VM)
# wsl — WSL Container (Windows native via wslc.exe)
# orbstack — OrbStack (high-perf Linux VM + docker shim on macOS)
# podman — Podman (rootless, daemonless)
# agent-sandbox — remote Kubernetes sandbox (kubernetes-sigs/agent-sandbox warm
# pools, e.g. gVisor/Kata). Opt-in only, never auto-detected.
# SKILLS_SANDBOX_RUNTIME=auto
# agent-sandbox runtime (only read when SKILLS_SANDBOX_RUNTIME=agent-sandbox).
# Each run creates one SandboxClaim from a warm pool, runs the command with
# `kubectl exec`, then deletes the claim. Isolation and limits come from the
# operator's SandboxTemplate, so SKILLS_SANDBOX_NETWORK_ENABLED does not apply
# here: network policy, read-only rootfs and CPU/memory limits are set there.
# The kubeconfig needs, in the namespace:
# sandboxclaims create/get/list/watch/delete, pods get, pods/exec create.
# Image -> warm pool mapping (image=pool, comma-separated):
# SKILLS_AGENT_SANDBOX_POOLS=python:3.12-alpine=py-pool,node:22-alpine=js-pool
# Fallback warm pool for images not listed above:
# SKILLS_AGENT_SANDBOX_POOL=
# SKILLS_AGENT_SANDBOX_NAMESPACE=default
# SKILLS_AGENT_SANDBOX_KUBECONFIG=
# SKILLS_AGENT_SANDBOX_KUBECTL=kubectl
# SKILLS_AGENT_SANDBOX_CONTAINER=main
# SKILLS_AGENT_SANDBOX_CLAIM_TIMEOUT_S=60
# ═══════════════════════════════════════════════════════════════════════════════
# 25. TEST & E2E
# ═══════════════════════════════════════════════════════════════════════════════
# Used by scripts/dev/run-next-playwright.mjs, scripts/dev/smoke-electron-packaged.mjs,
# scripts/dev/run-ecosystem-tests.mjs and scripts/build/uninstall.mjs.
# Production deployments should leave every value below unset.
# E2E bootstrap mode for the Playwright runner. Accepted: auth | fresh | reuse.
# Default (when unset): auth.
# OMNIROUTE_E2E_BOOTSTRAP_MODE=auth
# Admin password injected into the Playwright test environment.
# Falls back to INITIAL_PASSWORD when unset.
# OMNIROUTE_E2E_PASSWORD=
# Disable the local healthcheck poll during Playwright runs (default: true).
# OMNIROUTE_DISABLE_LOCAL_HEALTHCHECK=true
# Disable the OAuth token healthcheck loop during tests (default: true).
# OMNIROUTE_DISABLE_TOKEN_HEALTHCHECK=true
# Exclude specific providers from the PROACTIVE token-refresh sweep (comma-separated,
# case-insensitive). Targeted alternative to OMNIROUTE_DISABLE_TOKEN_HEALTHCHECK: keeps
# rotating-cascade providers (Codex/OpenAI share one Auth0 family) on the reactive 401
# path only, while short-TTL providers like Kimi-coding keep being refreshed proactively.
# OMNIROUTE_HEALTHCHECK_SKIP_PROVIDERS=codex,openai
# Read synchronized Codex tokens instead of rotating refresh tokens on this instance.
# Opt-in; empty/unset keeps normal refresh behaviour. Supported ids: codex, cx
# (comma-separated, case-insensitive). Other ids fail startup validation.
# Only manual refresh returns a passive error; implicit refreshes reread the DB.
# Keep one active rotation owner and synchronize its connection tokens yourself.
# This does not provide distributed locking or prevent new OAuth logins.
# OMNIROUTE_TOKEN_REFRESH_PASSIVE_PROVIDERS=codex
# Silence healthcheck noise in Playwright stdout (default: true).
# OMNIROUTE_HIDE_HEALTHCHECK_LOGS=true
# Skip the Next.js production build before Playwright starts (CI optimization).
# OMNIROUTE_PLAYWRIGHT_SKIP_BUILD=0
# Skip the OmniRoute uninstall hook (used by CI to keep node_modules intact).
# OMNIROUTE_SKIP_UNINSTALL_HOOK=0
# Ecosystem/protocol test orchestrators wait this long (ms) for the server to
# become healthy. Default: 180000.
# ECOSYSTEM_SERVER_WAIT_MS=180000
# Docs translation pipeline (used by scripts/i18n/run-translation.mjs).
# OpenAI-compatible base URL, e.g. https://cloud.omniroute.online/v1
# OMNIROUTE_TRANSLATION_API_URL=
# Bearer token for the translation backend (NEVER commit a real key here).
# OMNIROUTE_TRANSLATION_API_KEY=
# Model id, e.g. gpt-4o-mini or cx/gpt-5.6-sol.
# OMNIROUTE_TRANSLATION_MODEL=gpt-4o-mini
# Optional fallback chain, comma-separated, tried in order when the model above fails for a
# reason another model could fix (429 quota, 401/402, 5xx, timeout, network). A malformed
# request (400/413/422) is not retried elsewhere. The wave's per-chunk validator still rejects
# dropped lines or leaked reasoning whichever model answered.
# OMNIROUTE_TRANSLATION_FALLBACK_MODELS=cmd/deepseek/deepseek-v4.1-flash
# Per-request timeout in milliseconds (default 60000).
# OMNIROUTE_TRANSLATION_TIMEOUT_MS=60000
# Optional reasoning control, sent as-is to the translation backend when set (e.g. none).
# OMNIROUTE_TRANSLATION_REASONING_EFFORT=
# Number of parallel translation requests (default 4).
# OMNIROUTE_TRANSLATION_CONCURRENCY=4
# Translation engine: llm (default, the backend above) or google (structure-safe Google
# Translate engine; needs none of the LLM variables).
# OMNIROUTE_TRANSLATION_ENGINE=llm
# With the llm engine, translate a chunk the model could not produce through Google instead of
# failing the locale (default 1; 0 disables).
# OMNIROUTE_TRANSLATION_GOOGLE_FALLBACK=1
# Optional Cloud Translation v2 key; unset uses the keyless web endpoint (rate-limited).
# OMNIROUTE_TRANSLATION_GOOGLE_API_KEY=
# Parallel Google requests shared by every locale of a run (default 6).
# OMNIROUTE_TRANSLATION_GOOGLE_CONCURRENCY=6
# Per-request timeout for the Google engine in milliseconds (default 30000).
# OMNIROUTE_TRANSLATION_GOOGLE_TIMEOUT_MS=30000
# ── UI kit upstream check (CI / maintainers only) ──
# Read-only token for the private upstream kit repo (keak-ai/cheaper-inference-ui-kit), used by
# `npm run check:ui-kit-upstream` and the weekly "UI Kit upstream watch" workflow. Locally the
# check uses your git credentials (gh auth) and this can stay unset.
# UI_KIT_READ_TOKEN=
# ─── Cloud Sync hardening (v3.8.6) ──────────────────────────────────────────
# Shared secret used to verify the HMAC-SHA256 of the Cloud sync response body
# (the Cloud endpoint must sign each response with the same secret and place
# the hex digest in the X-Cloud-Sig header). When unset, v3.8.6 logs a warning
# but accepts unsigned responses for back-compat. v3.9 will make this required.
# OMNIROUTE_CLOUD_SYNC_SECRET=
#
# Set to "true" to allow the Cloud Sync endpoint to overwrite local OAuth
# tokens (accessToken / refreshToken / providerSpecificData). Default OFF —
# only non-credential metadata is synced. See docs/security/SOCKET_DEV_FINDINGS.md §5.
# OMNIROUTE_CLOUD_SYNC_SECRETS=false
#
# Set to "true" to reject an UNSIGNED Cloud sync response when no local secret
# is configured (#13679). Default OFF keeps v3.8.x back-compat for peers that
# have not rotated in a shared secret yet; v3.9 flips the default to enforced.
# A signature that IS present is always verified, and always rejected when
# OMNIROUTE_CLOUD_SYNC_SECRET is unset, regardless of this flag.
# OMNIROUTE_CLOUD_SYNC_ENFORCE_SIGNATURE=false
# ─── Zed import legacy compat (v3.8.6) ──────────────────────────────────────
# Set to "true" to fall back to the v3.8.5 one-step "import everything from
# the keychain" behaviour. Default OFF — the new 2-step confirmation flow
# requires `confirmedAccounts` in the request body. See SOCKET_DEV_FINDINGS.md §2.
# OMNIROUTE_ZED_IMPORT_LEGACY_ONE_STEP=false
# ─── Build profile (build-time only) ────────────────────────────────────────
# Set to "minimal" before `npm run build` to physically remove four optional
# privileged modules (MITM cert install, Zed keychain import, Cloud Sync,
# 9router installer) from the standalone bundle. The resulting artifact is
# intended to be published as `omniroute-secure`. See SECURITY.md.
# OMNIROUTE_BUILD_PROFILE=full
# Override the standalone build output directory consumed by the post-build
# colocation step. Default: the real Next.js standalone output under .build/.
# Used by: scripts/build/colocate-standalone.mjs (build tooling, not runtime).
# OMNIROUTE_STANDALONE_DIR=
# OMNIROUTE_DIST_DIR=
# Skip emitting `.tar.gz` tarballs during optional-pack staging for the Electron
# standalone tree (pack directories + optional-packs.index.json are still produced).
# Used by the desktop release workflow to trim artifact upload size.
# Default (when unset): 1 (tarballs emitted). Set to 0 to disable.
# OMNIROUTE_OPTIONAL_PACK_TAR=1
# Electron smoke harness (used by scripts/dev/smoke-electron-packaged.mjs).
# ELECTRON_SMOKE_URL=http://127.0.0.1:20128/login
# ELECTRON_SMOKE_TIMEOUT_MS=45000
# ELECTRON_SMOKE_SETTLE_MS=2000
# ELECTRON_SMOKE_APP_EXECUTABLE=
# ELECTRON_SMOKE_DATA_DIR=
# ELECTRON_SMOKE_KEEP_DATA=0
# ELECTRON_SMOKE_STREAM_LOGS=0
# #7592: second launch against the same DATA_DIR must pick the native driver.
# ELECTRON_SMOKE_COLD_RESTART=0
# Coverage capture (scripts/quality/coverage-node-register.mjs, coverage-vitest-provider.mjs):
# repository root the frozen coverage source scope is resolved against. Set by the quality
# harness only; leave unset in production deployments.
# OMNI_COVERAGE_ROOT=
# Playground Studio
# Default model used by the improve-prompt route (optional; falls back to model in request body).
PLAYGROUND_IMPROVE_PROMPT_DEFAULT_MODEL=
# Maximum number of parallel compare columns in the Compare tab.
PLAYGROUND_COMPARE_MAX_COLUMNS=4
# Memory engine (plan 21)
# MEMORY_EMBEDDING_CACHE_TTL_MS=300000 # default 5 min
# MEMORY_EMBEDDING_CACHE_MAX=1000 # default 1000 entries
# MEMORY_TRANSFORMERS_MODEL=Xenova/all-MiniLM-L6-v2
# MEMORY_STATIC_MODEL=minishlab/potion-base-8M # HF repo id (download once)
# MEMORY_STATIC_CACHE_DIR= # default <DATA_DIR>/embeddings
# MEMORY_VEC_TOP_K=20 # default top-K for vector search
# MEMORY_RRF_K=60 # RRF k constant (sqlite-vec hybrid recipe)
# HF_HUB_ENDPOINT=https://huggingface.co # override Hugging Face Hub base URL for static potion downloads
# Test/diagnostic seam (src/lib/memory/vectorStore.ts) — forces getVectorStore() to
# return null (simulates a cloud/WASM environment without sqlite-vec), degrading
# memory retrieval to FTS5 keyword search. Default off; leave unset in production.
# VECTOR_STORE_DISABLE_VEC=false
# TV6 typed memory decay (OPT-IN, default off — the sweep DELETES decayed memories)
# MEMORY_TYPED_DECAY_ENABLED=false # master switch for the destructive sweep (default off)
# MEMORY_TYPED_DECAY_EPISODIC_DAYS=30 # episodic TTL in days; 0 = episodic immune too
# MEMORY_TYPED_DECAY_ACCESS_IMMUNITY=3 # access_count >= N → immune; 0 disables access immunity
# MEMORY_TYPED_DECAY_SWEEP_INTERVAL=0 # periodic sweep interval (seconds); 0 = no periodic sweep
# ─── Memory Backend Connectors (Generic HTTP) ──────────────────────────────
# NOTION_API_KEY=
# NOTION_API_URL=
# OBSIDIAN_API_KEY=
# OBSIDIAN_API_URL=
# AgentBridge + Traffic Inspector (Group A)
# AgentBridge
AGENTBRIDGE_UPSTREAM_CA_CERT=
# Inspector
INSPECTOR_BUFFER_SIZE=1000
INSPECTOR_HTTP_PROXY_PORT=8080
INSPECTOR_HTTP_PROXY_AUTOSTART=false
INSPECTOR_SYSTEM_PROXY_GUARD_MINUTES=30
INSPECTOR_MAX_BODY_KB=1024
INSPECTOR_MASK_SECRETS=true
INSPECTOR_LLM_HOSTS_EXTRA=
INSPECTOR_INTERNAL_INGEST_TOKEN=
# Shared secret for identity-preserving internal REST hops (#9260): when an
# OmniRoute component calls another local OmniRoute route, this token (sent as
# x-omniroute-internal-service-token) marks the request as internal so the
# original caller identity is preserved. OPT-IN: unset disables the mechanism.
# Used by: src/lib/api/internalServiceAuth.ts
# OMNIROUTE_INTERNAL_SERVICE_TOKEN=
# File-based variant (secret-file pattern; wins only when the inline var is
# unset): path to a file whose trimmed content is the token.
# OMNIROUTE_INTERNAL_SERVICE_TOKEN_FILE=
# Quota Sharing (Group B — planos 16+22)
# sqlite | redis
QUOTA_STORE_DRIVER=sqlite
# QUOTA_STORE_REDIS_URL= # ex.: redis://localhost:6379 (apenas quando driver=redis)
# QUOTA_SATURATION_THRESHOLD=0.5 # 0..1; >= threshold ativa modo strict (sem empréstimo)
# QUOTA_SOFT_DEPRIORITIZE_FACTOR=0.7 # 0..1; multiplicador do score quando soft policy ativa
# STATUS_SOFT_DEPRIORITIZE_FACTOR=0.5 # 0..1; multiplicador do score p/ provider esgotado (credits_exhausted/rate_limited) quando preflight cutoff OFF (#4540)
# QUOTA_CONSUMPTION_RETENTION_DAYS=14 # GC de buckets quota_consumption.updated_at antigos
# QUOTA_PREFLIGHT_CUTOFF_ENABLED=false # opt-in (default OFF): hard quota cutoff drops low-quota candidates before auto-routing scoring
# ─── Auto-Combo tier filter (#4517) ───────────────────────────────────────
# When an `auto/<category>:free` (or any `:<tier>`) request matches NO connected
# candidates, OmniRoute returns an EMPTY pool by default — so `:free` really means
# "free tier only" and a paid model is never picked just because no free provider is
# connected. Set this to `true`/`1` to restore the legacy behavior of falling back to
# the full (unfiltered) pool with a warning. Source: open-sse/services/autoCombo/virtualFactory.ts
# OMNIROUTE_AUTO_FREE_FALLBACK_TO_FULL_POOL=false
# ─── Auto-Combo chaos panel (broadcast variant) ────────────────────────────
# Tuning for the `auto/*:chaos` variant, which fans a single request out to a
# panel of provider-diverse models. Panel size is clamped to 1..10 (default 5);
# min-panel and the panel hard-timeout fall back to the engine defaults when
# unset. Source: open-sse/services/autoCombo/virtualFactory.ts
# OMNIROUTE_CHAOS_MAX_PANEL=5
# OMNIROUTE_CHAOS_MIN_PANEL=
# OMNIROUTE_CHAOS_PANEL_TIMEOUT_MS=
# ─── OpenCode config regeneration (scripts/ad-hoc/regen-opencode-config.ts) ───
# Base URL of the OmniRoute instance to query for /v1/models when regenerating
# an opencode.json with accurate limit.context values. Used by:
# scripts/ad-hoc/regen-opencode-config.ts. Default: http://localhost:20128
# OMNIROUTE_URL=
# API key to authenticate against the OmniRoute /v1/models endpoint. Falls back
# to OPENCODE_API_KEY when unset. Used by: scripts/ad-hoc/regen-opencode-config.ts.
# OMNIROUTE_KEY=
# OpenCode-style API key (sk-...) for the regenerated opencode.json. Used by:
# scripts/ad-hoc/regen-opencode-config.ts. Falls back to OMNIROUTE_KEY.
# OPENCODE_API_KEY=
# ─── Bifrost Go sidecar (PR-4 in #3932) ──────────────────────────────────────
# Master kill switch for the bifrost sidecar proxy. When set to 0, the
# /api/v1/relay/chat/completions/bifrost route returns 503 with the
# X-Bifrost-Killswitch header and the operator is bounced to the TS path.
# Use this to disable the sidecar without redeploying (e.g. during a
# tier-1 router incident or a key rotation). Default: 1 (sidecar active).
# BIFROST_ENABLED=1
# When BIFROST_BASE_URL is set, /api/v1/relay/chat/completions/bifrost routes
# traffic to the Go gateway instead of the TS relay handler, removing TS from
# the hot path. Auth/rate-limit/injection-guard stay in the route (security not
# duplicated). Falls back to TS path via X-Bifrost-Fallback header on
# timeout/failure. See bin/omniroute for the local-redis companion.
# BIFROST_BASE_URL=
# Port the supervised Bifrost embedded service binds to (127.0.0.1:<port>), read by
# src/lib/services/bootstrap.ts when OmniRoute manages the Bifrost sidecar lifecycle.
# Default: 8080.
# BIFROST_PORT=8080
# Port the supervised sing-box embedded service binds to (127.0.0.1:<port>).
# Default: 20140.
# SINGBOX_PORT=20140
# API key for the Bifrost gateway (sent as Authorization: Bearer ...). If
# unset, the route expects the request to carry a valid OmniRoute API key;
# this key is for gateway-side auth only.
# BIFROST_API_KEY=
# When true, the Bifrost sidecar route streams responses back via SSE through
# the gateway rather than the TS streaming executor. Default: true (when
# BIFROST_BASE_URL is set).
# BIFROST_STREAMING_ENABLED=
# Per-request timeout when proxying to the Bifrost gateway. Default: 30000 (30s).
# BIFROST_TIMEOUT_MS=
# Alias for BIFROST_API_KEY (used by scripts that read the env via
# OMNIROUTE_*). BIFROST_API_KEY takes precedence when both are set.
# OMNIROUTE_BIFROST_KEY=
# Relay backend selection for the OpenAI-compatible relay endpoint:
# ts | bifrost | auto. "ts" (default when Bifrost is not configured) uses the
# TypeScript relay; "auto" selects Bifrost when BIFROST_BASE_URL is set (and
# BIFROST_ENABLED != 0) and falls back to TS if the sidecar is unreachable;
# "bifrost" forces Bifrost (strict — no TS fallback). Auth, rate limits,
# injection guard and model allowlists always run in the Next route first.
# RELAY_ROUTING_BACKEND is an accepted alias. Responses carry X-Routing-Backend
# and X-Routing-Fallback.
# OMNIROUTE_RELAY_BACKEND=
# RELAY_ROUTING_BACKEND=
# Cooldown (ms) after a Bifrost sidecar hop fails in "auto" mode before the relay
# re-attempts the sidecar; it goes straight to the TS path while the cooldown lasts.
# 0 disables. Default 5000. Only applies when OMNIROUTE_RELAY_BACKEND=auto.
# OMNIROUTE_BIFROST_FAILURE_COOLDOWN_MS=
# Opt-in native HTTPS/TLS for `omniroute serve` (equivalent to --tls-cert /
# --tls-key). Provide BOTH a PEM certificate and its private key and the
# standalone server terminates TLS on the same listener (wss:// works
# unchanged). With neither set the server stays plain HTTP; providing only one
# (or an unreadable path) logs a warning and stays HTTP (never half-enables).
# OMNIROUTE_TLS_CERT=
# OMNIROUTE_TLS_KEY=
# ─── 1-click local service launchers (PR-3 in #3932) ────────────────────────
# Master switch for /api/local/* routes. When unset or "0", all /api/local/*
# routes return 503 in production. Default: 0. Must be "1" in non-loopback
# deploys to enable the Redis launcher and similar 1-click local service
# starters. Belt-and-suspenders with the isLocalOnlyPath() route-guard
# classification (LOCAL_ONLY_API_PREFIXES in src/server/authz/routeGuard.ts).
# OMNIROUTE_LOCAL_ENDPOINTS_ENABLED=
# Bearer token for /api/local/* callers that aren't on loopback (e.g. the
# desktop app). When set, requests from non-loopback IPs must carry
# Authorization: Bearer <token>. Required when
# OMNIROUTE_LOCAL_ENDPOINTS_ENABLED=1 in non-loopback deployments. Default:
# unset (loopback-only).
# OMNIROUTE_LOCAL_ENDPOINTS_TOKEN=
# Container name for the 1-click Redis launcher (`omniroute redis up`).
# Default: omniroute-redis. Used by bin/cli/commands/redis.mjs and the
# RedisLauncherPanel.
# OMNIROUTE_REDIS_CONTAINER_NAME=
# Host port for the 1-click Redis launcher. Default: 6379. Bump if the host
# already binds 6379. The container's internal port stays 6379.
# OMNIROUTE_REDIS_HOST_PORT=
# Host interface the 1-click Redis launcher publishes on. Default: 127.0.0.1
# (loopback only). The launcher starts Redis WITHOUT a password, so binding
# 0.0.0.0 hands every host on your LAN an unauthenticated Redis — only widen
# this if you also set a password on the instance yourself.
# OMNIROUTE_REDIS_BIND_HOST=
# Redis image used by the 1-click Redis launcher. Default: redis:7-alpine.
# Override to redis:8-alpine or a private registry mirror as needed.
# OMNIROUTE_REDIS_IMAGE=
# ── Cluster Profile: Qdrant Vector Memory (opt-in via `docker compose --profile memory up`) ──
# Qdrant is an OPTIONAL sidecar for deployments that need cosine-distance vector
# search at >1M embeddings. The default vector store is sqlite-vec
# (src/lib/memory/vectorStore.ts:108); flip this profile on only if you hit the
# sqlite-vec ceiling or want persistent cross-replica vector state. See
# docs/architecture/cluster-decisions.md § "Qdrant (memory profile)".
# QDRANT_HOST=qdrant
# QDRANT_PORT=6333
# QDRANT_GRPC_PORT=6334
# QDRANT_API_KEY=
# QDRANT_COLLECTION=omniroute-memory
# QDRANT_EMBEDDING_MODEL=text-embedding-3-small
# QDRANT_VECTOR_SIZE=1536
# QDRANT_HNSW_EF_CONSTRUCT=128
# ── Cluster Profile: Bifrost Tier-1 Router (opt-in via `docker compose --profile bifrost up`) ──
# Bifrost is an OPTIONAL Go-based Tier-1 router that handles the upstream-provider
# multiplexing layer. Default: OmniRoute's open-sse/executors/bifrost.ts in-process
# executor handles routing directly. Flip this profile on only if you want the
# gateway as a separate sidecar (helps in 3+ replica deployments where you want
# provider rotation centralised). See docs/architecture/cluster-decisions.md §
# "Bifrost (bifrost profile)".
# Set OMNIROUTE_RELAY_BACKEND=auto to use this sidecar when healthy, or
# OMNIROUTE_RELAY_BACKEND=bifrost to require it without TS fallback.
# BIFROST_BASE_URL=http://bifrost:8080
# BIFROST_API_KEY=
# BIFROST_STREAMING_ENABLED=true
# BIFROST_TIMEOUT_MS=30000
# ─────────────────────────────────────────────────────────────────────────────
# Account rotation config (operator-managed; consumed by open-sse/services/rotationConfig.ts)
# Lets a supervising front-end mirror its rotation rules onto the backend's account-fallback
# engine. All optional; defaults preserve the historical behavior.
# ─────────────────────────────────────────────────────────────────────────────
# OMNIROUTE_ROTATION_ENABLED=true
# OMNIROUTE_ROTATION_RATE_LIMIT_RESET_SECONDS=0
# OMNIROUTE_ROTATION_DISABLE_TAG_WITHOUT_RESET=true
# OMNIROUTE_ROTATE_ON_429=true
# OMNIROUTE_ROTATE_429_THRESHOLD=1
# OMNIROUTE_ROTATE_429_WINDOW_SECONDS=120
# OMNIROUTE_ROTATE_ON_500=true
# OMNIROUTE_ROTATE_500_THRESHOLD=1
# OMNIROUTE_ROTATE_500_WINDOW_SECONDS=120
# OMNIROUTE_ROTATE_ON_502=true
# OMNIROUTE_ROTATE_502_THRESHOLD=1
# OMNIROUTE_ROTATE_502_WINDOW_SECONDS=120
# OMNIROUTE_ROTATE_ON_400=false
# OMNIROUTE_ROTATE_400_THRESHOLD=1
# OMNIROUTE_ROTATE_400_WINDOW_SECONDS=120
# ─────────────────────────────────────────────────────────────────────────────
# PromptQL playground provider (Unofficial/Experimental — src/shared/constants/providers/web-cookie.ts)
# Reverse-engineered GraphQL session bridge for prompt.ql.app. All optional —
# defaults point at the public playground endpoints; override only for a
# self-hosted/alternate PromptQL deployment.
# Used by: open-sse/executors/promptql.ts, open-sse/services/usage/promptql.ts
# ─────────────────────────────────────────────────────────────────────────────
# PROMPTQL_GRAPHQL_ENDPOINT=https://data.prompt.ql.app/promptql/playground-v2-hge/v1/graphql
# PROMPTQL_CREDITS_ENDPOINT=https://data.pro.ql.app/v1/graphql
# PROMPTQL_TOKEN_REFRESH_URL=https://auth.pro.ql.app/ddn/project/token
# PROMPTQL_POLL_TIMEOUT_MS=180000
# ─────────────────────────────────────────────────────────────────────────────
# Kilo Code usage quotas (src/shared/constants/providers/kilocode.ts)
# Personal USD balance and Kilo Pass usage lookup. Optional — the default
# points at the public Kilo API; override only for a relay/test fixture.
# Authentication uses the connection's existing OAuth access token.
# Used by: open-sse/services/usage/kilocode.ts
# ─────────────────────────────────────────────────────────────────────────────
# KILO_API_URL=https://api.kilo.ai
# ─────────────────────────────────────────────────────────────────────────────
# MegaBrain plan usage limits (open-sse/config/providers/registry/megabrain)
# The plan's 5-hour session and weekly limits for Provider Limits. Optional —
# the default points at the public MegaBrain API; override only for a
# relay/test fixture. Authentication uses the connection's OAuth token or
# its mb-v1 API key.
# Used by: open-sse/services/usage/megabrain.ts
# ─────────────────────────────────────────────────────────────────────────────
# MEGABRAIN_API_URL=https://api.getmegabrain.com
# ─────────────────────────────────────────────────────────────────────────────
# HyperAgent web provider (Unofficial/Experimental — src/shared/constants/providers/web-cookie.ts)
# Reverse-engineered session bridge for hyperagent.com. Optional — defaults
# point at the public billing/usage endpoint; override only for a
# self-hosted/alternate HyperAgent deployment.
# Used by: open-sse/services/usage/hyperagent.ts
# ─────────────────────────────────────────────────────────────────────────────
# HYPERAGENT_USAGE_URL=https://hyperagent.com/api/settings/billing/usage
# ─────────────────────────────────────────────────────────────────────────────
# ChatGPT Web clean-room turn budgets (milliseconds)
# Used by: open-sse/utils/chatgptWebExecutorAdapter.ts
# Tool-emulated turns share the 180000ms ceiling with ordinary text turns, because
# a live Free-account text turn already takes 49-86s; lower it to return control to
# the client sooner, at the risk of cutting off a slow tool envelope. Values below
# 1000ms are ignored.
# ─────────────────────────────────────────────────────────────────────────────
# CHATGPT_WEB_TOOL_TURN_TIMEOUT_MS=180000
# CHATGPT_WEB_TURN_TIMEOUT_MS=180000
# ─────────────────────────────────────────────────────────────────────────────
# ChatGPT Web clean-room browser (open-sse/utils/chatgptWebExecutorAdapter.ts)
# Headless is the default: servers have no display, and a headed Chromium either
# fails to start or puts a window on the operator's desktop. Set to 0 only for
# accounts whose first-party challenge rejects headless mode.
# CHATGPT_WEB_HEADLESS=1
# Ceiling for launching the browser and warming up chatgpt.com. Keeps a dead
# browser or session from consuming the 600s request-queue execution deadline.
# CHATGPT_WEB_BROWSER_ACQUIRE_TIMEOUT_MS=45000
# ─────────────────────────────────────────────────────────────────────────────
# ChatGPT Web (Codex) headless browser and outbound tool tunnel
# Used by: open-sse/executors/chatgpt-web-codex.ts
# Connection values entered in the dashboard override these global defaults.
# ─────────────────────────────────────────────────────────────────────────────
# CHATGPT_WEB_CODEX_CHROME_PATH=/usr/bin/chromium
# CHROME_PATH=/usr/bin/chromium
# CHATGPT_WEB_CODEX_CDP_URL=http://chatgpt-web-codex-browser:9223
# CHATGPT_WEB_CODEX_USE_CDP_PROFILE: set to 1 (with a CDP endpoint configured) to reuse the
# externally managed, signed-in browser profile's existing ChatGPT page instead of creating an
# isolated context per turn; also caps concurrent ChatGPT tabs at 1. Off by default.
# See docs/guides/CHATGPT-WEB-PERSISTENT-CDP.md.
# Used by: open-sse/vendor/codex-chatgpt-web/persistent-cdp-context.ts
# Default: unset (off)
# CHATGPT_WEB_CODEX_USE_CDP_PROFILE=1
# CDP_PROXY_TOKEN: shared secret for docker/chatgpt-web-codex-browser/cdp-proxy.mjs
# (#13679, #14486). The proxy FAILS CLOSED — every request must present it as an
# `X-Omni-Cdp-Token` header. Leave empty in docker compose: the browser container
# then auto-generates a secret into a shared volume (CDP_PROXY_TOKEN_FILE) that the
# app reads. Set it explicitly only to pin your own value (`openssl rand -hex 32`).
# CDP_PROXY_TOKEN=
# CHATGPT_WEB_CODEX_TUNNEL_ID=tunnel_0123456789abcdef0123456789abcdef
# CHATGPT_WEB_CODEX_RUNTIME_KEY=
# CHATGPT_WEB_CODEX_CONNECTOR_NAME=OmniRoute Codex v2
# CODEX_CHATGPT_WEB_HOME=/var/lib/omniroute/chatgpt-web-codex
# CODEX_CHATGPT_WEB_BROWSER_DIAGNOSTICS=0
# CODEX_CHATGPT_WEB_LAUNCHER=/absolute/path/to/codex-chatgpt-web
# CODEX_CHATGPT_WEB_BUN=/absolute/path/to/bun
# CODEX_WEB_GPT_BUN=/absolute/path/to/bun
# ─────────────────────────────────────────────────────────────────────────────
# Browser-login VNC sessions (optional — src/lib/vncSession/manifest.ts)
# Containerized Chromium+VNC used for interactive browser-login credential
# capture via /api/vnc-session. All optional — defaults target the bundled
# `omniroute-vnc-chromium:local` image; override only for a custom image, ports,
# or lifecycle tuning.
# ─────────────────────────────────────────────────────────────────────────────
# OMNIROUTE_VNC_IMAGE=omniroute-vnc-chromium:local
# OMNIROUTE_DOCKER_BIN=docker
# OMNIROUTE_VNC_CONTAINER_VNC_PORT=3000
# OMNIROUTE_VNC_CONTAINER_CDP_PORT=9223
# OMNIROUTE_VNC_CONTAINER_PROFILE_DIR=/config
# OMNIROUTE_VNC_PROFILE_DIR=
# OMNIROUTE_VNC_IDLE_MS=600000
# OMNIROUTE_VNC_MAX_MS=1800000
# OMNIROUTE_VNC_MAX_SESSIONS=4
# OMNIROUTE_VNC_READY_MS=45000
# OMNIROUTE_VNC_HARVEST_MS=20000
# OMNIROUTE_VNC_CHROMIUM_ARGS=--remote-debugging-port=9222 --no-first-run --no-default-browser-check
# OMNIROUTE_VNC_NETWORK=omniroute-vnc-browser-login
# ─────────────────────────────────────────────────────────────────────────────
# Data-dir alias (optional — open-sse/services/notionThreadSessions.ts)
# Legacy fallback for DATA_DIR, checked only after DATA_DIR and
# OMNIROUTE_DATA_DIR are both unset. Locates the Notion web-thread session cache.
# ─────────────────────────────────────────────────────────────────────────────
# VIBEPROXY_DATA_DIR=
# ── Internal service auth (management-plane service-to-service calls) ─────────
# Inline token for internal service authentication; prefer the _FILE variant in
# containerized deployments so the secret never lands in the environment table.
# OMNIROUTE_INTERNAL_SERVICE_TOKEN=
# Path to a file containing the internal service token (overrides the inline var).
# OMNIROUTE_INTERNAL_SERVICE_TOKEN_FILE=
# ═══════════════════════════════════════════════════════════════════════════════
# 26. RADAR FEED (SELF-HOSTING)
# ═══════════════════════════════════════════════════════════════════════════════
# Optional add-on (feature flag RADAR_ENABLED, default off — see feature flag
# settings, not an env var) that overlays a signed, freshly-curated free-model
# catalog on top of the release baseline. The first four variables below are
# optional overrides for a self-hosted/forked feed or supporter-key flow. The
# fifth is an optional, default-free link to the owner's private operations panel. Used by:
# src/lib/radar/sync.ts, src/lib/radar/pinnedKeys.ts, src/lib/radar/links.ts.
# Base URL of the Radar feed service. Overrides the built-in default so forks
# and self-hosters can point at their own signed feed.
# RADAR_FEED_URL=https://radar.omniroute.online
# Ed25519 public key (base64-DER SPKI or PEM) used to verify the feed
# signature, replacing the pinned default key. Required when self-hosting a
# feed signed with a different key pair.
# RADAR_FEED_PUBKEY=
# URL the dashboard's "I'm a contributor" button opens (GitHub OAuth
# supporter-key claim flow). No pricing/value lives in this repo — only the
# link.
# RADAR_CONTRIBUTOR_CLAIM_URL=https://radar.omniroute.online/auth/github
# URL the dashboard's "Support the project" button opens (payment/plans
# page). No pricing/value lives in this repo — only the link.
# RADAR_SUPPORTER_PLANS_URL=https://radar.omniroute.online/planos
# Owner-only link to the private Radar operations panel. There is deliberately
# no default: when unset or invalid, no "Radar Admin" navigation item exists.
# Use HTTPS for a tunnel/tailnet URL, or HTTP only for an SSH loopback forward.
# RADAR_ADMIN_URL=http://127.0.0.1:9351
# ═══════════════════════════════════════════════════════════════════════════════
# 27. RELEASE v3.8.50 ADDITIONS
# ═══════════════════════════════════════════════════════════════════════════════
# Heavy chat admission queue wait before returning retryable 503. Set 0 for the
# legacy immediate rejection. Used by: src/shared/middleware/chatBodyAdmission.ts.
# Documented once above, under the chat admission block — this entry said 5000
# while the code said 2000, so it is a pointer now rather than a second answer.
# Default: RATE_LIMIT_MAX_WAIT_MS (see that var elsewhere in this file for its
# current value)
# Timeout for /api/jobs/:id/run-now while it waits for an in-flight run.
# Used by: src/app/api/jobs/[id]/run-now/route.ts. Default: 30000 (30 seconds)
# OMNIROUTE_RUNNOW_TIMEOUT_MS=30000
# Adobe Firefly browser renewal and durable session cache (enabled by default).
# Used by: open-sse/services/adobeFireflySession.ts.
# ADOBE_FIREFLY_BROWSER_REFRESH=1
# ADOBE_FIREFLY_SESSION_DISK=1
# Minimum spacing between submissions and the extra pause after every third success.
# ADOBE_FIREFLY_MIN_SUBMIT_GAP_MS=12000
# ADOBE_FIREFLY_BATCH_EXTRA_GAP_MS=15000
# Browser used by Adobe Firefly renewal. True headless is debug-only: Adobe
# colligo normally rejects risk tokens minted without a headed browser.
# Used by: open-sse/services/adobeFireflyBrowserLogin.ts
# ADOBE_FIREFLY_CHROME_HEADLESS=0
# The CDP-attached Chrome runtime (adobeFireflyChromeRuntime.ts) was removed in
# #9255 along with its knobs — ADOBE_FIREFLY_CHROME_CDP_PORT, _VISIBLE, _HEADED,
# _PING, _FORCE_RESTART, ADOBE_FIREFLY_LOGIN_WAIT_MS and _FORTER_WAIT_MS are read
# nowhere and have no effect.
# Telegram Mini App bridge. The update endpoint remains disabled while the bot
# token is unset. Used by: src/lib/telegram/* and src/app/api/telegram/update/route.ts.
# TELEGRAM_BOT_TOKEN=
# Shared secret registered with setWebhook and echoed back by Telegram as the
# X-Telegram-Bot-Api-Secret-Token header. REQUIRED for the webhook path: without
# it the webhook is rejected with 503, because an unauthenticated update lets any
# caller mint API keys and spend upstream quota. The Mini App path does not use it.
# TELEGRAM_WEBHOOK_SECRET=
# TELEGRAM_DEFAULT_MODEL=auto/chat
# TELEGRAM_BOT_API_BASE=https://api.telegram.org
# TELEGRAM_WEBHOOK_TIMEOUT_MS=60000
# Who may use the bot. A bot is reachable by anyone who finds its @username, and a
# valid Telegram signature proves origin, not authorization: with the allowlist off
# (the default) every Telegram user is served and gets a minted API key that spends
# upstream quota. Set to true to serve only the users in TELEGRAM_ALLOWED_USER_IDS
# (others: Mini App 403, webhook message dropped). Recommended for any public bot.
# TELEGRAM_USER_ALLOWLIST_ENABLED=false
# Comma-separated numeric Telegram user ids served when the allowlist is enabled.
# Entries that are not plain positive integers (e.g. @usernames, 0-prefixed ids)
# are ignored and reported once at startup. Empty with the allowlist enabled =
# nobody is served.
# TELEGRAM_ALLOWED_USER_IDS=
# ── OmniConductor bridge (Conductor PRD RF1) ──────────────────────────────────
# Mirrors the OmniConductor hub's tasks into the local A2A TaskManager via SSE.
# Opt-in: the bridge only starts when CONDUCTOR_HUB_URL is set.
# Token: emit a `spokesperson`-kind credential on the hub (POST /v1/peers, admin) —
# server-side only, never exposed to the browser.
# Used by: src/lib/conductor/boot.ts, src/lib/conductor/bridge.ts
# CONDUCTOR_HUB_URL=http://127.0.0.1:7910
# CONDUCTOR_HUB_TOKEN=
# Inbound A2A→hub delegation credential (falls back to CONDUCTOR_HUB_TOKEN when unset).
# Used by: src/lib/conductor/hubProxy.ts
# CONDUCTOR_ORCHESTRATOR_TOKEN=
# Spokesperson (Faro) base URL for the dashboard chat proxy (/api/conductor/ask).
# Used by: src/lib/conductor/faroProxy.ts
# CONDUCTOR_SPOKESPERSON_URL=http://127.0.0.1:7920
# ═══════════════════════════════════════════════════════════════════════════════
# QUOTA-AWARE PROVIDER SCHEDULING (opt-in, Phase 2)
# ═══════════════════════════════════════════════════════════════════════════════
# When enabled, routing skips connections whose configured per-window token
# budget (rateLimitOverrides.tpm) cannot afford the estimated request cost —
# before dispatching — instead of waiting for a 429. Fail-open: connections
# without a configured budget are always considered affordable. Requires the
# provider_quota_state table (migration 148).
# OMNIROUTE_QUOTA_AWARE_ROUTING=0
# Feedback calibration of the context-guard token estimator (#14931): learns the
# provider's real prompt_tokens / estimate ratio per (provider, model, tools) and
# scales later estimates (clamped 0.15–2.0, in-memory only). On by default; set
# off, 0 or false to disable. Used by: open-sse/services/estimatorCalibration.ts.
# OMNIROUTE_ESTIMATOR_CALIBRATION=on
# Grok subscription images: registers the xai-oauth (xao) and grok-cli image routes.
# Dashboard feature flag of the same name; a DB override wins over this value.
# Default off. Used by: open-sse/config/imageRegistry.ts.
# GROK_SUBSCRIPTION_IMAGES_ENABLED=false
# ─── LOCAL CORPUS (opt-in document index) ───
# Size of the in-memory LRU index cache for the local document corpus used by
# corpus-aware retrieval. Higher values keep more index entries hot.
# Used by: src/lib/localCorpus/configured.ts
# OMNIROUTE_CORPUS_CACHE_SIZE=5
# Service-worker cache-busting id for the PWA shell (#11779). NEXT_PUBLIC_SW_BUILD_ID is
# derived at build time from OMNIROUTE_SW_BUILD_ID, then SOURCE_VERSION (set by some PaaS
# builders), then the git SHA — override only when the build cannot see git. Used by:
# next.config.mjs, scripts/build/assembleStandalone.mjs, src/shared/components/PwaRegister.tsx.
#OMNIROUTE_SW_BUILD_ID=2026-08-28T12-00-00
#SOURCE_VERSION=abcdef0123456789
#NEXT_PUBLIC_SW_BUILD_ID=abcdef0123456789
# Optional runtime controls introduced after the previous environment snapshot.
# Enable the xAI subscription image routes (off by default).
# Used by: open-sse/config/imageRegistry.ts.
# GROK_SUBSCRIPTION_IMAGES_ENABLED=0
# Per-key API-key cooldown when a 429 response has no Retry-After hint (ms).
# Used by: open-sse/services/apiKeyRotator.ts. Default: 60000.
# OMNIROUTE_API_KEY_COOLDOWN_MS=60000
# Disable in-memory estimator calibration with off, 0, or false. Enabled by default.
# Used by: open-sse/services/estimatorCalibration.ts.
# OMNIROUTE_ESTIMATOR_CALIBRATION=on
# Render free-tier keep-alive: the standalone launcher pings its own public URL so the service is
# not spun down. Inert unless SELF_PING_URL or Render's RENDER_EXTERNAL_URL is set. See ENVIRONMENT.md.
# Used by: scripts/build/runtime-env.mjs.
# RENDER_EXTERNAL_URL is set by Render itself; do not set it elsewhere.
# RENDER_EXTERNAL_URL=
# SELF_PING_ENABLED=true
# SELF_PING_URL=
# SELF_PING_PATH=/api/monitoring/health
# SELF_PING_INTERVAL_SECONDS=180
# Internal standalone-server signal override. Normally managed by the launcher.
# Used by: scripts/dev/standalone-server-ws.mjs.
# NEXT_MANUAL_SIG_HANDLE=1
# Path of the private CI UI Kit clone the vendored-snapshot gate diffs packages/ui-kit against.
# Defaults to _references/cheaper-inference-ui-kit (main checkout); the gate skips with a
# warning when the clone is absent (public CI / forks). KEA-7886.
# Used by: scripts/check/check-ui-kit-snapshot.mjs.
# UI_KIT_CLONE=_references/cheaper-inference-ui-kit
# Opt-in model-sync phase timings; disabled unless exactly 1.
OMNIROUTE_MODEL_SYNC_TIMINGS=0
# Opt-in sanitized per-physical-send Antigravity phase timings (no request bodies).
OMNIROUTE_ANTIGRAVITY_TIMING_TELEMETRY=false
# Optional local OpenCode media-analysis tool settings (scripts/cli/omniroute-media-mcp.mjs).
# These configure the local tool process, not the hosted gateway.
# OMNIROUTE_MEDIA_CONFIG=
# OMNIROUTE_MEDIA_PROVIDER=omniroute
# OMNIROUTE_MEDIA_MODEL=auto
# OMNIROUTE_MEDIA_API_KEY=
# ── Vision image normalization (opt-in) ──
# Normalizes every inline (base64) image in chat request bodies before
# dispatch: RGB conversion (alpha flattened onto white), long edge <= 4096px,
# total pixels <= ~4MP, re-encoded as baseline JPEG/PNG — the comfort zone of
# Qwen2-VL-style vision pipelines, which reject oversized/exotic images with
# 400 parse errors or zero-output hangs. Remote http(s) URLs are not
# downloaded; a missing sharp binary or undecodable image passes through
# untouched (fail-open). Unset (default) = off, zero change.
# Used by: open-sse/utils/visionImageNormalization.ts + src/sse/handlers/chat.ts
# OMNIROUTE_IMAGE_NORMALIZATION=1
# Session stickiness/TTL in minutes for in-memory sessions (default 15). Long
# agent sessions benefit from a higher TTL; unset/blank/invalid keeps 15.
# Used by: open-sse/services/sessionManager.ts.
# OMNIROUTE_SESSION_TTL_MIN=15