703 KiB
title, version, lastUpdated
| title | version | lastUpdated |
|---|---|---|
| Environment Variables Reference | 3.8.52 | 2026-10-11 |
Environment Variables Reference
Complete reference for every environment variable recognized by OmniRoute. For a quick-start template, see
.env.example.
Important
Every variable documented here must also appear in
.env.example, and every variable in.env.examplemust appear here.npm run check:env-doc-syncenforces this on commit and in CI. To omit a variable on purpose, add it to the allowlist insidescripts/check/check-env-doc-sync.mjs.
Table of Contents
- 1. Required Secrets
- 2. Storage & Database
- 3. Network & Ports
- 4. Security & Authentication
- 5. Input Sanitization & PII Protection
- 6. Tool & Routing Policies
- 7. URLs & Cloud Sync
- 8. Outbound Proxy
- 9. CLI Tool Integration
- 10. Internal Agent & MCP Integrations
- 11. OAuth Provider Credentials
- 12. Provider User-Agent Overrides
- 13. CLI Fingerprint Compatibility
- 14. API Key Providers
- 15. Timeout Settings
- 16. Logging
- 17. Memory Optimization
- 18. Pricing Sync
- 19. Model Sync (Dev)
- 20. Provider-Specific Settings
- 21. Proxy Health
- 22. Debugging
- 23. GitHub Integration
- 24. Skills Sandbox (v3.8.0+)
- 27. Radar Feed (Self-Hosting)
- Deployment Scenarios
- Audit: Removed / Dead Variables
1. Required Secrets
Unset secrets marked Yes are auto-generated on the first run (JWT_SECRET, API_KEY_SECRET) and persisted to server.env in the data directory — set them explicitly when that directory is ephemeral. The exception is OMNIROUTE_WS_BRIDGE_SECRET: it is not persisted to server.env — the server entrypoints mint an ephemeral per-boot value only the in-process bridge can use, so external bridge clients need it set explicitly.
| Variable | Required | Default | Source File | Description |
|---|---|---|---|---|
JWT_SECRET |
Yes | (none) | src/lib/auth |
Signs/verifies all dashboard session cookies (JWT). Generate with openssl rand -base64 48. |
API_KEY_SECRET |
Yes | (none) | src/lib/db/apiKeys.ts |
AES encryption key for API key values at rest in SQLite. Generate with openssl rand -hex 32. |
INITIAL_PASSWORD |
No | (unset) | src/lib/auth/managementPassword.ts |
Sets the dashboard password at startup while none is saved yet; ignored once a password is saved. npm and source installs copy .env.example to .env, so they start with its publicly known placeholder CHANGEME: replace it before first boot, or set INITIAL_PASSWORD= (empty) in that .env to create the password in the onboarding wizard on first visit, as an unset value (the Docker image's default) does. Change a saved password in Dashboard → Settings → Security, or run omniroute reset-password (node bin/reset-password.mjs in a source checkout) with DATA_DIR set to the server's data directory. |
OMNIROUTE_WS_BRIDGE_SECRET |
Yes (production) | (unset) | src/app/api/internal/codex-responses-ws/route.ts |
Shared secret for the internal Codex Responses WebSocket bridge. Authenticates bridge requests between the Electron/browser WS relay and OmniRoute. ⚠️ REQUIRED in production — when unset, all WS bridge requests are rejected. Generate with openssl rand -base64 32. |
OMNIROUTE_SW_BUILD_ID |
No | (git SHA) | next.config.mjs, scripts/build/assembleStandalone.mjs |
Explicit service-worker cache-busting id for the PWA shell (#11779); first in the resolution chain. |
SOURCE_VERSION |
No | (unset) | next.config.mjs, scripts/build/assembleStandalone.mjs |
Second in the chain — set by PaaS builders (e.g. Heroku-style) as the deployed commit. |
NEXT_PUBLIC_SW_BUILD_ID |
No | (derived) | src/shared/components/PwaRegister.tsx |
Build-time public value the client uses to register /sw.js?v=…; derived from the two above, then the git SHA. |
OMNIROUTE_PEER_STAMP_TOKEN |
No (auto) | (auto per boot) | src/server/authz/policies/management.ts |
Per-process secret proving the trusted peer-IP stamp came from OmniRoute's own HTTP server (scripts/dev/peer-stamp.mjs). The authz middleware trusts request locality (loopback/LAN gating of LOCAL_ONLY routes) only when the stamp carries this token. Auto-generated each boot — leave unset; only pin it for multi-process setups that must share the stamp. |
OMNIROUTE_TRUSTED_PROXIES |
No | (unset) | scripts/dev/peer-stamp.mjs |
Comma-separated IPs or CIDR ranges of reverse proxies 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 for a proxy on any other public address; otherwise that proxy's own address is what the filter judges. The relay's per-client throttle (/api/v1/relay/chat/completions) keys on the same resolved client address, never on forwarding headers alone. |
Generation Commands
# Generate all four secrets at once:
echo "JWT_SECRET=$(openssl rand -base64 48)"
echo "API_KEY_SECRET=$(openssl rand -hex 32)"
echo "INITIAL_PASSWORD=$(openssl rand -base64 16)"
echo "OMNIROUTE_WS_BRIDGE_SECRET=$(openssl rand -base64 32)"
Caution
Never commit
.envfiles with real secrets to version control. The.gitignorealready excludes.env, but verify before pushing.
2. Storage & Database
OmniRoute uses SQLite (via better-sqlite3) for all persistence. These variables control data location, encryption, and lifecycle.
| Variable | Default | Source File | Description |
|---|---|---|---|
DATA_DIR |
~/.omniroute/ |
src/lib/db/core.ts |
Root directory for SQLite DB, backups, and data files. Override for Docker volumes or custom paths. |
OMNIROUTE_ALLOW_DEFAULT_DATA_DIR |
(unset) | src/lib/dataPaths.ts |
Escape hatch for the test/eval DATA_DIR guard (#10428). Tests and Node eval/print probes (-e/--eval/-p/--print, including --eval=/--print= forms) with no DATA_DIR are redirected to a throwaway temp dir so they cannot open the operator's real database; set to 1 to opt back in to the real directory. |
OMNIROUTE_BUILD_SHA |
(unset) | src/lib/monitoring/buildSha.ts |
Git SHA of the running artifact. Stamped by npm run build:release; injectable in containers that ship without the dist/BUILD_SHA sentinel. Surfaced as system.buildSha on /api/monitoring/health. |
OMNIROUTE_RELEASE_REF |
origin/main |
scripts/build/buildProvenance.ts |
Ref the pack-artifact provenance gate checks the build SHA against (#10427). |
OMNIROUTE_ALLOW_CANARY_BUILD |
(unset) | scripts/build/buildProvenance.ts |
Set to 1 to allow packing a build whose SHA is not on the release line, recording it as a deliberate canary instead of failing the gate (#10427). |
OMNIROUTE_SMOKE_API_KEY |
(unset) | scripts/ops/deploy-canary.mjs |
API key for the canary-deploy smoke probe, sent as Authorization: Bearer on /v1/chat/completions. Only used by the deploy script (#10429), never by the server. Not related to the OMNIROUTE_SMOKE_* variables of the opt-in CLI smoke harness (RUN_CLI_SMOKE=1, OMNIROUTE_SMOKE_BASE_URL/MODEL/API_KEY_ENV/TARGETS/TIMEOUT_MS in tests/integration/upstream-cli-smoke.int.test.ts) — see CLI Integrations → Real smoke sweep. |
OMNIROUTE_BUILDING |
(unset) | src/lib/buildPhase.ts |
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 for the running server. |
OMNIROUTE_SKIP_NATIVE_DEP_CHECK |
0 |
scripts/check/check-native-deps.mjs |
Set to 1 to skip the optional native-dependency prebuild check for exotic vendored trees. This does not make a missing dependency buildable; use only when native dependencies are supplied out of band. |
OMNIROUTE_DATA_DIR |
(unset) | open-sse/executors/promptql/threadSticky.ts |
Fallback alias for DATA_DIR, checked only when DATA_DIR is unset. Used to locate the PromptQL executor's on-disk thread-sticky session cache (<dir>/promptql-thread-sessions.json); if neither var is set, the cache stays in-memory only (not persisted across restarts). |
OMNIROUTE_PLUGINS_DIR |
(unset) | src/lib/plugins/scanner.ts |
Directory the runtime plugin scanner reads — and the root the plugin manager installs into — overriding the home-derived default (#11827). Point it at the bind-mounted plugin tree in Docker/K8s instead of moving HOME just to relocate the scan path (HOME governs every other home-relative behaviour too). Unset = ~/.omniroute/plugins, or /tmp/.omniroute/plugins when the process exports no home at all — the silent non-discovery this variable removes. The resolved directory is logged once at startup as scanner.dir_resolved with the input that won. Server-side only: CLI command plugins keep their own OMNIROUTE_PLUGIN_PATH (section 9). |
STORAGE_ENCRYPTION_KEY |
(empty = disabled) | src/lib/db/encryption.ts |
AES key for full SQLite database encryption at rest. Generate with openssl rand -hex 32. |
STORAGE_ENCRYPTION_KEY_VERSION |
v1 |
scripts/build/bootstrap-env.mjs, electron/main.js |
Version label for the encryption key. Increment when performing key rotation to support decryption of old backups. |
DISABLE_SQLITE_AUTO_BACKUP |
false |
src/lib/db/backup.ts |
When true, skips routine/pre-write SQLite file backups (models.dev pricing save/clear, settings writes). Manual and pre-restore backups still run. It does not disable the migration runner's mandatory durable safety snapshot or mass-migration guard for an existing persistent DB. Non-manual backups are throttled to at most once per 60 minutes. Dashboard Settings → Storage can disable routine auto-backup independently. |
OMNIROUTE_SQLITE_SLOW_MS |
(unset/off) | src/lib/db/adapters/slowDiagnostics.ts |
Milliseconds; values below 1 or non-numeric stay off; warns at most once per 10s; log line has driver, operation, and elapsedMs only. |
OMNIROUTE_SQLITE_OPTIMIZE_ENABLED |
true |
src/lib/db/sqlitePlannerStats.ts |
Background planner statistics maintenance, independent of retention cleanup: first enabled cleanup pass (normally 30s after startup, after migrations) runs PRAGMA optimize=0x10002; subsequent passes every 6h run PRAGMA optimize (or PRAGMA optimize=0x00002 for unlimited analysis). false or 0 disables all maintenance (case-insensitive, whitespace trimmed). Memory databases and read-only backup paths are unaffected. Failures are logged, not thrown. |
OMNIROUTE_SQLITE_ANALYSIS_LIMIT |
400 |
src/lib/db/sqlitePlannerStats.ts |
Sets PRAGMA analysis_limit before optimization. Decimal integers are clamped to [0, 100000]; malformed/empty values default to 400. 0 requests unlimited, exact analysis of tables selected by optimization; the periodic pass clears SQLite's optimize sampling-cap bit to honor this. No standalone SQL analysis statement is run. |
OMNIROUTE_CRYPT_KEY |
(unset) | src/lib/db/encryption.ts |
Legacy alias for STORAGE_ENCRYPTION_KEY. Accepted as a fallback when the primary variable is absent. |
OMNIROUTE_API_KEY_BASE64 |
(unset) | src/lib/db/encryption.ts |
Legacy alias (Base64-encoded form) accepted as a fallback. Decoded automatically before use. |
OMNIROUTE_DB_HEALTHCHECK_INTERVAL_MS |
(unset) | src/lib/db/core.ts |
Override the periodic SQLite healthcheck interval (ms). When unset, defaults are derived from NODE_ENV. |
OMNIROUTE_WAL_TRUNCATE_INTERVAL_MS |
(removed) | src/lib/db/walMaintenance.ts |
Removed. A periodic live wal_checkpoint(TRUNCATE) can invalidate the shared wal-index mapping and crash the process with SIGBUS (#13973), so the scheduler no longer exists. The variable is inert: a positive value logs a one-time deprecation warning, while 0 or unset stays silent. The WAL is maintained by PASSIVE checkpoints (below) and truncated by the shutdown checkpoint. |
OMNIROUTE_WAL_PASSIVE_INTERVAL_MS |
300000 (5m) |
src/lib/db/walMaintenance.ts |
Override the frequent wal_checkpoint(PASSIVE) interval (ms). Keeps pending WAL frames small so checkpoints stay fast and the WAL file stays bounded between shutdown truncations. 0 disables. |
OMNIROUTE_WAL_GUARD_MAX_MB |
256 |
src/lib/db/walMaintenance.ts |
When a PASSIVE tick finds the WAL file above this size, run wal_checkpoint(RESTART) so the WAL starts over without rewriting the mapped wal-index. Live truncate-mode checkpoints were removed (see the OMNIROUTE_WAL_TRUNCATE_INTERVAL_MS row). |
OMNIROUTE_PRESSURE_SELF_RESTART |
false |
open-sse/utils/resourcePressure.ts |
Set to 1/true/yes/on to exit the process after critical resource pressure is sustained for OMNIROUTE_PRESSURE_SELF_RESTART_AFTER_MS, letting a supervisor (systemd Restart=always, Docker restart policy) bring back a clean process instead of serving 503s indefinitely. |
OMNIROUTE_PRESSURE_SELF_RESTART_AFTER_MS |
120000 (2m) |
open-sse/utils/resourcePressure.ts |
How long critical pressure must persist before the self-restart exit fires. |
OMNIROUTE_PRESSURE_PSI_DISABLED |
false |
open-sse/utils/resourcePressurePolicy.ts |
Set to 1/true/yes/on to ignore host-wide /proc/pressure/memory (psi_some / psi_full) when a noisy neighbor trips 503s while this process is fine (#13124). Cgroup and V8 heap guards stay on. PSI also stops counting as kernel throttle proof for cgroup_high: a cgroup total above memory.high then turns critical only on a memory.events high/max increase. Without memory.events the raw ratio is kept. |
OMNIROUTE_SQLJS_WASM_PATH |
(auto-detect) | src/lib/db/adapters/sqljsAdapter.ts |
Explicit path (absolute or relative to cwd) to sql-wasm.wasm when using the sql.js WASM fallback adapter. Auto-detected via package dependencies and candidate layouts when unset. |
OMNIROUTE_BATCH_RETENTION_DAYS |
30 |
src/lib/db/cleanup.ts |
Days a terminal (completed/failed/cancelled/expired) Batch API job's checkpoints, referenced input/output/error files, and row are kept by the automatic cleanup sweep before deletion. Only takes effect once BATCH_AND_FILE_AUTO_CLEANUP_ENABLED is turned on; matches OpenAI's own Batch API output retention window. Does not affect the operator-triggered DELETE /api/v1/batches/delete-completed route, which stays unconditional (no age filter) by design. |
BATCH_AND_FILE_AUTO_CLEANUP_ENABLED |
false |
src/lib/db/cleanup.ts |
When true, let the automatic cleanup sweep delete terminal Batch API jobs (and their checkpoints) past OMNIROUTE_BATCH_RETENTION_DAYS, and clear the BLOB content of uploaded files past their own expires_at. Off by default: every existing install keeps this data exactly as before until an operator opts in. Also a dashboard-editable feature flag — see docs/reference/FEATURE_FLAGS.md → Runtime. |
OMNIROUTE_SKIP_DB_HEALTHCHECK |
0 |
src/lib/db/core.ts, src/lib/db/healthCheck.ts |
Set to 1 to skip the DB healthcheck entirely on startup. Useful for short-lived tasks and integration tests. |
OMNIROUTE_FORCE_DB_HEALTHCHECK |
0 |
src/lib/db/core.ts |
Set to 1 to force the DB healthcheck loop on, even when it would normally be skipped (e.g., short-lived tasks). |
OMNIROUTE_SKIP_POSTINSTALL |
0 |
scripts/postinstall.mjs |
Set to 1 to skip the native-runtime warm-up during npm install. Useful in CI/headless installs where sqlite is already built. |
OMNIROUTE_MIGRATIONS_DIR |
(auto-detect) | src/lib/db/migrationRunner.ts |
Override the directory that the migration runner scans. Useful when shipping bundled migrations in custom builds. |
OMNIROUTE_EXTRA_MIGRATIONS_DIRS |
(unset) | src/lib/db/migrationRunner/extraDirs.ts |
Additional migration directories as namespace=dir entries separated by the platform path delimiter (e.g. ee=/opt/app/enterprise/db/migrations). Files found there are recorded as <namespace>-<number>, so a distribution shipping its own migrations never collides with the upstream numeric slots. A malformed entry, an invalid namespace or a missing directory throws at startup instead of silently skipping the schema. |
OMNIROUTE_MAX_PENDING_MIGRATIONS |
50 |
src/lib/db/migrationRunner.ts |
Mass-pending-migrations safety threshold (#3416). Startup aborts if more than this many migrations are pending on an existing DB (guards against a wiped tracking table). Raise it to restore an older backup; set to 0 to disable the check. |
OMNIROUTE_INSTALL_UPGRADE_WORKDIR |
(<repo>/.install-upgrade) |
scripts/check/check-install-upgrade.mjs |
Working directory for the check:install-upgrade release gate. It needs roughly 12 GB (two ~3 GB install trees plus the tarball), so it must not run on a small tmpfs — on the self-hosted runner /tmp is a 12 GB RAM-backed tmpfs and the gate exhausted it, truncating the package. |
OMNIROUTE_SPEND_FLUSH_INTERVAL_MS |
(default in code) | src/lib/spend/batchWriter.ts |
Flush interval (ms) for the batched spend/cost writer. Lower values reduce write coalescing; higher values reduce DB contention. |
OMNIROUTE_SPEND_MAX_BUFFER_SIZE |
(default in code) | src/lib/spend/batchWriter.ts |
Max buffered spend entries before a forced flush. Raise on high-QPS deployments; lower when bounded memory matters more. |
OMNIROUTE_PROXY_FETCH_DEBUG |
(unset) | open-sse/utils/proxyFetch.ts |
Set to "true" to emit [ProxyFetch] debug logs on the Vercel relay path. Off by default to avoid leaking routing hints. |
OMNIROUTE_PROXY_CORE_BINARY_PATH |
(unset) | src/lib/proxySubscription/coreConfig/sync.ts |
Absolute path of the local proxy core binary (a file named sing-box / mihomo) that checks a generated core configuration before it replaces the adopted file. Unset writes <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. |
OMNIROUTE_PROXY_CORE_RELOAD_COMMAND |
(unset) | src/lib/proxySubscription/coreConfig/reload.ts |
How the local proxy core reloads after a verified config replacement: a JSON argument array run without a shell, or exactly external when an outside observer applies the file. Never stored in the database nor exposed via the API. |
PROXY_LOG_INCLUDE_IPS |
false |
src/lib/proxyLogger.ts |
Set to "true" or "1" to include client/egress IPs and the account prefix in the verbose [ProxyEgress] process-log line. Kept OFF by default so the process log does not leak IPs or the account prefix. |
OMNIROUTE_DEBUG |
(unset) | bin/cli/commands/quota.mjs |
Set to 1 to print per-request timing diagnostics ([omniroute] GET <path> completed in Nms) from the CLI quota commands to stderr. |
OMNIROUTE_HEALTHCHECK_PATH |
(auto) | scripts/dev/healthcheck.mjs |
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. |
OMNIROUTE_DEBUG_COMPLETION |
(unset) | bin/cli/commands/completion.mjs |
Set to any non-empty value to emit [omniroute completion] diagnostics from the CLI shell-completion cache paths (read/refresh/write). Off by default — those caches fail silently so a missing/corrupt cache never breaks tab-completion. |
OMNIROUTE_DEBUG_STACK |
(unset) | bin/cli/utils/formatCliError.mjs |
Set to 1 to print the full stack trace when a CLI command fails. Off by default — the CLI prints only the error message. CLI-only; HTTP error responses never include stacks. |
BATCH_RETRY_DURATION_MS |
86400000 (24h) |
open-sse/services/batchProcessor.ts |
Maximum retry window for individual batch items (ms). Items exceeding this duration are marked failed. |
BATCH_BACKOFF_BASE_MS |
5000 |
open-sse/services/batchProcessor.ts |
Base delay (ms) for exponential backoff on batch item retries. |
BATCH_BACKOFF_MAX_MS |
3600000 (1h) |
open-sse/services/batchProcessor.ts |
Cap (ms) for exponential backoff between batch item retries. |
BATCH_MAX_CONCURRENT |
1 |
open-sse/services/batchProcessor.ts |
Maximum number of batches processed concurrently. Raise to increase throughput; keep low to avoid rate-limit storms. |
Important
Before changing an existing persistent database, the migration runner publishes a complete, content-addressed snapshot under
DATA_DIR/db_backups/. Publication requires a filesystem that supports same-filesystem, no-overwrite hard links plus durable file sync. POSIX hosts also require directory sync; on Windows, Node may reject directory handles, so OmniRoute flushes the published file and treats directory-entry sync as best effort. If the mountedDATA_DIRcannot provide those guarantees, startup fails closed before applying a migration. MoveDATA_DIRto a volume with those primitives; do not useDISABLE_SQLITE_AUTO_BACKUPto bypass migration safety.
Scenarios
| Scenario | Configuration |
|---|---|
| Local development | Leave all defaults. DB lives at ~/.omniroute/omniroute.db. |
| Docker | DATA_DIR=/data + mount a volume at /data. |
| Encrypted at rest | Set STORAGE_ENCRYPTION_KEY + keep backups of the key! Losing it = losing data. |
| CI/Testing | DATA_DIR=/tmp/omniroute-test — ephemeral, no encryption needed. |
3. Network & Ports
| Variable | Default | Source File | Description |
|---|---|---|---|
PORT |
20128 |
src/lib/runtime/ports.ts |
Primary port for both Dashboard UI and API endpoints (single-port mode). |
OMNIROUTE_BASE_PATH |
(empty = root) | next.config.mjs, scripts/docker/ensure-docker-base-path.mjs |
URL subpath for serving OmniRoute behind a reverse proxy (sets Next.js basePath; auth redirects are basePath-aware). E.g. /omniroute. In Docker the value is baked during docker build (ARG OMNIROUTE_BASE_PATH); pre-built root images can apply a different runtime value once at container start before Next.js boots. Set NEXT_PUBLIC_BASE_URL to the public origin including the same subpath. |
NEXT_PUBLIC_OMNIROUTE_BASE_PATH |
(empty = root) | src/shared/hooks/useDisplayBaseUrl.ts |
Browser-visible mirror of OMNIROUTE_BASE_PATH, inlined at build time so the dashboard endpoint display shows https://host/omniroute/v1 instead of https://host/v1. Falls back to OMNIROUTE_BASE_PATH when unset. Rebuild after changing (Next basePath is build-time). |
DASHBOARD_ALLOW_EMBED |
(unset = never framable) | next.config.mjs, scripts/build/dashboardEmbed.mjs |
Opt-in iframe embedding of the HTML pages. Unset, every route ships frame-ancestors 'none' + X-Frame-Options: DENY. Set to vscode to serve the pages (dashboard, login, docs, landing) with frame-ancestors 'self' vscode-webview: and no X-Frame-Options, so the VS Code Simple Browser can render them (OmniCopilot's dashboardOpen: "editor" mode). The API surface (/api, /v1, /v1beta, /a2a, /healthz, root-level aliases) keeps the strict headers either way. Only vscode is recognised — 1/true do not enable it. Build-time: rebuild after changing (docker build --build-arg DASHBOARD_ALLOW_EMBED=vscode for images; setting it on a prebuilt install has no effect). |
API_PORT |
(unset) | src/lib/runtime/ports.ts |
When set, serves the /v1/* proxy API (plus Gemini-native /v1beta/*) on this separate port. |
API_HOST |
0.0.0.0 |
src/lib/runtime/ports.ts |
Bind address for the API port. |
DASHBOARD_PORT |
(unset) | src/lib/runtime/ports.ts |
When set, serves the Dashboard UI on this separate port. |
OMNI_MAX_CONCURRENT_CONNECTIONS |
0 (disabled) |
src/sse/utils/backpressure.ts |
Caps concurrent in-flight chat connections; requests over the cap get 503 with Retry-After. Positive integer enables the guard; unset/0 disables it. |
OMNIROUTE_INSTANCE_ID |
(unset) | src/shared/resilience/peerRouting.ts |
Stable, unique ID for this gateway when chaining OmniRoute instances. Enables inbound peer-loop checks. Allowed characters: letters, digits, ., _, :, and -; maximum 64 characters. |
OMNIROUTE_PEER_URLS |
(unset) | src/shared/resilience/peerRouting.ts, open-sse/executors/base.ts |
Comma-separated OmniRoute base URLs that may receive X-OmniRoute-Peer-Trace. Only explicitly allowlisted upstream URLs receive peer metadata; all other providers are untouched. |
OMNIROUTE_PEER_MAX_HOPS |
4 |
src/shared/resilience/peerRouting.ts |
Maximum number of previously visited OmniRoute instances accepted on a chained request (1-32). Repeated instances or an exhausted budget return HTTP 508 Loop Detected. |
PROD_DASHBOARD_PORT |
20130 |
docker-compose.prod.yml |
Host-side published port for the Dashboard in Docker production mode. |
PROD_API_PORT |
20131 |
docker-compose.prod.yml |
Host-side published port for the API in Docker production mode. |
OMNIROUTE_PORT |
(unset) | src/lib/runtime/ports.ts |
Takes precedence over PORT when running inside Electron or other wrappers. |
LIVE_WS_PORT |
20129 |
src/server/ws/liveServer.ts |
Port for the real-time WebSocket live monitoring server. |
LIVE_WS_HOST |
127.0.0.1 |
src/server/ws/liveServer.ts |
Bind address for the live WebSocket server. Set to 0.0.0.0 to expose on LAN (also configure LIVE_WS_ALLOWED_ORIGINS). Connections authenticate with the dashboard session cookie or a Bearer API key that holds a management scope (manage/admin). |
LIVE_WS_ALLOWED_ORIGINS |
(unset) | src/server/ws/liveServer.ts |
Comma-separated extra origins allowed to open a live WebSocket. Loopback dashboard origins are already permitted by default. |
LIVE_WS_ALLOWED_HOSTS |
(unset) | src/server/ws/liveServerAllowList.ts |
Comma-separated extra hostnames allowed for live WebSocket origins. Unlike LIVE_WS_ALLOWED_ORIGINS (full origin URLs), matches only the host portion — useful for LAN/Tailscale setups. |
NEXT_PUBLIC_LIVE_WS_PUBLIC_URL |
(unset) | src/hooks/useLiveDashboard.ts |
Public URL for the live dashboard WebSocket (browser-side). Set when fronting the WS server with a reverse proxy or Cloudflare Tunnel (e.g. wss://ws.my-ai.com/live-ws); the browser connects there instead of ws://hostname:20132. The pathname portion is also used as the WebSocket upgrade path (default: /live-ws). |
OMNIROUTE_ENABLE_LIVE_WS |
true |
src/server/ws/liveServer.ts and scripts/start-ws-server.mjs |
Set to 0 or false to disable the real-time WebSocket server (enabled by default, loopback-bound). CI/harness toggle that disables the standalone live WebSocket helper script. |
RELAY_IP_PER_MINUTE |
30 |
src/app/api/v1/relay/chat/completions/route.ts |
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). |
NODE_ENV |
production |
Next.js core | Controls logging verbosity, caching, error detail exposure, and Next.js optimizations. |
OMNIROUTE_USE_TURBOPACK |
(unset) (automatic build selection) | scripts/build/build-next-isolated.mjs |
For npm run build, unset or empty selects webpack when the effective memory limit (physical RAM or lower cgroup/process quota) is at most 16 GiB or cannot be safely determined; above 16 GiB, Turbopack is selected. Explicit 0 forces webpack; explicit 1 and other nonempty nonzero values force Turbopack. An empty environment value forwarded by Compose does not force Turbopack. This threshold comes from a 15.6 GiB build-memory regression (#18184); host builds with 24/32 GiB were not benchmarked. Production webpack automatically skips its persistent cache by default (see OMNIROUTE_WEBPACK_BUILD_CACHE below; #18141) and builds with substantially less peak RSS than the current Turbopack path. Development retains its existing bundler behavior. Docker builds already default to 0 (webpack); use --build-arg OMNIROUTE_USE_TURBOPACK=1 to opt in. See docs/guides/DOCKER_GUIDE.md. |
OMNIROUTE_WEBPACK_BUILD_CACHE |
(unset) | next.config.mjs |
Webpack production builds (OMNIROUTE_USE_TURBOPACK=0) skip the webpack persistent filesystem cache unless this is 1. Writing that cache adds about 2.5 GB of peak build memory at a 6144 MB heap cap, and clean builds never read it back. Set to 1 to keep .build/next/cache/webpack for faster repeat builds on a machine with RAM to spare; Docker builds take it as --build-arg OMNIROUTE_WEBPACK_BUILD_CACHE=1 (Dockerfile and Dockerfile.bun builder stages). |
OMNIROUTE_SKIP_DB_HEALTHCHECK |
(unset) | src/lib/db/core.ts / src/lib/db/healthCheck.ts |
Set to 1 to skip the SQLite integrity health check on startup. Useful for faster boot on large databases. |
NOTIFY_SOCKET |
(unset) | systemd (sd_notify protocol) | Set by systemd when the process runs under a service unit with sd_notify integration; OmniRoute reads it (see OMNIROUTE_DISABLE_SD_NOTIFY) to send READY/WATCHDOG notifications. Never set by the user. |
OMNIROUTE_DISABLE_SD_NOTIFY |
(unset) | scripts/dev/systemd-notify.mjs |
Set to 1 to disable systemd sd_notify (Type=notify / WatchdogSec=) even when running under a systemd unit. The notifier is a no-op outside systemd regardless. |
CREDENTIAL_HEALTH_CHECK_INTERVAL |
3600000 |
open-sse/config/constants.ts / src/lib/credentialHealth/scheduler.ts |
Interval (ms) for the background credential health check scheduler. Minimum: 10000 (10s). |
CREDENTIAL_HEALTH_CACHE_TTL |
300000 |
open-sse/config/constants.ts / src/lib/credentialHealth/cache.ts |
TTL (ms) for cached credential health status. |
OMNIROUTE_DISABLE_CREDENTIAL_HEALTH_CHECK |
false |
src/lib/credentialHealth/scheduler.ts |
Set to 1 or true to disable background periodic testing of provider connections. Search providers (SEARCH_VALIDATOR_CONFIGS in src/lib/providers/validation/searchProviders.ts, e.g. tavily-search) are always excluded from the sweep — their "validation" is a real billed upstream query, so they are never health-checked on a timer (#9970). |
DEEP_HEALTH_CHECK_ENABLED |
0 |
src/app/api/monitoring/health/route.ts |
Set to 1 to allow an authenticated caller to request /api/monitoring/health?deep=1, which samples the completions surface once per TTL. Anonymous callers never trigger the probe. |
OMNIROUTE_EVENT_LOOP_STALL_THRESHOLD_MS |
5000 |
src/lib/healthzLag.ts |
Stall threshold (ms) for the boot event-loop recorder: a freeze longer than this logs one event loop stalled line at resume with memory and in-flight counts, and bumps the eventLoopStall counter/maximum on /api/monitoring/health. Set to 0 to disable; an unreadable or negative value falls back to 5000. |
HOST |
0.0.0.0 |
scripts/dev/run-next.mjs |
Bind address for the Next.js dev/start server. Overrides the default 0.0.0.0 when set. |
HOSTNAME |
127.0.0.1 |
scripts/dev/run-next-playwright.mjs |
Bind address used by the Playwright runner when launching Next.js. Defaults to 127.0.0.1 for hermetic tests. Do not use for omniroute serve — use OMNIROUTE_SERVER_HOST instead (POSIX shells auto-set HOSTNAME to the machine name; .env cannot override it). |
OMNIROUTE_SERVER_HOST |
0.0.0.0 |
bin/cli/commands/serve.mjs |
Bind address for omniroute serve. Avoids collision with the POSIX shell HOSTNAME variable (always set to the machine name by bash/zsh). Falls back to 0.0.0.0 when unset. (#6194) |
Port Modes
┌─────────────────────────── Single Port (default) ──────────────────────────┐
│ PORT=20128 │
│ → Dashboard: http://localhost:20128 │
│ → API: http://localhost:20128/v1/chat/completions │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────── Split Ports ─────────────────────────────────────┐
│ DASHBOARD_PORT=20128 │
│ API_PORT=20129 │
│ API_HOST=0.0.0.0 │
│ → Dashboard: http://localhost:20128 │
│ → API: http://0.0.0.0:20129/v1/chat/completions │
│ Use case: Expose API to LAN while restricting Dashboard to localhost. │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────── Docker Production ──────────────────────────────┐
│ PROD_DASHBOARD_PORT=443 PROD_API_PORT=8443 │
│ → Maps container ports to host ports in docker-compose.prod.yml. │
└─────────────────────────────────────────────────────────────────────────────┘
4. Security & Authentication
| Variable | Default | Source File | Description |
|---|---|---|---|
MACHINE_ID_SALT |
endpoint-proxy-salt |
src/lib/auth |
Salt combined with hardware identifiers for machine fingerprinting. Change per-deployment for isolation. |
OMNIROUTE_CLI_SALT |
(unset = random per-install salt persisted at <DATA_DIR>/cli-token-salt.json) |
src/lib/machineToken.ts |
HMAC salt for deriving the local CLI auth token. Setting this value rotates all CLI tokens on the machine and always takes priority over the persisted salt. See docs/security/CLI_TOKEN.md. |
AUTH_COOKIE_SECURE |
false |
src/lib/auth |
Sets the Secure flag on session cookies. Must be true when running behind HTTPS. |
REQUIRE_API_KEY |
false |
API middleware | When true, all /v1/* proxy requests must include a valid API key. This flag does not gate GET /v1/models, which follows the dashboard login posture (requireAuthForModels) instead — so a 401 from /v1/models does NOT mean inference is protected. See docs/security/INFERENCE_AUTH_POSTURE.md (#13695). Accepts true, 1 or yes, ignoring case and surrounding spaces; any other value (including on) is off. |
ALLOW_API_KEY_REVEAL |
false |
src/shared/constants/featureFlagDefinitions.ts |
Allows revealing full API key values in the Dashboard UI. Configurable from Dashboard Feature Flags; security risk on shared instances. |
NO_LOG_API_KEY_IDS |
(empty) | src/lib/compliance/index.ts |
Comma-separated API key IDs that bypass request logging (GDPR compliance). |
DEFAULT_RATE_LIMIT_PER_DAY |
(unset = unlimited) | src/shared/utils/apiKeyPolicy.ts |
Fallback per-day request budget applied to API keys whose rate_limits column is null. Unset or empty: no implicit cap (#2289, #11017). 0 is the same (unlimited). Positive integer N enables N/day, 5N/week, 20N/month. Malformed non-empty values fall back to the legacy 1000/day, 5000/week, 20000/month windows. |
MAX_BODY_SIZE_BYTES |
10485760 (10 MB) |
src/shared/middleware/bodySizeGuard.ts |
Default for the visible maxBodySizeMb setting; a saved setting takes precedence. /api/v1/chat/completions and /api/v1/responses keep a 50 MB default until a limit is saved; a saved limit then replaces it, up or down, for the header guard and for actual-byte chat admission alike. |
OMNIROUTE_CHAT_LARGE_BODY_BYTES |
262144 (256 KB) |
src/shared/middleware/chatBodyAdmission.ts |
Actual request bodies at or above this threshold take the atomic process-local heavyweight admission lease before JSON parsing (BYTE path, including POST /v1/responses). Same #10437 healthy-headroom escape as structure-heavy; still bounded by OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES / #10110 so #7849 does not return. |
OMNIROUTE_CHAT_HARD_MAX_BODY_BYTES |
52428800 (50 MB) |
src/shared/middleware/chatBodyAdmission.ts |
Chat-route hard cap enforced against bytes read during bounded ingestion, including requests with missing, invalid, or dishonest Content-Length; excess receives 413. A saved maxBodySizeMb replaces the 50 MB default; when this variable is set, it also caps that saved value. |
OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT |
(unset — no request-count cap) | src/shared/middleware/chatBodyAdmission.ts |
#503-fanout: this legacy request-COUNT cap now binds only when explicitly set. Left unset (the default), heavyweight chat admission is instead gated by OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES — an auto-derived BYTE budget sized from the process's real memory ceiling in one process (one V8 heap). Two overlapping ~750k-token /v1/responses abort ~12 Gi heaps (#7849) — a memory-budget warning, not a hard product max of 2. A healthy process (heap below the shed ratio) MAY admit more concurrent long /v1/responses via OMNIROUTE_CHAT_ADMISSION_HEALTHY_HEADROOM. Tens of long SSE clients (40–50) is heap + OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES / #10110, not “max 2”. Blindly raising this to “use the host” reintroduces #7849. Multiply heaps with N independent DATA_DIRs (#11024); never replicas>1 on one SQLite file. |
OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES |
(auto-derived) | src/shared/middleware/admissionBudget.ts |
#503-fanout: override for the auto-derived ingest byte budget (25% of the tighter V8/cgroup memory ceiling divided by 8x transient amplification). Derived and explicit values clamp to 8 MiB–2 GiB. A body larger than the effective budget fails immediately with 413 body_exceeds_budget; contention between individually serviceable bodies remains retryable 503. 40–50 concurrent long SSE clients is this budget + heap, not a hard “max 2”. Read chatAdmission.maxInflightBytes / budgetSource / pressureSeverity at /api/monitoring/health before tuning. |
OMNIROUTE_CHAT_ADMISSION_HEAP_SHED_RATIO |
0.75 |
src/shared/middleware/chatBodyAdmission.ts |
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 the retryable 503 when the heap is ALSO at or above this ratio; on a healthy heap it is admitted via healthy-headroom instead. |
OMNIROUTE_CHAT_ADMISSION_HEALTHY_HEADROOM |
OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT (default 1) |
src/shared/middleware/chatBodyAdmission.ts |
Bounded extra capacity for the healthy-heap fast path (#10437) on both STRUCTURE and BYTE (admitChatRequest, including bodies ≥ OMNIROUTE_CHAT_LARGE_BODY_BYTES). Without this bound, every busy-but-healthy-heap request bypassed admission with no ceiling. Once this many concurrent leases are active through the healthy-heap path, further busy requests fall through to the SAME bounded-wait/shed path used under real heap pressure. 0 disables the bypass entirely. |
OMNIROUTE_CHAT_HEAVY_MESSAGE_COUNT |
200 |
src/shared/middleware/chatBodyAdmission.ts |
Message count that classifies a chat request as heavyweight even when its body is below the byte threshold. |
OMNIROUTE_CHAT_HEAVY_TOOL_COUNT |
64 |
src/shared/middleware/chatBodyAdmission.ts |
Tool count that classifies a chat request as heavyweight even when its body is below the byte threshold. |
OMNIROUTE_CHAT_HEAVY_ESTIMATED_TOKENS |
32000 |
src/shared/middleware/chatBodyAdmission.ts |
Conservative string-size token estimate that classifies a request as heavyweight; this is an admission-cost proxy, not provider billing tokenization. |
OMNIROUTE_CHAT_HARD_MAX_MESSAGES |
0 (disabled) |
src/shared/middleware/chatBodyAdmission.ts |
Optional opt-in chat history cap. Disabled by default: a message count is deployment policy, not a universal property of a request, and capping here rejects conversations with a terminal 413 before the compression pipeline can make them servable. Heap growth is bounded by OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT and the heap-pressure shed. Set a positive value on memory-constrained deployments that need a hard ceiling; excess then receives structured compact-required 413. |
OMNIROUTE_MAX_NONSTREAMING_RESPONSE_BYTES |
67108864 (64 MB) |
open-sse/handlers/chatCore/nonStreamingResponseBody.ts |
Hard cap for a non-streaming upstream response buffered fully into memory. Past this the upstream reader is cancelled and the request fails fast instead of growing an unbounded string until the heap is exhausted. |
OMNIROUTE_FORWARDING_HEADER_BUDGET_BYTES |
768 |
open-sse/handlers/chatCore/responseHeaders.ts |
Max wire bytes forwarded from upstream response headers. When the budget is exceeded, lower-priority headers (e.g., custom x-codex-*, x-oai-request-id) are dropped to stay within common reverse-proxy header limits. Set higher to forward more upstream metadata at the cost of larger response header size. |
OMNIROUTE_QUOTA_RECOVERY_MAX_PER_KEY |
64 |
src/lib/quota/quotaSessionRecovery.ts |
Most quota-recovery tickets (pending, running or awaiting confirmation) one API key may hold. Once a key is at the limit, a new turn gets the original quota error instead of a 202 ticket; retrying an already parked turn still returns its ticket. Invalid or non-positive values use the default. |
CORS_ORIGIN |
(unset) | src/server/cors/origins.ts |
Legacy single-origin CORS allowlist. Prefer CORS_ALLOWED_ORIGINS for new deployments. CORS is only for cross-origin browser API clients; authenticated dashboard writes use same-origin requests plus session-bound CSRF protection instead. |
CORS_ALLOWED_ORIGINS |
(unset) | src/server/cors/origins.ts |
Comma-separated CORS allowlist. No wildcard is sent unless CORS_ALLOW_ALL=true is explicitly configured. |
CORS_ALLOW_ALL |
false |
src/server/cors/origins.ts |
Development-only escape hatch to echo any browser Origin. Do not enable on shared or production deployments. |
OUTBOUND_SSRF_GUARD_ENABLED |
true |
src/shared/network/outboundUrlGuardPolicy.ts |
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 below. |
OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS |
false |
src/shared/network/outboundUrlGuardPolicy.ts |
Turns off the outbound URL guard's host checks, cloud-metadata block included (all of 169.254.0.0/16, metadata.google.internal), 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. Chat requests dispatched through BaseExecutor.execute() keep their cloud-metadata check. Local providers work with the defaults: OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS (default true) already allows local and LAN URLs on the validation, discovery, and provider-node paths; the proxy-fallback test and private webhook targets consult only this flag and block local/LAN hosts while it is off. Overrides OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS=false. A value saved from the dashboard toggle takes precedence over this variable. |
OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS |
true |
src/shared/network/outboundUrlGuardPolicy.ts |
Allow provider URLs on local/private addresses (127.0.0.1, localhost, LAN, private ranges) for provider validation, model discovery, chat, and the other provider-adjacent outbound paths the guard mode governs. Default true (local-first): the guard then blocks cloud-metadata endpoints — all of 169.254.0.0/16 plus the known metadata hostnames (metadata.google.internal, metadata.goog, Alibaba/Azure/Oracle IMDS, fd00:ec2::254). Set false for public-only mode, which blocks private and loopback hosts too. The guard checks the hostname or IP literal as written, before any DNS lookup; in public-only mode the safe-fetch wrapper additionally resolves the hostname and refuses any private answer. OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS=true turns these checks off on the paths its row lists. Built-in local providers, such as LM Studio, Ollama, vLLM, Llamafile, and Triton, skip all host checks for key validation and chat. A value saved from the dashboard toggle takes precedence over this variable. (#5066) |
AUDIO_REMOTE_PROVIDER_NODES |
false |
src/app/api/v1/_shared/audioProviderNodes.ts |
Let the /v1/audio/* routes (transcriptions, speech, translations) use an OpenAI-compatible provider node hosted outside localhost. Off by default — routing audio to a remote host changes egress identity and must be an explicit operator decision. Loopback/private nodes (localhost, 127.0.0.1, 172.16-31.x) are always allowed and unaffected. (#3963) |
RERANK_REMOTE_PROVIDER_NODES |
false |
src/app/api/v1/_shared/rerankProviderNodes.ts |
Let POST /v1/rerank (and the memory engine's loopback rerank step) use an OpenAI-compatible provider node hosted outside localhost — a LAN box or Tailscale peer running TEI, Infinity, vLLM, etc. Off by default — routing to a remote host changes egress identity and must be an explicit operator decision. Loopback nodes (localhost, 127.0.0.1, 172.16-31.x) are always allowed and unaffected. A remote node's base URL must also pass the provider outbound URL policy (OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS / OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS). |
OMNIROUTE_LOCAL_PROVIDER_NODE_HOSTS |
(empty) | src/shared/network/localNodeHosts.ts |
Hostnames (comma or whitespace separated) that provider-node routing treats as local — typically the Docker/Compose service name of a reranker, TEI or audio sidecar on OmniRoute's own Docker network (http://reranker:8080/v1), so the node does not need a hard-coded container IP. Listed hosts are eligible for /v1/rerank, /v1/audio/* and the local health check without turning on RERANK_REMOTE_PROVIDER_NODES / 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. (#14635) |
OMNIROUTE_OIDC_DISABLE_PASSWORD_LOGIN |
false |
src/app/api/auth/login/route.ts |
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 of the same key takes precedence. (#10889) |
OIDC_DISABLE_PASSWORD_LOGIN |
false |
src/app/api/auth/login/route.ts |
Bare alias of OMNIROUTE_OIDC_DISABLE_PASSWORD_LOGIN (#10889). |
OMNIROUTE_DISABLE_MFA |
false |
src/server/auth/dashboardMfa.ts |
Lost-device recovery for the opt-in dashboard TOTP two-factor login. When true, the second factor is skipped only for a sign-in from the host itself (loopback peer and loopback Host); remote sign-ins and POST /api/cli/connect from other origins still require the code. Sign in locally, disable two-factor under Settings → Security (the code may be left blank while this is set, so a factor that no longer verifies can be removed; the password is still required), then unset it. TOTP covers password login and omniroute connect only — OIDC/SSO sign-in relies on the identity provider's own second factor. See AUTHZ_GUIDE. |
Hardening Checklist
# Production security minimum:
AUTH_COOKIE_SECURE=true # Requires HTTPS
REQUIRE_API_KEY=true # Authenticate all proxy calls
ALLOW_API_KEY_REVEAL=false # Never expose keys in UI
CORS_ALLOWED_ORIGINS=https://your.domain.com
MAX_BODY_SIZE_BYTES=5242880 # 5 MB limit
5. Input Sanitization & PII Protection
OmniRoute provides a two-layer defense: request-side injection scanning and response-side PII stripping.
⚠️ Limitations: These guardrails are best-effort heuristic detections, not a complete prompt-injection firewall or PII DLP system. They can produce false positives (benign persona/RPG prompts flagged) and false negatives (leetspeak, spacing, non-English patterns). They are not sufficient alone for compliance. Tune modes and test against your traffic before relying on them.
Request-Side: Prompt Injection Guard
| Variable | Default | Source File | Description |
|---|---|---|---|
INPUT_SANITIZER_ENABLED |
true |
src/middleware/promptInjectionGuard.ts |
Enable scanning of incoming messages for prompt injection patterns. |
INPUT_SANITIZER_MODE |
warn |
src/middleware/promptInjectionGuard.ts |
Injection policy: warn = log only, block = reject request with 400. Legacy redact does not strip injection text; use PII_REDACTION_ENABLED for request PII rewrite. |
INJECTION_GUARD_MODE |
(unset) | src/middleware/promptInjectionGuard.ts |
Legacy alias for INPUT_SANITIZER_MODE — same behavior. |
INPUT_SANITIZER_BLOCK_THRESHOLD |
high |
src/shared/utils/injectionSeverity.ts |
Minimum severity that MODE=block rejects: high (default), medium, or low. Medium patterns are observe-only unless lowered. |
INJECTION_GUARD_BLOCK_THRESHOLD |
(unset) | src/shared/utils/injectionSeverity.ts |
Legacy alias for INPUT_SANITIZER_BLOCK_THRESHOLD — same behavior. |
PII_REDACTION_ENABLED |
false |
src/lib/guardrails/piiMasker.ts |
When true, redact PII in incoming requests (independent of injection mode). |
PII_REVERSIBLE_VAULT_ENABLED |
false |
src/lib/pii/requestTokenVaultScope.ts |
With PII_REDACTION_ENABLED, mask request PII as per-request reversible tokens and restore them in 2xx responses. Also a DB feature flag (DB > ENV). |
CREDENTIAL_REDACTION_ENABLED |
false |
src/lib/guardrails/credentialMasker.ts |
Redact well-known API-key / secret-token patterns from request/response payloads. Opt-in; mirrors PII_REDACTION_ENABLED. |
Response-Side: PII Sanitizer
| Variable | Default | Source File | Description |
|---|---|---|---|
PII_RESPONSE_SANITIZATION |
false |
src/lib/piiSanitizer.ts |
Scan LLM responses for leaked PII before returning to client. |
PII_RESPONSE_SANITIZATION_MODE |
redact |
src/lib/piiSanitizer.ts |
redact = mask PII, warn = log only, block = drop entire response. |
VS Code Tokenized-Route Context Sanitizer
| Variable | Default | Source File | Description |
|---|---|---|---|
OMNIROUTE_VSCODE_SANITIZE_CONTEXT |
1 |
src/app/api/v1/vscode/contextSanitizer.ts |
Strips implicit active-editor context (editorContext, activeEditor, currentFile, selection, openTabs…) from /v1/vscode/[token]/* requests and redacts content of explicitly-attached sensitive files. Secure-by-default; set to 0 to disable. |
Scenarios
| Scenario | Configuration |
|---|---|
| Enterprise compliance | INPUT_SANITIZER_ENABLED=true, INPUT_SANITIZER_MODE=block, PII_REDACTION_ENABLED=true, PII_RESPONSE_SANITIZATION=true (injection blocks + request/response PII redaction; modes are independent) |
| Monitoring only | INPUT_SANITIZER_ENABLED=true, INPUT_SANITIZER_MODE=warn — logs but never blocks |
| Personal use | Leave all disabled — zero overhead |
6. Tool & Routing Policies
| Variable | Default | Source File | Description |
|---|---|---|---|
TOOL_POLICY_MODE |
disabled |
src/lib/toolPolicy.ts |
Controls LLM tool/function-calling access. allowlist = only listed tools, denylist = all except listed, disabled = no restrictions. |
OMNIROUTE_PAYLOAD_RULES_PATH |
./config/payloadRules.json |
open-sse/services/payloadRules.ts |
Path to payload manipulation rules JSON file (per-model/protocol upstream tweaks). |
OMNIROUTE_PAYLOAD_RULES_RELOAD_MS |
5000 |
open-sse/services/payloadRules.ts |
Reload interval (ms) for hot-reloading the payload rules file. Minimum 1000. |
OMNIROUTE_PREFER_CLAUDE_CODE_FOR_UNPREFIXED_CLAUDE_MODELS |
false |
open-sse/services/model.ts |
Opt-in: route bare claude-* model IDs from Claude Code clients through the Claude Code OAuth account instead of requiring a provider prefix. Explicit provider prefixes still win. Also configurable via a dashboard toggle on the Claude provider page. |
OMNIROUTE_REDACT_THINKING |
true |
open-sse/executors/base/redactThinkingBeta.ts |
Set false to stop OmniRoute adding the redact-thinking-2026-02-12 Anthropic beta itself (empty signature-only thinking blocks). Requests with thinking.display: "summarized" skip it regardless; a client-negotiated redact beta or a CC-compatible requestDefaults.redactThinking opt-in keeps it. Claude OAuth requests keep the beta (it is part of the Claude Code OAuth fingerprint) unless the default-off CLAUDE_OAUTH_SUMMARIZED_THINKING_UNREDACTED feature flag is on. |
BARE_MODEL_DEFAULT_OVERRIDE_LEGACY |
false |
open-sse/services/model.ts |
Legacy resolveBareModelToConnectionDefault behaviour (#4825): replace any bare model name with the selected connection's defaultModel. Off by default, only auto or an empty model is replaced; logs one warning per pair when on. |
COMBO_CONCURRENCY_PER_MODEL |
3 |
open-sse/services/comboConfig.ts |
Per-model concurrency cap for round-robin combos (#9100). The round-robin combo semaphore was hard-capped at 3 concurrent requests per model with no override, serializing higher-concurrency traffic behind that cap. Validated to >= 1, clamped to <= 32. |
OMNIROUTE_COMBO_MAX_DEADLINE_FAILURES |
unset (0 = disabled) |
open-sse/services/combo/comboPredicates.ts |
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 have accumulated. A failure counts when the attempt ends in a 504 whose structured error.code is the stream-readiness timeout: no non-ping SSE event within the readiness window, or a source stream that failed before its first non-ping event. An early EOF (stream closed before its first event) does not count. |
OMNIROUTE_AGENTIC_STALL_FAILOVER |
false |
open-sse/services/combo/agenticStallFailover.ts |
Opt-in: set to 1 (or true) so a combo member answering a tool-result turn with finish: stop + narration + zero tool calls fails over to the next target (priority-loop strategies, round-robin and pinned sessions). If no target does better, the stalled answer is returned rather than an error, and neither the provider breaker nor a model lockout is charged. Streamed turns are held back from the client until the verdict is settled. Requests using the Responses API input shape are not classified. Default OFF. |
DISABLE_CONTEXT_WINDOW_CHECKS |
false |
open-sse/handlers/chatCore.ts |
Dangerous opt-in that skips OmniRoute's local context-window / max-input-token check for direct single-model requests. Upstream providers still enforce their actual limits; prompt compression and the model's own output-token cap remain active. Effective precedence is Feature Flags DB override > environment variable > default; no restart is required. |
OMNIROUTE_SELF_HOSTED_PROVIDERS |
(unset) | open-sse/services/selfHostedEntry.ts |
Inline YAML providers: document (RIC-738, D4). When set (with or without a strategy: block), /v1/chat/completions diverts to the self-hosted unified OpenAI-compatible entry instead of the cloud pipeline. Unset (the default): the route falls straight through to the existing cloud pipeline. See docs/routing/SELF_HOSTED_OPENAI_ENTRY.md. |
OMNIROUTE_SELF_HOSTED_PROVIDERS_FILE |
(unset) | open-sse/services/selfHostedEntry.ts |
Path to a YAML file holding the same providers: document as OMNIROUTE_SELF_HOSTED_PROVIDERS, for deployments that prefer a file over an inline env var. Either one activates the self-hosted entry. |
OMNIROUTE_SELF_HOSTED_API_KEY |
(unset — open route) | open-sse/services/selfHostedEntry.ts |
Optional shared API key for the unified self-hosted entry (D5 scaffold, reserved for the per-key quota system). When set, requests must include Authorization: Bearer <key>. Unset: the route is open, matching the existing self-hosted local-provider pattern (loopback/trusted-network deployment). |
OMNIROUTE_SELF_HOSTED_STRATEGY |
(unset) | open-sse/services/routingStrategies.ts |
Inline YAML strategy: document for the deterministic routing engine (M2/RIC-740, D3) — blacklist/whitelist, cooldown breaker, cost-priority, latency-aware, fallback chain. Overrides an inline strategy: block nested inside OMNIROUTE_SELF_HOSTED_PROVIDERS, per-key. See docs/routing/DETERMINISTIC_ROUTING.md. |
OMNIROUTE_SELF_HOSTED_STRATEGY_FILE |
(unset) | open-sse/services/routingStrategies.ts |
Path to a YAML file holding the same strategy: document as OMNIROUTE_SELF_HOSTED_STRATEGY, for deployments that prefer a file over an inline env var. |
OMNIROUTE_DISABLE_CONVERSATION_TRACKING |
(unset) | open-sse/services/conversationTracker.ts |
Set 1 to stop collecting conversation history. resolveConversationId() returns an untracked result before it reads SQLite or parses message history, and client-supplied session IDs are covered too. Routing-session handling is unchanged and existing records are not deleted. For deployments that do not use the dashboard's conversation view and want the turn table to stop growing. |
OMNIROUTE_NADIR_API_KEY |
(unset) | open-sse/services/autoCombo/nadirStrategy.ts |
API key for the opt-in nadir auto-combo router strategy, used when the combo's own config.nadir.apiKey is unset. 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 field when combos use different accounts. |
OMNIROUTE_NADIR_BASE_URL |
https://api.getnadir.com |
open-sse/services/autoCombo/nadirStrategy.ts |
Base origin of the Nadir decision API, used when the combo's own config.nadir.baseUrl is unset. Only needed for a self-hosted Nadir, which keeps prompt heads inside your own network. A trailing /v1 is tolerated and stripped. |
OMNIROUTE_API_KEY_WEEKLY_WINDOW |
provider |
src/lib/usage/apiKeyUsageLimits.ts |
Weekly window for per-API-key USD usage limits (request enforcement, GET /api/keys/{id}/usage-limits, @@om-usage). provider: the week ends at the earliest weekly reset among the upstream connections the key can reach, or is a rolling 7 days when none is known. calendar: the local week from Monday 00:00 to the next Monday 00:00, identical for every key. calendar is recommended when one pool of upstream accounts is shared by many individually budgeted keys. Invalid values fall back to provider. |
OMNIROUTE_API_KEY_WEEKLY_WINDOW_TIMEZONE |
(process timezone) | src/lib/usage/apiKeyUsageLimits.ts |
IANA timezone (for example Asia/Shanghai) that defines Monday 00:00 for the calendar weekly window. Unset or invalid: the timezone of the OmniRoute process (the TZ of the host or container, which is often unset, i.e. Coordinated Universal Time, in container images). Ignored in provider mode. |
OMNIROUTE_MAX_TOOLS_LIMIT |
128 |
open-sse/config/constants.ts |
Default maximum number of tools allowed in a request (OpenAI default). Positive integers only; unset or invalid values keep 128. A provider with a known/proactive limit (grok-cli 200, nvidia 1536) still applies its own cap — this only moves the default ceiling. Claude-format targets have no default cap (the Messages API has none); a learned limit still applies. |
OMNIROUTE_TOOL_OUTPUT_IMAGE_MAX_COUNT |
16 |
open-sse/translator/request/openai-responses.ts |
Responses to Chat translation: how many tool-output images (function_call_output, custom_tool_call_output, role tool) are re-sent as user image parts per request. The newest are kept and each older one becomes a text placeholder with its tool_call_id. Positive integers only; unset or invalid values keep 16. |
OMNIROUTE_TOOL_OUTPUT_IMAGE_MAX_BYTES |
20971520 (20 MB) |
open-sse/translator/request/openai-responses.ts |
Total size of the tool-output image URLs re-sent per request in the same translation. Images past the budget are dropped oldest first, with one warning per request. Positive integers only; unset or invalid values keep 20971520. |
OMNIROUTE_RESPONSES_STRICT_TOOL_HISTORY |
false |
open-sse/translator/helpers/responsesToolHistory.ts |
How inconsistent Responses tool history is handled: an output with no call, a call with no output, a missing, overlong or invalid call_id, or malformed historical arguments. Off, OmniRoute repairs the history and dispatches it (orphan outputs are dropped, unanswered calls get an empty output, ids are minted or clamped, malformed arguments become {}). On, the request gets a 400 before dispatch; a valid history is forwarded with its call ids and JSON arguments as sent. Accepts true or 1; any other value keeps the default. |
OMNIROUTE_PROMPT_EMULATE_TOOLS |
(on) | open-sse/executors/syntxChat.ts |
SYNTX.ai prompt-emulated tool calling: unset or 1/true/on/yes injects the local tool catalog into the prompt; any other value (e.g. 0) skips that injection. |
7. URLs & Cloud Sync
| Variable | Default | Source File | Description |
|---|---|---|---|
BASE_URL |
http://localhost:20128 |
src/lib/cloudSync.ts |
Server-side URL for internal sync jobs to call /api/sync/cloud. Keep this as a loopback/container URL even when the app is publicly proxied. A2A skills also use it (see OMNIROUTE_BASE_URL) and fail rather than send an API key to a public plain-http URL. |
CLOUD_URL |
(empty) | src/lib/cloudSync.ts |
Cloud relay endpoint URL (premium feature). |
CLOUD_SYNC_TIMEOUT_MS |
12000 |
src/lib/cloudSync.ts |
HTTP timeout for cloud sync requests. |
OMNIROUTE_BUILD_PROFILE |
full |
Webpack build config | Build-time profile (set to minimal to physically exclude privileged modules from bundle). |
OMNIROUTE_STANDALONE_DIR |
.build/ standalone output | scripts/build/colocate-standalone.mjs |
Build-time override for the standalone output directory consumed by the post-build colocation step. Not a runtime setting. |
OMNIROUTE_DIST_DIR |
dist/ (repo root) |
scripts/build/prepublish.ts |
Build-time override for the directory the publish step (prepublish.ts) writes the CLI bundle into, instead of dist/ under the repo root. The directory is wiped before the build. Not a runtime setting. |
OMNIROUTE_CLOUD_SYNC_SECRET |
(empty) | src/lib/cloudSync.ts |
Shared secret used to verify the HMAC-SHA256 signature of Cloud Sync responses. |
OMNIROUTE_CLOUD_SYNC_SECRETS |
false |
src/lib/cloudSync.ts |
Set to true to allow the Cloud Sync endpoint to overwrite local credentials. Default is false. |
OMNIROUTE_CLOUD_SYNC_ENFORCE_SIGNATURE |
false |
src/lib/cloudSync.ts |
Set to true to reject an unsigned Cloud Sync response when no local secret is configured (#13679). A signature that is present is always verified — and always rejected when OMNIROUTE_CLOUD_SYNC_SECRET is unset — regardless of this flag. The default flips to enforced in v3.9. |
OMNIROUTE_ZED_IMPORT_LEGACY_ONE_STEP |
false |
src/app/api/providers/zed/import/route.ts |
Set to true to fall back to the v3.8.5 one-step "import everything" behavior without user confirmation. |
NEXT_PUBLIC_BASE_URL |
http://localhost:20128 |
OAuth, Dashboard, sync | Public-facing URL for OAuth redirect_uri, Dashboard links, and generated public URLs. Set this to the stable public URL when OAuth callbacks or generated browser links must use a canonical reverse-proxy host. |
NEXT_PUBLIC_CLOUD_URL |
(empty) | Client-side | Client-side mirror of CLOUD_URL. |
NEXT_PUBLIC_APP_URL |
(unset) | src/shared/services/cloudSyncScheduler.ts |
Legacy fallback for NEXT_PUBLIC_BASE_URL. |
NEXT_PUBLIC_PORT |
(unset — falls back to PORT) |
src/shared/hooks/useDisplayBaseUrl.ts |
Client-side fallback port for display URLs when no origin is known (SSR/tests); read before PORT. |
OMNIROUTE_PUBLIC_BASE_URL |
(unset) | Public-origin resolver, image URLs | Highest-priority browser-facing OmniRoute origin used for public URL generation and non-dashboard browser-origin validation. Set this when OpenWebUI or another relay reaches OmniRoute by an internal URL but the user's browser must fetch generated media from a LAN, tunnel, or public origin. Do not include /v1. |
OMNIROUTE_PROVIDER_MANIFEST_URL |
(unset) | open-sse/config/providerPluginManifestUrl.ts |
Absolute provider plugin manifest URL advertised to sidecar clients. When unset, OmniRoute derives /api/v1/provider-plugin-manifest from request origin or HOST/PORT. |
OMNIROUTE_PUBLIC_PROTOCOL |
http |
open-sse/config/providerPluginManifestUrl.ts |
Protocol used when deriving the provider plugin manifest URL from HOST/PORT without a request origin. Set to https behind a TLS-terminating public proxy when no explicit OMNIROUTE_PROVIDER_MANIFEST_URL is set. |
OMNIROUTE_TRUST_PROXY |
(unset) | src/server/origin/publicOrigin.ts |
Optional trust mode for forwarded public-origin headers. Unset = do not trust Forwarded / X-Forwarded-* for security decisions. true / loopback trusts forwarded host/proto only from a token-stamped loopback proxy. private / lan also trusts private-LAN proxy peers, lets the API_PORT bridge keep such a peer's X-Forwarded-For, and lets LOCAL_ONLY routes accept a private-network client that such a proxy reports (never a Cloudflare-tunnel request, a loopback-only chain, or the loopback-only CLI-token gate). Prefer explicit NEXT_PUBLIC_BASE_URL in production. |
KIE_CALLBACK_URL |
(unset) | open-sse/utils/kieTask.ts |
Public callback URL for asynchronous kie.ai jobs. Highest-priority override before OMNIROUTE_KIE_CALLBACK_URL and OMNIROUTE_PUBLIC_URL. |
OMNIROUTE_KIE_CALLBACK_URL |
(unset) | open-sse/utils/kieTask.ts |
Alternate spelling of KIE_CALLBACK_URL. Falls back when the primary variable is unset. |
OMNIROUTE_PUBLIC_URL |
(unset) | open-sse/utils/kieTask.ts |
Public origin used to compose async callback URLs. Lowest-priority fallback for kie.ai callbacks; also used as a generic public URL for other relays. |
OMNIROUTE_CROF_USAGE_URL |
https://crof.ai/usage_api/ |
open-sse/services/usage.ts |
CrofAI quota lookup endpoint used by the Usage page. Override for relays / test fixtures. |
OMNIROUTE_CLINEPASS_USAGE_URL |
https://api.cline.bot/api/v1/users/me/plan/usage-limits |
open-sse/services/usage/clinepass.ts |
ClinePass 5-hour / weekly / monthly quota endpoint used by the Usage page. Override for relays / test fixtures. |
OMNIROUTE_OPENCODE_QUOTA_URL |
https://opencode.ai/zen/go/v1/usage |
open-sse/services/opencodeQuotaFetcher.ts |
Official API-key-authenticated OpenCode Go usage endpoint used by the Usage page. Override for relays / test fixtures. |
OPENCODE_SYNTHESIZE_CLI_HEADERS |
true |
open-sse/executors/opencode.ts |
Synthesize OpenCode CLI identity headers (User-Agent, x-opencode-client/project, request/session UUIDs) on opencode-go/zen upstream requests the client didn't send, so Cloudflare on VPS egress accepts them (#6210/#5997). On by default since #10571; opt out with false/0/no/off. |
OPENCODE_USER_AGENT |
opencode/1.18.31 |
open-sse/utils/opencodeHeaders.ts |
Default User-Agent used when OPENCODE_SYNTHESIZE_CLI_HEADERS is on and no per-provider <PROVIDER>_USER_AGENT override is set. Only applied to opencode executors. On a keyless request the upstream gates, a configured value that does not carry opencode/<version >= 1.17> is replaced by this default rather than refused. |
OMNIROUTE_FORWARD_ATTRIBUTION |
1 (on) |
open-sse/utils/opencodeHeaders.ts |
Forward client app-attribution headers (x-session-id, x-title, http-referer) to upstream providers, so a request that starts inside a listed harness keeps its identity through the router (OpenRouter publisher gates key on these). 0/false/no/off keeps the registry/operator identity and drops client-supplied values. Operator-configured custom headers always win over client values. |
OPENCODE_CLIENT |
desktop |
open-sse/executors/opencode.ts |
Value for the synthesized x-opencode-client header when OPENCODE_SYNTHESIZE_CLI_HEADERS is on. |
OPENCODE_PROJECT |
global |
open-sse/executors/opencode.ts |
Value for the synthesized x-opencode-project header when OPENCODE_SYNTHESIZE_CLI_HEADERS is on. |
OMNIROUTE_EGRESS_IP_LOCK_PROVIDERS |
(unset) | open-sse/config/providerErrorRules.ts |
Effective set of providers whose upstream failures are bucketed by egress IP (one 429 parks every sibling connection sharing that IP). Unset uses the free-tier default opencode,opencode-go,opencode-cli; none/off/false/0 disables the cascade entirely; a comma-separated list replaces the set. Paid plans are account-bucketed upstream and can safely disable it (#9611). |
OMNIROUTE_EGRESS_QUOTA_ROTATION_PROVIDERS |
(unset) | open-sse/config/providerErrorRules.ts |
Quota-refusal egress rotation scope. Unset sets a pool member aside on a 429 only for the IP-bucketed family above; all extends that write to every provider, so a rate limit received through a member makes the next pick egress elsewhere. Any value other than all is ignored. Needs PROXY_SKIP_RECENTLY_FAILED (on by default). The store is keyed by egress address, not (provider, address), so a widened 429 parks that member for every provider until the period elapses (5 min, doubling to 15). Read per response outcome, so a change applies without a restart. |
OPENCODE_FREE_TIER_REQUEST_CONTRACT |
(unset) | open-sse/executors/opencodeFreeTierContract.ts |
Set to off to stop adjusting the body of keyless OpenCode requests (streaming flag and tool list). Headers are still applied. Read per request, so a change takes effect immediately. |
OPENCODE_FREE_TIER_PLACEHOLDER_TOOLS |
(unset) | open-sse/executors/opencodeFreeTierContract.ts |
Comma-separated tool names to declare on a keyless OpenCode request that carries none, when nothing has been observed yet for that model. Empty falls back to a single placeholder the model is told not to call. At most 32 entries, [A-Za-z_][A-Za-z0-9_-]{0,63}; invalid entries are ignored. |
OPENCODE_FREE_TIER_CREDENTIAL |
public |
open-sse/executors/opencodeFreeTierContract.ts |
Credential sent on the gated free-tier lane (https://opencode.ai/inference/v1). Since 2026-10-21 that lane answers 403 Model access is disabled to a real API key and serves the anonymous literal instead. key keeps the operator's API key, none/off sends no credential header, any other literal is sent as the bearer token. Read per request. |
OPENCODE_FREE_TIER_RELAY_URL |
unset | src/lib/opencodeFreeRelay.ts |
Base URL of the Bun relay for gated free-tier OpenCode requests. When set, those requests carry the OpenCode CLI system prompt and tool set and are sent through the relay (scripts/ops/opencode-free-relay.ts), because the upstream answers 429 to non-Bun HTTP clients. Loopback URLs are started with the server when bun is on PATH; a path on the URL is ignored. Plain http:// is accepted only for loopback hosts (localhost, 127.0.0.0/8, ::1); any other host must use https://, otherwise requests fail with an explicit error. Chat Completions only. Read per request. |
OPENCODE_FREE_RELAY_BUN |
bun on PATH |
src/lib/opencodeFreeRelay.ts |
Bun binary used to start the relay. |
OPENCODE_FREE_RELAY_SCRIPT |
scripts/ops/opencode-free-relay.ts under the package root |
src/lib/opencodeFreeRelay.ts |
Path of the relay script. The default is resolved from the installed package root, then the working directory. |
OPENCODE_FREE_RELAY_HOST |
127.0.0.1 |
scripts/ops/opencode-free-relay.ts |
Relay listen host. |
OPENCODE_FREE_RELAY_PORT |
20199 |
scripts/ops/opencode-free-relay.ts |
Relay listen port. |
OPENCODE_FREE_RELAY_UPSTREAM |
https://opencode.ai |
scripts/ops/opencode-free-relay.ts |
Origin the relay forwards to. Must be https:// (http:// only for a loopback test origin); the relay refuses to start otherwise. |
OPENCODE_FREE_RELAY_TOKEN |
unset | scripts/ops/opencode-free-relay.ts, open-sse/executors/opencodeRelay.ts |
Shared secret. OmniRoute sends it in x-opencode-relay-auth; the relay answers 401 without it. Required: a relay with a non-loopback OPENCODE_FREE_RELAY_HOST refuses to start without it. |
OPENCODE_FREE_RELAY_PROXY_ALLOWLIST |
unset | scripts/ops/opencode-free-relay.ts |
Comma-separated host or host:port egress proxies a non-loopback relay accepts from callers (x-opencode-relay-proxy); any other proxy answers 403. Ignored on a loopback bind. |
OMNIROUTE_OLLAMA_CLOUD_USAGE_URL |
https://ollama.com/settings |
open-sse/services/usage.ts |
Ollama Cloud settings URL used for quota scraping. Override for relays / test fixtures. |
OMNIROUTE_OLLAMA_CLOUD_BALANCE_URL |
https://ollama.com/api/balance |
open-sse/services/ollamaCloudBalance.ts |
Ollama Cloud documented upstream balance endpoint (GET https://ollama.com/api/balance, Authorization: Bearer <API key>). Read once at module load. Used first for Ollama Cloud quota when the connection has an API key; the settings-page cookie scraper stays as the fallback. Override for relays / test fixtures. |
OLLAMA_USAGE_COOKIE |
(unset) | open-sse/services/usage.ts |
Ollama Cloud __Secure-session cookie used for settings-page quota scraping. Sensitive; prefer the per-connection Dashboard field when multiple accounts are configured. |
OLLAMA_CLOUD_USAGE_COOKIE |
(unset) | open-sse/services/usage.ts |
Alternate Ollama Cloud __Secure-session cookie env var. Sensitive; prefer the per-connection Dashboard field when multiple accounts are configured. |
OMNIROUTE_OLLAMA_USAGE_COOKIE |
(unset) | open-sse/services/usage.ts |
Alternate Ollama Cloud __Secure-session cookie env var used before the shorter aliases. Sensitive; prefer the per-connection Dashboard field when multiple accounts are configured. |
OMNIROUTE_CODEWHISPERER_BASE_URL |
https://codewhisperer.us-east-1.amazonaws.com |
open-sse/services/usage.ts |
CodeWhisperer (AWS Kiro) usage limits endpoint. Override for relays / test fixtures. |
Important
When deploying behind a reverse proxy (nginx, Caddy), set
NEXT_PUBLIC_BASE_URLto your stable public URL (e.g.,https://omniroute.example.com) when OAuth callbacks or generated public links must use that hostname. Without this, OAuth callbacks can fail because the redirect_uri won't match and generated public links can point at the internal container origin.Keep
BASE_URLas an internal loopback/container URL for server-to-server jobs. Do not use a browserOriginor public hostname for credential-bearing internal self-fetches.Authenticated dashboard writes do not require a static public base URL: the dashboard sends same-origin unsafe requests with a session-bound CSRF token. OmniRoute still centralizes public-origin validation for non-dashboard browser integrations: explicit public URL env vars are trusted first; raw
Forwarded/X-Forwarded-*headers are ignored unlessOMNIROUTE_TRUST_PROXYis enabled and the immediate proxy peer is token-stamped as trusted. Do not use CORS settings to fix same-origin dashboard requests; CORS is only for cross-origin browser clients.
8. Outbound Proxy
Route upstream LLM provider calls through an HTTP or SOCKS5 proxy for egress control, geo-routing, or IP masking.
OMNIROUTE_UPSTREAM_HTTP2_ENABLED defaults to true. Set it to false, 0, no, or
off to force HTTP/1.1 on the Undici dispatchers in open-sse/utils/proxyDispatcher.ts
and open-sse/utils/proxyFetch.ts: direct egress, HTTP(S)/SOCKS proxies, relays, and
their fresh-socket retries. This preserves TLS certificate verification, proxy
authentication, connection limits, and keep-alive settings. Restart OmniRoute after
changing it because dispatchers are cached and relay agents are created at startup.
The switch does not control wreq TLS fingerprinting or provider-specific transports.
| Variable | Default | Source File | Description |
|---|---|---|---|
ENABLE_SOCKS5_PROXY |
true |
open-sse/executors |
Enable SOCKS5 proxy agent for upstream calls. Opt-out with false. |
OMNIROUTE_GZIP_REQUEST_BODIES |
true |
open-sse/executors/base/gzipRequestBody.ts |
Gzip the request body sent to the official api.anthropic.com (4096+ characters, direct connections only; skipped behind a proxy, TLS impersonation or NODE_EXTRA_CA_CERTS). Anthropic accepts gzip only. A refused encoding (415, a non-Anthropic 400/403, or an origin JSON-parse 400) is resent uncompressed once and the origin stays uncompressed for one hour. Opt-out with 0, false, off or no. |
NEXT_PUBLIC_ENABLE_SOCKS5_PROXY |
true |
Client-side | Client-side awareness of SOCKS5 availability. |
PROXY_SKIP_RECENTLY_FAILED |
true |
src/shared/utils/featureFlags.ts |
On-by-default feature flag (see FEATURE_FLAGS.md; a dashboard DB override wins). Proxy pools and per-account rotation stop re-serving a member that just failed (refused TCP probe, or a 429 through it) for a period that doubles on each repeat, up to a cap. false restores plain selection. |
SELECTOR_CONTROL_ALLOWLIST |
(unset) | src/lib/proxySubscription/selectorGuard.ts |
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 over http/https is allowed by default. A dashboard DB value wins over this variable when set and non-empty. |
PROXY_QUOTA_429_BASE_MS |
300000 |
open-sse/utils/proxyRefusalMemory.ts |
Base period (ms) of the 429 set-aside, doubled on each repeat. Read once at startup. Bounded to 1000..3600000; out-of-range or unreadable falls back to the default with a warning. |
PROXY_QUOTA_429_MAX_MS |
900000 |
open-sse/utils/proxyRefusalMemory.ts |
Cap (ms) of the 429 set-aside. Read once at startup. Bounded to 1000..3600000; out-of-range or unreadable falls back to the default with a warning. When the cap is below the base, it falls back to the default. Lowering the cap also shortens streak forgetting: entries purge 2 x max after expiry. |
PROXY_POOL_SHARED_EGRESS_ORDER |
false |
src/shared/utils/featureFlags.ts |
Opt-in feature flag (see FEATURE_FLAGS.md; a dashboard DB override wins). 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_WEBHOOK_REBOUND_MS |
300000 |
src/lib/proxyEvents/proxyTransitionBridge.ts |
Rebound window (ms) capping repeat proxy.set_aside webhook alerts per pool member so a burst of refusals sends one event. Read on each emit. Bounded to 1000..3600000; out-of-range or unreadable falls back to the default silently. |
HTTP_PROXY |
(unset) | Node.js standard | HTTP proxy for upstream calls. |
HTTPS_PROXY |
(unset) | Node.js standard | HTTPS proxy for upstream calls. |
ALL_PROXY |
(unset) | Node.js standard | Universal proxy (supports socks5://). |
OMNIROUTE_PROXY_ECHO_URL |
(unset) | src/lib/proxyEchoTarget.ts |
Pins the echo-IP target used by proxy egress probes to a single URL. Unset, the probe tries api64.ipify.org then api4.ipify.org so IPv4-only tunnels are not reported dead (#9694). |
NO_PROXY |
(unset) | Node.js standard | Comma-separated hostnames/IPs to bypass the proxy. |
OMNIROUTE_PROXY_DISPATCHER_CONNECTIONS |
32 |
open-sse/utils/proxyDispatcher.ts |
Max concurrent sockets per cached HTTP/SOCKS proxy dispatcher. Long-lived SSE streams such as Codex /v1/responses need more than one connection when several requests share the same account-level proxy. Values above 256 are capped. |
SOCKS_HANDSHAKE_TIMEOUT_MS |
10000 |
open-sse/utils/socksConnectorWithFamily.ts |
SOCKS5 handshake (connect) timeout in ms. Raise it when a single residential gateway host is hit by high concurrency (e.g. 100 simultaneous requests) — the real 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. Capped at 120000. |
PROXY_FAIL_OPEN |
false |
src/sse/handlers/chatHelpers.ts |
When false (default), a request whose assigned proxy fails to resolve is refused (fail-closed) rather than falling back to a direct connection — prevents real-IP leaks. Set true to restore the legacy DIRECT fallback. |
ENABLE_TLS_FINGERPRINT |
false |
open-sse/executors |
Spoof TLS fingerprint using wreq-js (mimics Chrome 124). Counters JA3/JA4 blocking. |
TLS_FINGERPRINT_PROVIDERS |
(unset) | open-sse/utils/proxyFetch.ts |
Comma-separated provider allowlist for the new proxied TLS routing (open-sse/utils/proxyFetch.ts). Direct TLS keeps its legacy behavior when unset; only these providers route through the Chrome-124 fingerprint bridge. Groq (api.groq.com) is excluded even when the allowlist is unset, because Chrome JA3 triggers Cloudflare 1010 while native undici reaches the API. |
OMNIROUTE_TURNSTILE_IGNORE_TLS_ERRORS |
false |
open-sse/services/claudeTurnstileSolver.ts |
Allow the Claude Turnstile Playwright browser context to ignore HTTPS certificate errors. |
Scenarios
| Scenario | Configuration |
|---|---|
| SOCKS5 through SSH tunnel | ALL_PROXY=socks5://127.0.0.1:7890, ENABLE_SOCKS5_PROXY=true |
| Corporate HTTP proxy | HTTP_PROXY=http://proxy.corp.com:3128, HTTPS_PROXY=http://proxy.corp.com:3128, NO_PROXY=localhost,internal.corp.com |
| Anti-fingerprint | ENABLE_TLS_FINGERPRINT=true — requires wreq-js (included) |
| Egress-controlled / no direct access | Leave PROXY_FAIL_OPEN=false (default). Requests fail hard when the proxy is unavailable instead of leaking via direct. |
| Legacy / dev — allow direct fallback | PROXY_FAIL_OPEN=true. Restores pre-hardening behaviour: direct connection used when proxy resolution fails. |
Note (NVIDIA validation bypass — #3226): NVIDIA's API-key validation endpoint stalls when routed through the global proxy/TLS-patched fetch (undici dispatcher → 504).
src/lib/providers/validation.ts::directHttpsRequest()intentionally bypasses the proxy patch for that one validation call usingsafeOutboundFetch({ bypassProxyPatch: true }). This is a documented, scoped exception — it does not affect chat/usage egress. The bypass is scope-pinned bytests/unit/proxy-bypass-scope-guard-3226.test.ts.
9. CLI Tool Integration
Controls how OmniRoute discovers and launches CLI sidecars (Claude Code, Codex, etc.).
| Variable | Default | Source File | Description |
|---|---|---|---|
CLI_MODE |
auto |
src/shared/services/cliRuntime.ts |
auto = search system PATH; manual = use explicit paths only. |
CLI_EXTRA_PATHS |
(unset) | src/shared/services/cliRuntime.ts |
Additional PATH entries for CLI binary discovery (colon-separated). |
CLI_CONFIG_HOME |
(unset) | src/shared/services/cliRuntime.ts |
Override home directory for reading CLI configs (~/.claude, ~/.codex). Must be absolute and inside the process home — or, in a container, a bind-mounted path (that is how /host-home works). Anything else falls back to the home dir. |
CLI_ALLOW_CONFIG_WRITES |
true |
src/shared/services/cliRuntime.ts |
Allow OmniRoute to write CLI config files (token refresh, session data). Set to false to make every CLI config write fail with an explicit "writes disabled" error. |
CLI_CLAUDE_BIN |
claude |
src/shared/services/cliRuntime.ts |
Custom path to Claude CLI binary. |
CLI_CODEX_BIN |
codex |
src/shared/services/cliRuntime.ts |
Custom path to Codex CLI binary. |
CLI_DROID_BIN |
droid |
src/shared/services/cliRuntime.ts |
Custom path to Droid CLI binary. |
CLI_OPENCLAW_BIN |
openclaw |
src/shared/services/cliRuntime.ts |
Custom path to OpenClaw CLI binary. |
CLI_CURSOR_BIN |
agent, then cursor |
src/shared/services/cliRuntime.ts |
Custom path to the Cursor agent binary. Without it, detection tries agent first and falls back to cursor. |
CLI_CLINE_BIN |
cline |
src/shared/services/cliRuntime.ts |
Custom path to Cline CLI binary. |
CLI_5DIVE_BIN |
5dive |
src/shared/services/cliRuntime.ts |
Custom path to the 5dive CLI binary. |
CLI_5DIVE_STATE_DIR |
/var/lib/5dive |
src/shared/services/cliRuntime.ts |
5dive's system state dir (root-owned auth profiles); mirrors 5dive's own STATE_DIR default. |
CLI_CONTINUE_BIN |
cn |
src/shared/services/cliRuntime.ts |
Custom path to Continue CLI binary. |
CLI_QODER_BIN |
qodercli |
src/shared/services/cliRuntime.ts |
Custom path to Qoder CLI binary. |
CLI_QWEN_BIN |
qwen |
src/shared/services/cliRuntime.ts |
Custom path to the Qwen Code CLI binary. |
CLI_AIDER_BIN |
aider |
src/shared/services/cliRuntime.ts |
Custom path to the Aider CLI binary. |
CLI_GOOSE_BIN |
goose |
src/shared/services/cliRuntime.ts |
Custom path to the Goose CLI binary. |
CLI_WHYCODES_BIN |
whycodes |
src/shared/services/cliRuntime.ts |
Custom path to the WhyCodes CLI binary. |
CLI_GEMINI_BIN |
gemini |
src/shared/services/cliRuntime.ts |
Custom path to the Google Gemini CLI binary — server-side detection/health checks only; omniroute run gemini resolves the gemini binary from the system PATH. |
CLI_KILO_BIN |
kilocode |
src/shared/services/cliRuntime.ts |
Custom path to the Kilo Code CLI binary. |
CLI_OPENCODE_BIN |
opencode |
src/shared/services/cliRuntime.ts |
Custom path to the OpenCode CLI binary. |
CLI_HERMES_BIN |
hermes |
src/shared/services/cliRuntime.ts |
Custom path to the Hermes binary. Shared by both catalog entries (hermes and hermes-agent). |
CLI_FORGE_BIN |
forge |
src/shared/services/cliRuntime.ts |
Custom path to the ForgeCode CLI binary. |
CLI_JCODE_BIN |
jcode |
src/shared/services/cliRuntime.ts |
Custom path to the jcode CLI binary. |
CLI_DEEPSEEK_TUI_BIN |
deepseek-tui |
src/shared/services/cliRuntime.ts |
Custom path to the DeepSeek TUI binary. |
CLI_CODEWHALE_BIN |
codewhale |
src/shared/services/cliRuntime.ts |
Custom path to the CodeWhale CLI binary. |
CLI_SMELT_BIN |
smelt |
src/shared/services/cliRuntime.ts |
Custom path to the Smelt CLI binary. |
CLI_PI_BIN |
pi |
src/shared/services/cliRuntime.ts |
Custom path to the Pi (pi-coding-agent) binary. |
CLI_CRUSH_BIN |
crush |
src/shared/services/cliRuntime.ts |
Custom path to the Crush CLI binary. |
CLI_OMP_BIN |
omp |
src/shared/services/cliRuntime.ts |
Custom path to the Oh My Pi (omp) agent binary. |
CLI_LETTA_BIN |
letta |
src/shared/services/cliRuntime.ts |
Custom path to the Letta CLI binary. |
CLI_PRIME_AGENT_BIN |
prime-agent |
src/shared/services/cliRuntime.ts |
Custom path to the Prime Agent (Prime Intellect) binary. |
CLI_WINDSURF_BIN |
(none) | src/shared/services/cliRuntime.ts |
Custom path to the Windsurf binary. Windsurf ships no default command — binary detection stays disabled until this is set. |
CLI_DEVIN_BIN |
devin |
open-sse/executors/devin-cli.ts |
Custom path to the Devin CLI binary (v3.8.0). Used by the Windsurf/Devin executor. |
DEVIN_DESKTOP_VERSION |
3.6.27 |
open-sse/executors/devin-desktop.ts |
Devin Desktop ide_version. Overrides must use x.y.z format; invalid values fall back to the verified default. |
DEVIN_DESKTOP_EXTENSION_VERSION |
1.48.2 |
open-sse/executors/devin-desktop.ts |
Bundled Codeium/language-server extension_version, distinct from Desktop ide_version. Overrides must use x.y.z; invalid values use the bundled default. |
CLI_DEVIN_AGENTIC_BIN |
devin |
open-sse/executors/devin-cli-agentic.ts |
Agentic bridge-only Devin CLI override. The executor accepts only the local ACP stdio upstream. |
DEVIN_AGENTIC_HOME |
(required) | open-sse/executors/devin-cli-agentic.ts |
Absolute isolated home for the agentic Devin subprocess; accepted bridge paths are /home/bridge and task-local .sandbox paths (on Windows, C:\...\.sandbox\...). |
DEVIN_AGENTIC_ACP_TIMEOUT_MS |
120000 |
open-sse/executors/devin-cli-agentic.ts |
Maximum duration of one Devin ACP turn before the bridge terminates the child and returns an explicit timeout. |
DEVIN_BRIDGE_MODEL |
devin-cli-agentic/swe-1-7 |
docker/devin-bridge/compose.yml |
Main Claude Code model alias for the isolated bridge. The live harness replaces the example with a model returned by the current Devin account. |
DEVIN_BRIDGE_SONNET_MODEL |
DEVIN_BRIDGE_MODEL |
docker/devin-bridge/compose.yml |
Isolated bridge alias used when Claude Code requests its Sonnet default. |
DEVIN_BRIDGE_OPUS_MODEL |
DEVIN_BRIDGE_MODEL |
docker/devin-bridge/compose.yml |
Isolated bridge alias used when Claude Code requests its Opus default. |
DEVIN_BRIDGE_HAIKU_MODEL |
DEVIN_BRIDGE_MODEL |
docker/devin-bridge/compose.yml |
Isolated bridge alias used when Claude Code requests its Haiku default. |
DEVIN_BRIDGE_SUBAGENT_MODEL |
DEVIN_BRIDGE_MODEL |
docker/devin-bridge/compose.yml |
Isolated bridge alias used for Claude Code subagents. |
DEVIN_SEAT_API_URL |
https://server.codeium.com |
open-sse/services/usage/devinCli.ts |
Optional override for the Codeium seat-management API used by Devin CLI quota (GetUserStatus). |
AUGGIE_BIN |
auggie |
open-sse/executors/auggie.ts |
Absolute-path override for the Augment (Auggie) CLI binary used by the local auggie provider. Falls back to CLI_AUGGIE_BIN, then a PATH lookup. |
CLI_AUGGIE_BIN |
auggie |
open-sse/executors/auggie.ts |
Alias override for the Augment (Auggie) CLI binary path (checked after AUGGIE_BIN). |
ZCODE_BIN |
zcode |
open-sse/executors/zcode.ts |
Binary used for the local zcode provider's stdio client. Falls back to zcode on PATH. |
ZCODE_ARGS |
— | open-sse/executors/zcode.ts |
JSON array (≤16 strings) of extra arguments passed to the zcode binary when launched via cliTools. |
ZCODE_CWD |
process.cwd() |
open-sse/executors/zcode.ts |
Working directory for the ZCode app-server subprocess. |
ZCODE_TRANSPORT |
app-server |
open-sse/executors/zcode.ts |
app-server (default) or gateway. Experimental / unsupported: gateway sends direct Z.AI Coding Plan HTTP requests by reproducing the ZCode client protocol (signing handshake and proof-of-work header of client 0.16.9) and may break when ZCode updates. It accepts only the Individual Coding Plan profile. |
ZCODE_PROVIDER_ID |
account:zai-individual-coding-plan |
open-sse/executors/zcode.ts |
Exact native provider profile for model selection. When unset, the Individual Plan account profile is used, falling back to builtin:zai-coding-plan (the config entry that holds the Individual Coding Plan key). Set an exact ID such as account:zai-start-plan to pin that profile; a pinned profile never falls back. |
ZCODE_SERVER_RUNTIME_ROOT |
~/.zcode/server |
open-sse/executors/zcode.ts |
Root of the ZCode app-server runtime (where the bundled node and zcode-server.cjs live). |
ZCODE_SERVER_NODE |
<runtimeRoot>/node |
open-sse/executors/zcode.ts |
Node executable used to host the ZCode app-server. |
ZCODE_SERVER_ENTRY |
<runtimeRoot>/zcode-server.cjs |
open-sse/executors/zcode.ts |
App-server entry script used to host the ZCode server. |
ZCODE_STARTUP_TIMEOUT_MS |
10000 |
open-sse/executors/zcode.ts |
Startup timeout (ms) before a ZCode app-server launch is considered failed. |
ZCODE_RPC_TIMEOUT_MS |
30000 |
open-sse/executors/zcode.ts |
Per-request RPC timeout (ms) for a ZCode app-server call. |
ZCODE_TURN_TIMEOUT_MS |
120000 |
open-sse/executors/zcode.ts |
Maximum duration (ms) of one ZCode turn before the supervisor times it out. |
ZCODE_POLL_INTERVAL_MS |
250 |
open-sse/executors/zcode.ts |
Polling interval (ms) for ZCode turn completion. |
MINIMAX_CODE_GATEWAY_URL |
https://agent.minimax.io/mavis/api/v1/llm/v1/messages |
open-sse/executors/minimaxCodeGateway.ts |
Endpoint of the managed MiniMax gateway that answers with native tool calls. It 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_TIMEOUT_MS |
60000 |
open-sse/executors/minimax-code.ts |
Maximum duration (ms) of one managed gateway attempt. The whole call (attempt, backoff, one retry) stays around two minutes, so an unreachable gateway cannot hold a model slot for long. |
MINIMAX_CODE_GATEWAY_RETRIES |
1 |
open-sse/executors/minimaxCodeGateway.ts |
Retries of a managed gateway call that fails with a transient error (429, 5xx, dropped connection). |
MINIMAX_CODE_CONTEXT_WINDOW |
1000000 |
open-sse/executors/minimaxCodeGateway.ts |
The context window the managed MiniMax gateway is asked for. The model catalog of the MiniMax Code product declares 512000 as the default window of MiniMax-M3 and MiniMax-M3.1-Flash and offers 1000000 as a second one; the gateway answers in the larger window (a request of 1024056 input tokens was answered with 200 on 2026-10-23). Set this to 512000 to narrow the request — the plan counts less of it. Every other value is ignored, so a typo cannot ask for a window the model does not have. |
MINIMAX_CODE_MAX_INPUT_TOKENS |
1000000 |
open-sse/executors/minimaxCodeGateway.ts |
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, because a refusal of the gateway locks the model out of the fallbacks. The default is the context window of the gateway (1000000); this value can lower that ceiling, never raise it above the window. |
MINIMAX_CODE_MAX_TOKENS |
8192 |
open-sse/executors/minimaxCodeGateway.ts |
Maximum number of tokens the managed gateway may answer with. |
MINIMAX_CODE_AUTH_FILE |
~/.minimax/auth/prod/<region>/mcode-public/auth.json |
open-sse/executors/minimaxCodeGateway.ts |
Path of the MiniMax Code auth profile that holds the access and refresh token. |
MINIMAX_CODE_PROFILE_DIR |
~/.minimax |
open-sse/executors/minimaxCodeGateway.ts |
Directory of the MiniMax Code profile that holds the auth profile. |
MINIMAX_CODE_AUTH_RECORD |
(newest generation) | open-sse/executors/minimaxCodeGateway.ts |
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_REGION |
en |
open-sse/executors/minimaxCodeGateway.ts |
Region of the MiniMax account. It decides the account endpoint that refreshes the token and the profile directory the credential is read from. |
HERMES_HOME |
~/.hermes |
src/lib/cli-helper/config-generator/hermesHome.ts |
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). |
WHYCODES_HOME |
~/.whycodes |
src/lib/cli-helper/config-generator/whycodesHome.ts |
WhyCodes instance root where OmniRoute reads/writes config.toml. Same env var WhyCodes reads; defaults to ~/.whycodes (%USERPROFILE%\.whycodes on Windows). |
CLI Profile Auto-Sync
These feature flags are opt-in and default off. They can also be toggled from the CLI Code dashboard.
| Variable | Default | Source File | Description |
|---|---|---|---|
OMNIROUTE_AUTO_SYNC_CODEX_PROFILES |
false |
src/shared/constants/featureFlagDefinitions.ts |
After a provider model sync, automatically rewrites ~/.codex/*.config.toml profile files from the live catalog. Requires CLI_ALLOW_CONFIG_WRITES; never changes the active/default Codex config, auth, Codex-lb settings, or provider choice. |
OMNIROUTE_AUTO_SYNC_CLAUDE_PROFILES |
false |
src/shared/constants/featureFlagDefinitions.ts |
After a provider model sync, automatically rewrites ~/.claude/profiles/<name>/settings.json Claude Code profile files from the live catalog. Requires CLI_ALLOW_CONFIG_WRITES; never changes the active/default Claude config, auth, or provider choice. |
Docker Example
# Mount host binaries into the container and tell OmniRoute where they are:
CLI_EXTRA_PATHS=/host-cli/bin
CLI_CONFIG_HOME=/host-home
CLI_ALLOW_CONFIG_WRITES=true
CLI_CLAUDE_BIN=/host-cli/bin/claude
CLI_CONFIG_HOME only takes effect when the path is actually bind-mounted from
the host — pair it with mounts like ~/.codex:/host-home/.codex:rw (see the
host profile in docker-compose.yml). A path that is neither inside the
container user's home nor a bind mount is ignored, because writing there would
be discarded when the container is recreated.
The image runs as USER node, so an unmounted /root is not a valid
override.
| Variable | Default | Source File | Description |
|---|---|---|---|
OMNIROUTE_CONTAINER |
(auto) | src/shared/utils/containerEnv.ts |
Force container detection on (1/true) or off (0/false). Only needed on runtimes the auto-detection misses. |
OMNIROUTE_ALLOW_CONTAINER_CONFIG_WRITE |
false |
src/shared/services/cliRuntime.ts |
Allow CLI-tool config writes into an unmounted container path anyway. The CLI equivalent is --allow-container-write. |
DOCKER_UPDATE_TRIGGER_FILE |
unset | src/lib/system/autoUpdate.ts |
Docker image only: dashboard Update Now writes a JSON request to this file (must be inside DATA_DIR) for a host-side watcher to pull and recreate the container. See the Docker Guide. |
CLI Binary (omniroute) helpers
These variables tune the omniroute CLI binary's own behavior (not the sidecar
detection above).
| Variable | Default | Source File | Description |
|---|---|---|---|
OMNIROUTE_LANG |
(system) | bin/cli/i18n.mjs |
Force CLI output language. BCP-47 locale (e.g. en, pt-BR). Overrides system locale env vars (LC_ALL, LC_MESSAGES). |
OMNIROUTE_SHOW_LOG |
(unset) | bin/cli/runtime/processSupervisor.mjs |
Set to 1 to forward server stdout/stderr to the terminal in supervised mode. Equivalent to --log flag on omniroute serve. |
OMNIROUTE_CLI_TOKEN |
(unset) | bin/cli/api.mjs |
Machine-auth token injected as x-omniroute-cli-token header. Auto-generated in task 8.12. |
GEMINI_CLI_HOME |
(unset) | bin/cli/commands/setup-gemini.mjs |
Persistent Gemini home root; one-shot run uses a temporary isolated home. |
OMNIROUTE_CHILD_SIGNAL_TIMEOUT_MS |
5000 |
bin/cli/commands/run.mjs |
Grace period in milliseconds before force-killing a signalled CLI child. |
OMNIROUTE_CLI_SKIP_DEFAULT_DATA_ENV |
(unset) | bin/omniroute.mjs |
Set to 1 with an explicit DATA_DIR to skip the default user's data-directory environment file. |
OMNIROUTE_SYNC_TOKEN |
(unset) | bin/cli/commands/sync.mjs |
Sync token for omniroute sync bundle (GET /api/sync/bundle accepts only a sync token, not an API key). Equivalent to --token. |
OMNIROUTE_HTTP_TIMEOUT_MS |
30000 |
bin/cli/api.mjs |
Per-attempt HTTP timeout (ms) for CLI → server requests. |
OMNIROUTE_READY_TIMEOUT_MS |
60000 |
bin/cli/utils/pid.mjs |
Maximum time (ms) the CLI waits for the server health endpoint before printing a timeout warning. Useful for slow cold starts (e.g. Windows). Also settable via --ready-timeout. |
OMNIROUTE_VERBOSE |
0 |
bin/cli/api.mjs |
Set to 1 to print retry/backoff diagnostics to stderr during CLI commands. |
OMNIROUTE_PLUGIN_PATH |
(unset) | bin/cli/plugins.mjs |
Custom directory for CLI plugin discovery (omniroute-cmd-* packages). Defaults to ~/.omniroute/plugins/ when unset. CLI-only — it never reaches the server-side plugin scanner, which is pointed by OMNIROUTE_PLUGINS_DIR (section 2). |
OMNIROUTE_NO_UPDATE_NOTIFIER |
(unset) | bin/omniroute.mjs |
Suppress update checks when set to any non-empty value: the CLI notice at process exit and the dashboard "update available" banner (GET /api/system/version then skips the npm, GitHub and news lookups). The CLI notice also stays off in CI, quiet mode, and non-text output. |
OMNIROUTE_DOCTOR_LIVENESS_URL |
(derived) | bin/cli/commands/doctor.mjs |
Liveness URL probed by omniroute doctor. A programmatic livenessUrl option takes precedence; otherwise this value is used verbatim. Unset, the CLI derives the local dashboard's /api/health/degradation endpoint. |
OMNIROUTE_PROVIDER_CATALOG_PATH |
src/shared/constants/providers/ |
bin/cli/provider-catalog.mjs |
Provider catalog path used by CLI provider commands. A programmatic catalogPath option takes precedence. Absolute paths are used as-is; relative paths resolve from the project root. Unset, the CLI uses the provider constants directory, with the legacy providers.ts file as fallback. |
OMNIROUTE_PROVIDER_TEST_MODEL |
(provider default) | bin/cli/provider-test.mjs |
Global fallback model for CLI provider connection tests. Precedence is configured connection model, provider-specific model override, this value, then the provider's built-in test model. |
10. Internal Agent & MCP Integrations
| Variable | Default | Source File | Description |
|---|---|---|---|
OMNIROUTE_BASE_URL |
auto-detect | open-sse/mcp-server/server.ts |
Explicit URL for MCP/A2A tools to reach OmniRoute. Overrides localhost auto-detection. A2A skills fail instead of sending an API key to this URL (or the BASE_URL it falls back to) when it is plain http to a public address, a dotted public hostname or a cloud-metadata host, or holds credentials: use https, or http to loopback, a container or service name, or a private address. |
OMNIROUTE_API_KEY |
(unset) | MCP/A2A modules | API key for internal MCP tool calls. A2A skills send it only for a caller without an API key (dashboard session); a caller with a key acts with its own. |
OMNIROUTE_API_KEY_ID |
(unset) | open-sse/mcp-server/audit.ts |
Key ID for MCP audit log attribution. |
ROUTER_API_KEY |
(unset) | Legacy | Legacy alias for OMNIROUTE_API_KEY. |
OMNIROUTE_A2A_HISTORY_RETENTION_DAYS |
30 |
src/lib/a2a/taskManager.ts |
Days of A2A task history kept in the local database before the daily purge deletes a row. Unset, non-numeric, or <= 0 falls back to 30. |
OMNIROUTE_A2A_MEMORY_HITS |
1 |
src/lib/a2a/taskExecution.ts |
Kill-switch for the A2A memory-hits observability feature. Set to 0 to skip the memory recall lookup for a task entirely; any other value (including unset) keeps it enabled. |
OMNIROUTE_ISSUE_AGENT_ENABLED |
false |
src/app/api/issue-agent/runs/route.ts |
Enables the offline/local Issue Agent recorded-triage endpoint. Leave disabled unless explicitly running local recorded-triage workflows. |
OMNIROUTE_ISSUE_AGENT_TIMEOUT_MS |
(unset) | src/lib/issueAgent/execution.ts |
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. |
OMNIROUTE_CONTEXT |
(active context) | bin/cli/program.mjs, bin/cli/api.mjs |
CLI remote-mode context/profile for omniroute commands; overrides the active context in the local contexts store. Equivalent to --context <name>. |
OMNIROUTE_CONTEXT_KEYCHAIN_DISABLED |
0 |
bin/cli/contexts.mjs |
Disable the optional keytar OS-keychain backend for CLI context credentials. When enabled, credentials remain in config.json mode 0600 and the CLI emits a one-time fallback warning; intended for deliberate headless/container operation. |
OMNIROUTE_MCP_ENFORCE_SCOPES |
false |
open-sse/mcp-server/server.ts |
Enforce scope-based access control on MCP tool calls. |
OMNIROUTE_MCP_SCOPES |
(all) | open-sse/mcp-server/server.ts |
Comma-separated scopes: admin, combos, health, models, routing, budget, metrics, pricing, memory, skills. |
OMNIROUTE_PPLX_RESEARCH_ENABLED |
0 |
open-sse/mcp-server/tools/perplexityResearch.ts |
Register the Perplexity Deep Research MCP tool. Only 1 registers it; anything else leaves it off. |
OMNIROUTE_MCP_COMPRESS_DESCRIPTIONS |
false |
open-sse/mcp-server/descriptionCompressor.ts |
Compress MCP tool descriptions before serializing the manifest. Enable values: 1, true, on. |
OMNIROUTE_MCP_DESCRIPTION_COMPRESSION |
rtk |
open-sse/mcp-server/descriptionCompressor.ts |
Compression algorithm/profile. Disable values: 0, false, off. |
OMNIROUTE_MCP_FETCH_TIMEOUT_MS |
10000 |
open-sse/mcp-server/fetchTimeout.ts |
Abort budget (ms) for MCP-server internal management reads (health, resilience, combos, quota, usage). |
OMNIROUTE_MCP_UPSTREAM_TIMEOUT_MS |
60000 |
open-sse/mcp-server/fetchTimeout.ts |
Abort budget (ms) for MCP hops that wait on a provider (route_request, web_search, web_fetch). |
OMNIROUTE_MCP_SESSION_IDLE_MS |
300000 |
open-sse/mcp-server/httpTransport.ts |
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. |
OMNIROUTE_CORPUS_CACHE_SIZE |
5 |
src/lib/localCorpus/configured.ts |
Maximum number of local-corpus index instances cached in memory (LRU, one per indexed root directory). Clamped to a minimum of 1. |
MODEL_SYNC_INTERVAL_HOURS |
6 |
src/shared/services/modelSyncScheduler.ts |
Model catalog sync interval in hours. |
PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES |
70 |
src/lib/usage/providerLimits.ts |
Provider rate-limit and quota polling interval. |
PROVIDER_LIMITS_SYNC_SPACING_MS |
1500 |
src/lib/usage/providerLimits.ts |
Gap (ms) between consecutive OAuth quota fetches in a bulk sync; OAuth connections are fetched one at a time to avoid bursting an upstream. 0 opts out (concurrent). |
OMNIROUTE_QUOTA_FETCH_MIN_INTERVAL_MS |
250 |
open-sse/services/quotaFetchThrottle.ts |
Min interval (ms) between consecutive upstream quota fetches on the per-request preflight/monitor path; spaces concurrent network calls so many accounts on one IP don't burst the upstream. Wired into the Codex (/wham/usage), DeepSeek, Bailian (both fetch sites), OpenCode, and Crof quota fetchers (#6009, #6911). The generic usage.ts::getUsageForProvider dispatch path (github/glm/minimax/nanogpt/xai/etc.) is not yet covered — tracked separately. Cache hits unaffected. 0 disables; clamped 0..60000. |
OMNIROUTE_QUOTA_FETCH_JITTER_MS |
120 |
open-sse/services/quotaFetchThrottle.ts |
Additional per-request random spacing (ms), sampled at each reserved upstream quota fetch. Defaults to 120; clamped 0..60000; 0 removes only jitter. Set OMNIROUTE_QUOTA_FETCH_MIN_INTERVAL_MS=0 to disable the entire throttle. Jitter does not guarantee prevention of upstream bans. |
CODEX_QUOTA_FETCH_TIMEOUT_MS |
8000 |
open-sse/services/codexQuotaFetcher.ts |
Timeout (ms) for a single Codex quota fetch (chatgpt.com/backend-api/wham/usage). The preflight waits for this fetch before sending the request. After a timeout or transport error, the last snapshot from the past 15 minutes is reused unless its window is exhausted or has reset; with none, the quota is unknown, so a paid-credit account is skipped for that request and no cooldown is persisted. Accepts a positive integer up to 2147483647; any other value falls back to the default. |
PROVIDER_LIMITS_POST_USAGE_REFRESH_DELAY_MS |
5000 |
src/lib/usage/providerLimits.ts |
Delay (ms) before refreshing provider limits after a real usage event, giving the upstream quota API time to register consumption. |
OMNIROUTE_LOGIN_BROWSER_PATH |
auto-detect | open-sse/services/adobeFireflyBrowserLogin.ts |
Absolute path to a system Chrome or Edge executable used for interactive Adobe Firefly sign-in and off-screen renewal. |
ADOBE_FIREFLY_BROWSER_REFRESH |
enabled | open-sse/services/adobeFireflySession.ts |
Keeps IMS and browser-risk state fresh with account-scoped Chrome CDP sessions. Set to 0 to disable browser renewal. |
ADOBE_FIREFLY_SESSION_DISK |
enabled | open-sse/services/adobeFireflySession.ts |
Persists repaired Adobe sessions under DATA_DIR across process restarts. Set to 0 to keep sessions memory-only. |
ADOBE_FIREFLY_MIN_SUBMIT_GAP_MS |
12000 |
open-sse/services/adobeFireflySession.ts |
Minimum spacing in milliseconds between Adobe Firefly generate submissions; 0 disables spacing. |
ADOBE_FIREFLY_BATCH_EXTRA_GAP_MS |
15000 |
open-sse/services/adobeFireflySession.ts |
Extra quiet period in milliseconds after every third successful Adobe submission. |
ADOBE_FIREFLY_SUBMIT_BASE_DELAY_MS |
8000 |
open-sse/services/adobeFireflyClient.ts |
Base backoff in milliseconds after transient Adobe 408 responses; combined with submit spacing across at most five attempts. |
MEGABRAIN_API_URL |
https://api.getmegabrain.com |
open-sse/services/usage/megabrain.ts |
Base URL for the MegaBrain plan's session and weekly limits in Provider Limits (authenticated with the connection's OAuth token or mb-v1 API key); override only for a relay or test fixture. |
OMNIROUTE_DISABLE_BACKGROUND_SERVICES |
false |
src/instrumentation-node.ts |
Disable all background services: quota refresh, provider-limits sync, connection recovery, credential health, cloud/model/free-proxy/proxy-health sync, retention cleanup, scheduled VACUUM and the settings hot-reload poll. Useful for CI/test; on a long-running install, connections do not auto-recover and the database keeps growing. |
OMNIROUTE_HEADLESS |
(unset) | src/lib/system/headless.ts |
Proxy-engine-only boot: skips optional subsystems, /dashboard → 404. Same as omniroute serve --headless. See HEADLESS.md. |
OMNIROUTE_ENABLE_RUNTIME_BACKGROUND_TASKS |
(unset) | src/lib/config/runtimeSettings.ts |
Force background tasks on under automated test detection. Set 1 to override the test heuristic. |
OMNIROUTE_BUDGET_RESET_JOB_INTERVAL_MS |
600000 |
src/lib/jobs/budgetResetJob.ts |
Budget reset check cadence (ms). Floor 10000. |
OMNIROUTE_CONNECTION_RECOVERY_INTERVAL_MS |
60000 |
src/lib/quota/connectionRecovery.ts |
Proactive connection-cooldown recovery cadence (ms): re-validates connections whose transient rate_limited_until has elapsed, off the request hot path. Floor 5000. |
OMNIROUTE_DISABLE_CONNECTION_RECOVERY |
false |
src/lib/quota/connectionRecovery.ts |
Disable the proactive connection-cooldown recovery scheduler (lazy recovery in getProviderCredentials still applies). |
OMNIROUTE_REASONING_CACHE_CLEANUP_INTERVAL_MS |
1800000 |
src/lib/jobs/reasoningCacheCleanupJob.ts |
Reasoning cache cleanup cadence (ms). Floor 60000. |
OMNIROUTE_REASONING_MIN_BUDGET |
unset (disabled) | open-sse/services/reasoningTokenBuffer.ts |
Opt-in floor for thinking-model output budgets: caller max_tokens in [256, floor) is raised to the floor (capped by the model output cap). Unset = client budgets never enlarged (#9507). |
OMNIROUTE_REASONING_EFFORT_PROBE_PROVIDERS |
unset (disabled) | open-sse/services/learnedReasoningEffortCaps.ts |
Opt-in, comma-separated provider ids (or *): when a reasoning_effort 400/422 names no accepted set, retry once one tier lower (never below low) and learn that tier only if the probe is answered (#14895). |
OMNIROUTE_LOG_EXPORT_CRON |
0 * * * * |
src/lib/jobs/logExportJob.ts |
Cron expression (UTC) for the call-log export job that drains every enabled log-export destination. Prefer */5 * * * * when exporting bodies. |
OMNIROUTE_LOG_EXPORT_RUN_TIMEOUT_MS |
900000 |
src/lib/logExport/childRunner.ts |
Per-destination child wall-clock timeout in milliseconds. Timeout records failure and kills the process without advancing the unacknowledged batch. Invalid/non-positive/non-integer values use the default. |
OMNIROUTE_LOG_EXPORT_CHILD_MAX_OLD_SPACE_MB |
1024 |
src/lib/logExport/childRunner.ts |
Node export child V8 old-space limit in MB (not total RSS). Default leaves headroom for 500 rows of capped artifacts with bodies; oversized batches may still exhaust the child heap. Failure advises lowering batch size or raising this limit. Invalid/non-positive/non-integer values use the default. Bun exports fall back in-process without this limit. |
OMNIROUTE_CONFIG_HOT_RELOAD_MS |
5000 |
src/lib/config/hotReload.ts |
Polling interval (ms) for config hot-reload. Lower than 1000 is rejected. |
OMNIROUTE_DISABLE_REDIS_AUTH_CACHE |
(enabled) | src/lib/db/apiKeys.ts |
Set 1 to bypass the Redis-backed API-key auth cache (forces DB reads). |
OMNIROUTE_RTK_TRUST_PROJECT_FILTERS |
0 |
open-sse/services/compression/engines/rtk/filterLoader.ts |
Trust user-managed RTK project filter rules without strict signature checks. |
OMNIROUTE_LITE_MAX_TOOL_LENGTH |
2000 |
open-sse/services/compression/lite.ts |
Character cap for Lite proactive tool-result truncation when lite.maxToolLength is unset. Range 256–1000000. Dashboard setting wins over this env. |
OMNI_COMPRESSION_WORKERS |
2 |
open-sse/services/compression/compressionWorkerPool.ts |
Maximum concurrent synchronous RTK/Caveman workers; excess jobs wait FIFO. |
OMNI_COMPRESSION_WORKER_TIMEOUT_MS |
120000 |
open-sse/services/compression/compressionWorkerPool.ts |
Per-job timeout in milliseconds. Timed-out workers are terminated and the request fails open unchanged. |
OMNI_COMPRESSION_WORKER_IDLE_MS |
60000 |
open-sse/services/compression/compressionWorkerPool.ts |
Idle lifetime in milliseconds before an unused compression worker is terminated. |
OMNI_COMPRESSION_WORKER_MAX_OLD_MB |
1024 |
open-sse/services/compression/compressionWorkerPool.ts |
V8 old-generation heap cap in MB for each compression worker, all modes (floor 128). A job that exceeds it fails open (uncompressed) instead of growing the gateway heap. |
COMPRESSION_PIPELINE_BREAKER_ENABLED |
false |
open-sse/services/compression/pipelineEngineBreaker.ts |
T02 stacked-pipeline per-engine circuit-breaker master switch. Opt-in (default off) — when on, an engine that throws repeatedly across requests is skipped (fail-open) for a cooldown; off = byte-identical legacy behavior. |
COMPRESSION_PIPELINE_BREAKER_THRESHOLD |
3 |
open-sse/services/compression/pipelineEngineBreaker.ts |
Consecutive cross-request failures before an engine's breaker opens. |
COMPRESSION_PIPELINE_BREAKER_COOLDOWN_MS |
30000 |
open-sse/services/compression/pipelineEngineBreaker.ts |
Milliseconds an opened engine stays skipped before a half-open probe. |
COMPRESSION_CCR_RETRIEVAL_RAMP_FACTOR |
2 |
open-sse/services/compression/engines/ccr/index.ts |
T08/H8 CCR retrieval-feedback ramp: each prior retrieval of a stored block raises its effective minChars linearly (frequently-retrieved content compresses less; >=3 retrievals = never compressed). 1 disables the ramp (binary skip at the threshold only). |
COMPRESSION_CCR_DURABLE_STORE |
true |
open-sse/services/compression/engines/ccr/index.ts |
CCR durable block store (#9061). Backs the in-memory store with SQLite so a block survives LRU eviction, the TTL, a restart, or a retrieve landing on another instance. Set false to keep blocks in memory only. Blocks over 512KB and cloud runtimes stay memory-only regardless. |
COMPRESSION_PREFIX_FREEZE_ENABLED |
false |
open-sse/services/compression/prefixFreeze.ts |
T08/H5 usage-observed prefix freeze master switch. Opt-in (default off) — when on, a system prompt observed >= the threshold is treated as a stable cacheable prefix and preserved from compression even for providers the static cache heuristic misses (freeze only preserves, never mutates). |
COMPRESSION_PREFIX_FREEZE_THRESHOLD |
3 |
open-sse/services/compression/prefixFreeze.ts |
Observations of a system prompt before it is treated as a frozen stable prefix. |
OMNIROUTE_BOOTSTRAPPED |
false |
src/app/(dashboard)/dashboard/page.tsx |
Set true by bootstrap script after initial setup. Controls setup wizard visibility. |
OMNIROUTE_ALLOW_BODY_PROJECT_OVERRIDE |
0 |
open-sse/executors/antigravity.ts |
Escape hatch: allow request body to override the Antigravity project field. |
ANTIGRAVITY_CREDITS |
off |
open-sse/services/antigravityCredits.ts |
Google One AI credits policy: off never injects credits, retry injects once after an eligible quota 429, and always injects on the first request. |
OMNIROUTE_ANTIGRAVITY_TIMING_TELEMETRY |
false |
open-sse/executors/antigravity/executeAttempt.ts |
Opt-in sanitized per-physical-send timing: account idle, in-flight requests, time to headers and first meaningful SSE content. No prompts, credentials, or upstream URLs in logs. |
ANTIGRAVITY_MAX_429_ATTEMPTS |
2 |
open-sse/services/antigravity429Guard.ts |
Upstream 429s tolerated per Antigravity (agy/antigravity) request across all hosts (1–12) before the 429 goes back to the caller. A body that spent it is answered locally on re-send (2 min, doubling to 30 min, or the upstream retry hint), and the chat handler does not restart the request after that 429. |
OMNIROUTE_PREFERRED_ACCOUNT_FAILOVER_ENABLED |
false |
src/sse/services/preferredConnectionFailover.ts |
Opt-in response-start timeout on API-key-preferred connections across all providers. Default 20 s; Antigravity/agy 5 s, Gemini 3.8 Flash 12 s. Only with eligible sibling; at most one hop, no shared-account cooldown. Disabled by default. |
ANTIGRAVITY_ALLOW_SIGNATURE_BYPASS |
0 |
open-sse/translator/request/openai-to-gemini.ts |
Allow the Antigravity request translator to skip its strict CLI request-signature validation when the upstream refuses real signatures (debug/antiquated-CLI mode). Non-zero enables the bypass. |
AGY_TOKEN_FILE |
~/.gemini/antigravity-cli/antigravity-oauth-token |
src/app/api/providers/agy-auth/apply-local/route.ts |
Override the Antigravity CLI (agy) token-file path for the auto-detect local login import. |
OAuth CLI Bridge (Internal)
| Variable | Default | Source File | Description |
|---|---|---|---|
OMNIROUTE_SERVER |
auto-detect | src/lib/oauth/config/index.ts |
Server URL for CLI↔OmniRoute auth bridge. |
OMNIROUTE_TOKEN |
(unset) | src/lib/oauth/config/index.ts |
Auth token for CLI bridge. |
OMNIROUTE_USER_ID |
cli |
src/lib/oauth/config/index.ts |
User ID for CLI bridge sessions. |
SERVER_URL |
(unset) | src/lib/oauth/config/index.ts |
Legacy alias for OMNIROUTE_SERVER. |
CLI_TOKEN |
(unset) | src/lib/oauth/config/index.ts |
Legacy alias for OMNIROUTE_TOKEN. |
CLI_USER_ID |
(unset) | src/lib/oauth/config/index.ts |
Legacy alias for OMNIROUTE_USER_ID. |
11. OAuth Provider Credentials
Passive Codex token refresh
OMNIROUTE_TOKEN_REFRESH_PASSIVE_PROVIDERS set to codex makes this instance a consumer
of synchronized Codex credentials, not a refresh-token rotation owner. The empty
or unset default preserves normal refresh behaviour. Comma-separated values are
trimmed and case-insensitive; cx is an alias for codex. Unsupported providers
fail startup validation. Other providers are unchanged.
At existing refresh points, the instance bypasses the connection read cache and
adopts only a different, unexpired access token. Tokens rejected upstream during
the request cannot qualify again after synchronization rolls back: the request
credentials hold at most four SHA-256 fingerprints, discarded with that request.
Only token fields are adopted, so request-local provider metadata survives. No
adopted credentials are persisted. If no replacement exists, refresh_disabled
is non-terminal and does not count toward the token-refresh circuit breaker.
Real upstream 401/403 responses retain normal failure accounting, exponential
cooldown and client errors; account-deactivation signals still lock permanently.
Manual dashboard/API refresh returns 409 with code refresh_disabled and an
instruction to refresh on the active instance and synchronize. Implicit refreshes
(chat, usage, health checks and import validation) do not surface that error; on-demand
usage 401 recovery retries once with an adopted synchronized token.
Codex auth imports store the supplied tokens without a refresh-token exchange;
new OAuth logins are unchanged. No pre-dispatch synchronization is added outside
the existing proactive refresh path.
Keep exactly one rotation owner and arrange token synchronization separately,
before access tokens expire (default proactive lead: five minutes). This option
is not a distributed lock, database replication or a shared SQLite deployment.
Source: open-sse/services/tokenRefresh/passiveCodex.ts.
Built-in credentials for localhost development. For remote deployments, register your own at each provider's developer console.
| Variable | Provider | Notes |
|---|---|---|
CLAUDE_OAUTH_CLIENT_ID |
Claude Code (Anthropic) | Public client — no secret needed. |
CLAUDE_CODE_REDIRECT_URI |
Claude Code | Override redirect URI. Default: https://platform.claude.com/oauth/code/callback |
CODEX_OAUTH_CLIENT_ID |
Codex / OpenAI | Public client. |
GEMINI_OAUTH_CLIENT_ID |
Gemini (Google) | Requires matching _SECRET. |
GEMINI_OAUTH_CLIENT_SECRET |
Gemini (Google) | — |
KIMI_CODING_OAUTH_CLIENT_ID |
Kimi Coding (Moonshot) | Public client. |
MUSE_CODE_OAUTH_CLIENT_ID |
Muse Code (Meta) | Optional override for the public Muse CLI device-flow client id. Leave unset to use the baked-in public client. |
ANTIGRAVITY_OAUTH_CLIENT_ID |
Antigravity (Google) | Requires matching _SECRET. |
ANTIGRAVITY_OAUTH_CLIENT_SECRET |
Antigravity (Google) | — |
GITHUB_OAUTH_CLIENT_ID |
GitHub Copilot | Public client. |
GHE_COPILOT_OAUTH_CLIENT_ID |
GHE Copilot | Optional override for GitHub Enterprise Copilot's OAuth client id. Falls back to GITHUB_OAUTH_CLIENT_ID's public default when unset. |
COPILOT_INTEGRATION_ID |
GitHub Copilot | Optional override for the GitHub Copilot client integration ID sent in Copilot-Integration-Id and Editor-Plugin-Version headers. Defaults to copilot-developer-cli. |
WINDSURF_API_KEY |
Windsurf / Devin (v3.8) | API key fallback used by open-sse/executors/devin-cli.ts when no per-connection credential is available. Optional. |
CLI_DEVIN_BIN |
Devin CLI (v3.8) | Custom path to the Devin CLI binary (devin). Resolved by open-sse/executors/devin-cli.ts. |
GITLAB_DUO_OAUTH_CLIENT_ID |
GitLab Duo (v3.8) | OAuth client ID for GitLab Duo. Register an app at https://gitlab.com/-/profile/applications with redirect URI <NEXT_PUBLIC_BASE_URL>/callback and scopes api, read_user, openid, profile, email. Falls back to GITLAB_OAUTH_CLIENT_ID. |
GITLAB_DUO_OAUTH_CLIENT_SECRET |
GitLab Duo (v3.8) | OAuth client secret for GitLab Duo. Optional — PKCE flow does not require a secret. Falls back to GITLAB_OAUTH_CLIENT_SECRET. |
GITLAB_DUO_BASE_URL |
GitLab Duo (v3.8) | Override GitLab base URL (self-hosted GitLab). Defaults to https://gitlab.com. Falls back to GITLAB_BASE_URL. |
GITLAB_BASE_URL |
GitLab Duo (v3.8) | Legacy fallback for GITLAB_DUO_BASE_URL. Used when the _DUO_ variant is unset. |
GITLAB_OAUTH_CLIENT_ID |
GitLab Duo (v3.8) | Legacy fallback for GITLAB_DUO_OAUTH_CLIENT_ID consumed by src/lib/oauth/constants/oauth.ts. |
GITLAB_OAUTH_CLIENT_SECRET |
GitLab Duo (v3.8) | Legacy fallback for GITLAB_DUO_OAUTH_CLIENT_SECRET consumed by src/lib/oauth/constants/oauth.ts. |
QODER_OAUTH_CLIENT_SECRET |
Qoder | — |
QODER_OAUTH_AUTHORIZE_URL |
Qoder | Set to enable Qoder OAuth. |
QODER_OAUTH_TOKEN_URL |
Qoder | — |
QODER_OAUTH_USERINFO_URL |
Qoder | — |
QODER_OAUTH_CLIENT_ID |
Qoder | — |
QODER_PERSONAL_ACCESS_TOKEN |
Qoder | Direct API key fallback (bypasses OAuth). |
QODER_CLI_WORKSPACE |
Qoder | Workspace ID for Qoder CLI. |
OMNIROUTE_QODER_WORKSPACE |
Qoder | Alias for QODER_CLI_WORKSPACE. |
QODER_CLI_CONFIG_DIR |
Qoder | Override the Qoder CLI config dir (isolated PAT session, avoids clobbering a browser login). |
QODER_CLI_MAX_CONCURRENCY |
Qoder | Max concurrent qodercli runs (print spawns or ACP prompts); extra requests queue FIFO. Unset (default) = no cap. |
QODER_CLI_QUEUE_TIMEOUT_MS |
Qoder | How long a Qoder request waits for a qodercli slot (only with a cap set) before failing with 429 qodercli_busy + Retry-After. Default 120000. |
QODER_CLI_TRANSPORT |
Qoder | print (default) spawns qodercli --print per request; acp keeps one persistent qodercli --acp process per PAT. |
QODER_CLI_ACP_IDLE_TIMEOUT_MS |
Qoder | ACP transport: kill the persistent qodercli process after this much idle time. Default 600000. |
QODER_CLI_ACP_STARTUP_TIMEOUT_MS |
Qoder | ACP transport: deadline for qodercli to answer the ACP initialize. Default 60000. |
QODER_CLI_ACP_MAX_SESSIONS_PER_PROCESS |
Qoder | ACP transport: recycle the persistent qodercli process after this many sessions. Default 500. |
BLACKBOX_WEB_VALIDATED_TOKEN |
Blackbox Web | Frontend tk token to send as validated on /api/chat. Required when Blackbox enforces token matching; otherwise OmniRoute falls back to a random UUID. See issue #2252. |
VISION_BRIDGE_BASE_URL |
Vision Bridge guardrail | OpenAI-compatible base URL for non-Anthropic vision-bridge calls. Defaults to the legacy OpenAI URL env or api.openai.com. Point at OmniRoute's /v1 self-loop or any OpenAI-compat endpoint (Gemini OpenAI-compat, OpenRouter). Issue #2232. When the URL is OmniRoute's own /v1, the describe sub-request sends x-omniroute-admission-bypass: internal and authenticates with the resolved self-loop credential (sk_omniroute sentinel in local mode, or OMNIROUTE_API_KEY / ROUTER_API_KEY — #1350) so REQUIRE_API_KEY=true deployments work. |
VISION_BRIDGE_API_KEY |
Vision Bridge guardrail | API key for the URL above. Overrides per-provider OpenAI / Google env vars for non-Anthropic vision-bridge calls. Anthropic models keep their dedicated Anthropic key path. Issue #2232. |
OMNIROUTE_VISION_BRIDGE_NEGATIVE_CACHE_MS |
Vision Bridge guardrail | How long a "no usable candidate" routing outcome is cached, in ms (default 30000). Invalid or negative values fall back to the default; 0 disables the negative cache. Source: src/lib/guardrails/visionBridgeRouter.ts. |
OMNIROUTE_IMAGE_NORMALIZATION |
Vision image normalization | Opt-in (unset = off, zero behavior change; 1/true/on enables). Normalizes every inline (base64 data URI / Claude source.data) image in chat request bodies before dispatch: EXIF orientation applied, RGB (alpha flattened onto white), long edge <= 4096 px, total pixels <= ~4M; images that need a change are re-encoded as baseline JPEG (alpha-free PNGs stay lossless PNG), already-compliant RGB JPEG/PNG pass through untouched. Budgets are fixed. Targets Qwen2-VL-style vision pipelines that reject oversized/exotic images with 400 parse errors or zero-output hangs. Remote http(s) URLs are not downloaded; a missing sharp binary or an undecodable image passes through untouched (fail-open). Resizing a large image adds request latency. Source: open-sse/utils/visionImageNormalization.ts. |
Warning
- Go to Google Cloud Console → Credentials
- Create an OAuth 2.0 Client ID (type: "Web application")
- Add your server URL as Authorized redirect URI
- Replace the credential values in
.env.
12. Provider User-Agent Overrides
Override the User-Agent header sent to each upstream provider. This is dynamically resolved at runtime by the executor base class:
process.env[`${PROVIDER_ID}_USER_AGENT`]
Source:
open-sse/executors/base.ts→buildHeaders()
| Variable | Default Value | When to Update | |
|---|---|---|---|
CLAUDE_USER_AGENT |
claude-cli/2.1.280 (external, cli) |
When Anthropic releases a new CLI version | |
CLAUDE_DISABLE_TOOL_NAME_CLOAK |
false |
executors/base.ts + executors/cliproxyapi.ts |
Set to 1/true to forward third-party harness tool names verbatim to Anthropic on both Anthropic-bound paths (native OAuth and CLIProxyAPI). By default the executor deterministically aliases non-Claude-Code tool names (Claude Code canonical mapping where one exists, otherwise PascalCase) and reverses them on the response via _toolNameMap, so harnesses with snake_case tools are not refused as fingerprinted third-party clients. Debugging only. |
CODEX_USER_AGENT |
codex-cli/0.155.0 (Windows 10.0.26200; x64) |
When OpenAI updates the Codex CLI | |
CODEX_CLIENT_VERSION |
0.155.0 |
Override Codex client version independently of full UA string | |
GROK_CLI_CLIENT_VERSION |
1.0.41 |
Override x-grok-client-version for inference, model sync, and device-code OAuth, plus the default Grok CLI User-Agent for inference and model sync. Accepts SemVer with optional prerelease/build metadata, up to 128 characters after trimming surrounding whitespace. Unset, empty, invalid, or line-break-containing values use the shipped pin. The existing full inference User-Agent override retains precedence. |
|
CLAUDE_CODE_CLIENT_VERSION |
2.1.280 |
Override advertised Claude Code version independently of CLAUDE_USER_AGENT. Anthropic gates some models on this value (#12417). |
|
CLAUDE_CODE_CLIENT_BUILD_REVISION |
1e2 |
Override the 3-character suffix OmniRoute appends to cc_version= in the Claude billing block. Bump alongside CLAUDE_CODE_CLIENT_VERSION — pinning only the version advertises a version.revision pair no real binary emits. |
|
GITHUB_COPILOT_CLI_VERSION |
1.0.91 |
Override advertised Copilot CLI version independently of GITHUB_USER_AGENT |
|
GITHUB_USER_AGENT |
GitHubCopilotChat/0.54.0 |
When GitHub Copilot Chat updates | |
ANTIGRAVITY_CLI_CL |
(unset) | Override the Antigravity CLI (agy) Piper changelist reported as cl= in the CLI User-Agent. Not derivable from the version nor exposed by the public manifests; seeded per version from a live capture (1.4.4 → 1003595037). Unset on an unknown version omits cl= instead of advertising another build's changelist. |
|
KIRO_USER_AGENT |
AWS-SDK-JS/3.0.0 kiro-ide/1.0.0 |
When Kiro IDE updates | |
KIRO_OAUTH_CLIENT_ID |
kiro-cli |
Override the Kiro social device-code clientId (public id) |
|
KIRO_VERIFY_FULL_CRC |
false |
Opt-in: full per-frame message CRC validation on the Kiro event stream (debug corrupted streams) | |
KIRO_CREDIT_PRICE_USD |
0.02 |
USD per Kiro credit; converts meteringEvent credits into the exact per-request cost |
|
KIRO_REQUIRE_CREDITS |
false |
Fail a Kiro response that reports no credit metering instead of recording it unbilled | |
QODER_USER_AGENT |
Qoder-Cli |
When Qoder CLI updates | |
CURSOR_USER_AGENT |
Cursor/3.3 |
When Cursor updates |
Tip
You can add User-Agent overrides for any provider using the pattern
{PROVIDER_ID}_USER_AGENT. The executor dynamically constructs the env var name.
13. CLI Fingerprint Compatibility
When enabled, OmniRoute reorders HTTP headers and JSON body fields to match the exact signature of official CLI tools. This reduces the risk of account flagging while preserving your proxy IP.
Source: open-sse/config/cliFingerprints.ts, open-sse/executors/base.ts
Per-Provider
| Variable | Activation | Effect |
|---|---|---|
CLI_COMPAT_CODEX |
=1 |
Mimics Codex CLI request signature |
CLI_COMPAT_CLAUDE |
=1 |
Mimics Claude Code request signature |
CLI_COMPAT_GITHUB |
=1 |
Mimics GitHub Copilot request signature |
CLI_COMPAT_ANTIGRAVITY |
=1 |
Mimics Antigravity request signature |
CLI_COMPAT_CURSOR |
=1 |
Mimics Cursor request signature |
CLI_COMPAT_KIMI_CODING |
=1 |
Mimics Kimi Coding request signature |
CLI_COMPAT_KILOCODE |
=1 |
Mimics Kilo Code request signature |
CLI_COMPAT_CLINE |
=1 |
Mimics Cline request signature |
Global
| Variable | Activation | Effect |
|---|---|---|
CLI_COMPAT_ALL |
=1 |
Enable fingerprint compatibility for all providers at once. |
Kimi Coding CLI identity overrides
| Variable | Default | Source File | Description |
|---|---|---|---|
KIMI_CLI_VERSION |
1.36.0 |
src/lib/oauth/providers/kimi-coding.ts |
Override the Kimi CLI version sent during OAuth/API calls. |
KIMI_CODING_DEVICE_ID |
(captured default) | src/lib/oauth/providers/kimi-coding.ts |
Override the captured Kimi device ID used in client headers. |
Note
This feature works alongside the User-Agent overrides (§12). The fingerprint system handles header ordering and body field ordering, while User-Agent overrides handle the specific UA string. Both can be enabled independently.
14. API Key Providers
API keys for providers that use direct authentication. Preferred setup: Dashboard → Providers → Add API Key.
Setting via environment variables is an alternative for Docker or headless deployments.
Recognized pattern: {PROVIDER_ID}_API_KEY
| Variable | Provider |
|---|---|
DEEPSEEK_API_KEY |
DeepSeek |
NVIDIA_API_KEY |
NVIDIA NIM |
JINA_AI_API_KEY |
Jina AI (Foundation API + Reader fallback) |
JINA_API_KEY |
Jina AI (alias for JINA_AI_API_KEY) |
GEMINI_API_KEY |
Gemini (Google AI Studio) embeddings + chat fallback |
GOOGLE_API_KEY |
Gemini (alias for GEMINI_API_KEY) |
Note
Static
${PROVIDER}_API_KEYentries for Groq, xAI, Mistral, Perplexity, Together AI, Fireworks, Cerebras, Cohere, Nebius, and Qianfan were removed in v3.8.0 because the runtime no longer reads them — those providers rely exclusively on Dashboard /data/provider-credentials.json/ the encrypted DB. See the Audit: Removed / Dead Variables section at the bottom of this document for the migration path.
Tip
Keys set via the Dashboard are stored encrypted in SQLite and take precedence over environment variables.
Jina:
jina-ai/…embeddings, rerank, classify, segment, andjina-searchdo not bill a cluster env key when a dashboardjina-ai(or sharedjina-reader) connection exists —getProviderCredentialsis fill-first.JINA_AI_API_KEY/JINA_API_KEYare used only when no usable dashboard key exists. Call logs attribute the env fallback asconnection_id=env:JINA_AI_API_KEY. The Reader card (jina-reader,r.jina.ai) never serves/v1/embeddingsor/v1/rerank.Gemini:
gemini/gemini-embedding-2(aliasgoogle/gemini-embedding-2) uses the dashboardgeminiconnection first.GEMINI_API_KEY/GOOGLE_API_KEYare used only when no usable dashboard key exists. Call logs attribute the env fallback asconnection_id=env:GEMINI_API_KEY. Native multimodal traffic usesx-goog-api-keyagainst:embedContent/:batchEmbedContents— N OpenAIinputitems become N vectors.
15. Timeout Settings
All values are in milliseconds. Centralized resolution in src/shared/utils/runtimeTimeouts.ts.
Timeout Hierarchy
REQUEST_TIMEOUT_MS (global override)
├─→ FETCH_TIMEOUT_MS (upstream provider calls, default: 600000)
│ ├─→ FETCH_HEADERS_TIMEOUT_MS (inherits from FETCH_TIMEOUT_MS)
│ ├─→ FETCH_BODY_TIMEOUT_MS (inherits from FETCH_TIMEOUT_MS)
│ ├─→ TLS_CLIENT_TIMEOUT_MS (inherits from FETCH_TIMEOUT_MS)
│ │ └── TLS_FIRST_BYTE_WATCHDOG_MS (independent, default: 10000)
│ ├── RESPONSES_FIRST_BYTE_TIMEOUT_MS (independent, default: 15000)
│ ├── OPENCODE_RESPONSES_HEADERS_WAIT_MS (independent, default: 0 = off, suggested: 30000)
│ ├── OPENCODE_RESPONSES_HEADERS_WAIT_MAX_ROTATIONS (independent, default: 2)
│ ├── FETCH_CONNECT_TIMEOUT_MS (independent, default: 30000)
│ └── FETCH_KEEPALIVE_TIMEOUT_MS (independent, default: 4000)
├─→ STREAM_IDLE_TIMEOUT_MS (inherits from REQUEST_TIMEOUT_MS, default: 600000)
├─→ STREAM_ACTIVE_TIMEOUT_MS (independent; unset: 1260000, raised by declared budgets; set: hard cap; 0 disables)
├─→ STREAM_READINESS_TIMEOUT_MS (inherits from REQUEST_TIMEOUT_MS, default: 80000)
├─→ STREAM_READINESS_MAX_TIMEOUT_MS (caps adaptive readiness extensions, default: 180000)
└─→ API_BRIDGE_PROXY_TIMEOUT_MS (inherits from REQUEST_TIMEOUT_MS, default: 30000)
├─→ API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS (derived, default: 300000)
├── API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS (default: 60000)
├── API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS (default: 5000)
└── API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS (default: 0 = disabled)
| Variable | Default | Description |
|---|---|---|
REQUEST_TIMEOUT_MS |
(unset) | Global shortcut — overrides both FETCH_TIMEOUT_MS and STREAM_IDLE_TIMEOUT_MS defaults. |
FETCH_TIMEOUT_MS |
600000 |
Total HTTP request timeout for upstream provider calls. |
STREAM_IDLE_TIMEOUT_MS |
600000 |
Max silence between raw upstream bytes before aborting. Extended-thinking models rarely pause >90s. |
STREAM_ACTIVE_TIMEOUT_MS |
1260000 |
Maximum total active SSE stream lifetime; never resets on upstream bytes and is independent of REQUEST_TIMEOUT_MS. When unset, the default is the largest per-model timeoutMs in the registry (1200000, Codex) plus a 60000 margin, and a target that declares a longer budget (connection timeoutMs, then per-model, then provider-level, e.g. GLM's 3000000) gets that budget plus 60000 instead. A positive value is a hard cap for every target that declared budgets cannot raise. Set to 0 to disable for every target. |
OMNIROUTE_SSE_COMMENTS |
(disabled) | Whether OmniRoute may emit SSE : comment lines (e.g. the : keepalive heartbeat and x-omniroute-* metadata trailers). Disabled by default (#10524) since strict OpenAI-compatible clients JSON.parse every SSE line and crash on : comments; data: heartbeats are unaffected. Set on/true/1/yes to opt back in. Used by open-sse/utils/sseHeartbeat.ts. |
SSE_COALESCE_MS |
0 (off) |
Opt-in: merge consecutive Claude content_block_delta events (same block index and delta type) sent to Claude clients, flushing at least every N ms. Lossless; signature_delta and boundary events are never merged. Applies to every delta type unless a per-type variable below is set. Used by open-sse/utils/sseDeltaCoalesce.ts. |
SSE_COALESCE_THINKING_MS |
0 (off) |
Per-type override of SSE_COALESCE_MS for thinking_delta. |
SSE_COALESCE_TEXT_MS |
0 (off) |
Per-type override of SSE_COALESCE_MS for text_delta. |
SSE_COALESCE_INPUT_JSON_MS |
0 (off) |
Per-type override of SSE_COALESCE_MS for input_json_delta. |
SSE_FRAME_COALESCE_MS |
0 (off) |
Opt-in: batch SSE frames forwarded within N ms into one write to the client. The first frame and terminal frames ([DONE], message_stop, error, response.completed/failed/incomplete) are never delayed; with batching on, ITL measures batch gaps. Used by open-sse/utils/sseOutputSink.ts. |
SSE_STALL_WATCHDOG |
timer |
Byte-stall watchdog implementation for streamed responses. timer re-arms one timer per upstream chunk (fires exactly at the stall budget); interval keeps one check per stream with period clamp(budget/4, 1s, 5s), so a stall fires within budget + period. Used by open-sse/utils/streamStallWatchdog.ts. |
STREAM_READINESS_TIMEOUT_MS |
80000 |
Time to receive the first non-ping SSE event. Inherits REQUEST_TIMEOUT_MS when set. |
STREAM_READINESS_MAX_TIMEOUT_MS |
180000 |
Maximum adaptive first-event readiness window for large, tool-heavy, or high-reasoning streaming requests. |
OMNIROUTE_AGENT_GOAL_POLICY_ENABLED |
true |
Kill-switch for the /goal heuristic. Set false/0/off to fully disable detection — readiness timeouts and stream recovery are never elevated by request body/headers, mitigating client-controlled timeout amplification. |
OMNIROUTE_AGENT_GOAL_READINESS_MAX_TIMEOUT_MS |
600000 |
Maximum first-event readiness window for detected /goal agent runs or requests forced with x-omniroute-agent-goal. |
OMNIROUTE_AGENT_GOAL_STREAM_RECOVERY |
true |
Enable early stream recovery automatically for detected /goal agent runs. Set false/0/off to disable the goal-specific opt-in. This can only ADD recovery on top of the operator default — it never overrides an explicit STREAM_RECOVERY_ENABLED/DB settings opt-out. |
OMNIROUTE_CODEX_DROP_NONSTANDARD_EVENTS |
true |
Strip non-standard codex.* SSE events (e.g. codex.rate_limits) that break the OpenAI SDK's responses.stream() with a 502. Default ON (#11014). Set 0/false/no/off to forward them. |
OMNIROUTE_CODEX_APPSERVER_WS |
(unset) | Opt-in Codex app-server transport. WebSocket endpoint (ws:///wss://) of a local codex app-server sidecar. When set together with a token, Codex requests are routed over JSON-RPC to the sidecar instead of the HTTP Responses API. Also settable per-connection via providerSpecificData.codexAppServerUrl. Used by open-sse/executors/codex/appServerConfig.ts. |
OMNIROUTE_CODEX_APPSERVER_WS_TOKEN |
(unset) | Inline capability/bearer token presented to the app-server. Per-connection override: providerSpecificData.codexAppServerToken. |
OMNIROUTE_CODEX_APPSERVER_WS_TOKEN_FILE |
(unset) | Path to a file holding the app-server capability token (from codex app-server --ws-token-file). Used when OMNIROUTE_CODEX_APPSERVER_WS_TOKEN is unset. Per-connection override: providerSpecificData.codexAppServerTokenFile. |
OMNIROUTE_CODEX_APPSERVER_CWD |
/tmp |
Working directory the app-server turn runs in. Per-connection override: providerSpecificData.codexAppServerCwd. |
OMNIROUTE_CODEX_APPSERVER_APPROVAL |
(unset) | Approval policy passed to the app-server turn (e.g. never, on-request). Per-connection override: providerSpecificData.codexAppServerApprovalPolicy. |
OMNIROUTE_CODEX_APPSERVER_SANDBOX |
(unset) | 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; previously danger-full-access). Per-connection override: providerSpecificData.codexAppServerSandbox. |
OMNIROUTE_CODEX_APPSERVER_AUTO_APPROVE |
false |
Auto-approve the app-server's own approval prompts (command/file/permission execution on the host). Off by default — prompts are auto-denied; harness tool calls are unaffected (they travel the separate item/tool/call passthrough). Accepts true/1/yes. Per-connection override: providerSpecificData.codexAppServerAutoApprove. |
FETCH_HEADERS_TIMEOUT_MS |
= FETCH_TIMEOUT_MS |
Time to receive response headers. |
OMNIROUTE_FETCH_START_TIMEOUT_CAP_MS |
110000 |
Maximum wait for response headers on streaming requests (ms). 0 disables this cap; an explicit provider fetchStartTimeoutCapMs takes precedence. |
OMNIROUTE_CODEX_IMAGE_RESPONSE_START_TIMEOUT_MS |
600000 (10 min) |
First response-start deadline (ms) for paid Codex image-generation/edit POSTs, both direct and through an HTTP(S)/SOCKS proxy. These requests are never replayed after an ambiguous timeout or network failure. Edge relays (vercel/deno/cloudflare) also make one attempt, but keep their own OMNIROUTE_RELAY_FETCH_TIMEOUT_MS deadline. |
OMNIROUTE_DIRECT_HEADERS_TIMEOUT_MS |
30000 (30s) |
Maximum response-start wait (ms) for each direct no-proxy attempt. A timeout retries once on a fresh socket; set 0 to disable the bound and retain the previous behavior. |
OMNIROUTE_LOCAL_DIRECT_HEADERS_TIMEOUT_MS |
300000 (5 min) |
Response-start floor (ms) for direct no-proxy attempts whose target host is private/LAN/loopback (for example localhost, host.docker.internal, 192.168.x.x), so a native Ollama cold start is not cut off by the 30s default above. Acts as a floor: the effective wait is the larger of this value and OMNIROUTE_DIRECT_HEADERS_TIMEOUT_MS; 0 or an invalid value removes the local floor. Remote hosts are unaffected. |
OMNIROUTE_DIRECT_IMAGE_HEADERS_TIMEOUT_MS |
300000 (5 min) |
Response-start floor (ms) for direct no-proxy image requests: image generation/edit/variation endpoints (for example /v1/images/generations, /v1/images/edits) and request bodies that carry a hosted image_generation tool. Acts as a floor like the local floor above (it only raises the effective wait); 0 or an invalid value removes it. Codex image-generation/edit POSTs do not use it: they keep the dedicated OMNIROUTE_CODEX_IMAGE_RESPONSE_START_TIMEOUT_MS deadline. |
OMNIROUTE_DIRECT_HEADERS_VOLUME_ADAPTIVE |
1 |
Raise the direct response-start window by request payload tier: bodies over 512 KB get ×2, over 2 MB ×3, capped at 180 s and never lowering an already-higher floor (the operator override or the local/LAN floor above). Large contexts prefill proportionally to input size with no reasoning selector for the reasoning ceiling to key on, so the flat window cut healthy slow-prefill upstreams at exactly the floor. Set 0/false/off to pin the flat behavior. |
OMNIROUTE_DIRECT_RESPONSE_RETRY_TIMEOUT_MS |
600000 (10 min) |
Ceiling (ms) for the fresh-socket RETRY attempt after a pooled-attempt response-start timeout above (#13703). Applies only 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 identical 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; when the caller supplies no deadline signal at all, the retry keeps the flat floor unchanged. |
FETCH_BODY_TIMEOUT_MS |
= FETCH_TIMEOUT_MS |
Time to receive the full response body. |
FETCH_CONNECT_TIMEOUT_MS |
30000 |
TCP connection establishment timeout. |
FETCH_KEEPALIVE_TIMEOUT_MS |
4000 |
Keep-alive socket idle timeout. |
TLS_CLIENT_TIMEOUT_MS |
= FETCH_TIMEOUT_MS |
TLS fingerprint proxy (wreq-js) timeout. |
TLS_FIRST_BYTE_WATCHDOG_MS |
10000 |
Bounds time-to-first-byte on the wreq-js TLS-fingerprint transport's body specifically; TLS_CLIENT_TIMEOUT_MS alone cannot catch a stalled body since it resolves as soon as headers arrive (#12656). A timeout cancels the wreq reader and falls back to the direct/proxy dispatcher; 0 disables the watchdog. |
RESPONSES_FIRST_BYTE_TIMEOUT_MS |
15000 |
OpenCode executor only, and only while the OPENCODE_RESPONSES_STALL_ROTATION feature flag is on (default off): bounds the wait for the first body byte of a streamed Responses reply after its headers (#13484). A Responses stream opens with response.created, so silence past this window is a stall: the account is cooled down and the request rotates to the next account once; a second stall fails fast. 0 disables the guard even with the flag on. |
OPENCODE_RESPONSES_HEADERS_WAIT_MS |
0 (= off) |
OpenCode executor only: bounds the wait for upstream response headers on a streamed Responses call when another account is still available — a queued request stops waiting and moves on instead of holding the full headers window. Only streamed Responses calls are affected (the Responses stream opens with response.created, so silence there is a queue, not generation); chat completions and non-streamed calls are untouched, and the window only shortens the effective fetch-start ceiling, never extends it. Suggested value when enabling: 30000. 0 disables. |
OPENCODE_RESPONSES_HEADERS_WAIT_MAX_ROTATIONS |
2 |
OpenCode executor only: how many times per request the headers-wait bound above may move to the next account. The last remaining account always keeps the full headers window. |
OPENCODE_PARK_AND_RESUME |
false |
OpenCode executor only: park the request with a heartbeat after repeated transient 429s (or a fresh pool-strain marker), then replay one capped leg of up to 3 sequential accounts instead of fanning out the whole fleet (#13924). Off by default: every 429 rotates to the next account exactly as before. |
OPENCODE_PARK_REPLAY_SERVE_SETASIDE |
false |
OpenCode executor only: when every cooldown-ready account in the park-and-resume replay leg is set aside by the proxy-refusal memory, serve them anyway instead of replaying nothing (#14851, follow-up to #14750). Off by default: the replay leg is empty in that case, as before #14750. |
STREAM_READINESS_STALL_RETRY |
false |
Streaming chat only: when the first upstream body stalls before producing a usable event, issue one bounded second attempt through the same routing path with the same readiness budget and no account penalty. Off by default: a stalled first body fails the request without a retry. |
OPENCODE_POOL_RESELECT |
false |
OpenCode executor only: after a 429 from an egress-bucketed provider on a proxy-less account under an ambient pool context, ask the connection pool for another member for the next attempt instead of retrying the same egress address. Orders, never excludes: an exhausted pool keeps the current behavior. Off by default: every 429 rotates to the next account exactly as before. |
OPENCODE_POOL_STRAIN_MARKER_PATH |
(unset) | OpenCode executor only: override path of the pool-strain marker read before parking ({since, reason, ttl_s}, default /tmp/opencode-pool-strain.json, #13924). A fresh marker parks without recounting; absent or stale falls back to the burst counter. |
API_BRIDGE_PROXY_TIMEOUT_MS |
30000 |
Proxy hop timeout for /v1 bridge requests. |
FIRECRAWL_BASE_URL |
https://api.firecrawl.dev |
Point the Firecrawl web-fetch executor at a self-hosted instance (API key optional off-cloud). |
FIRECRAWL_TIMEOUT_MS |
30000 |
Per-request timeout for the Firecrawl web-fetch executor. |
TAVILY_BASE_URL |
(unset) | Base URL for the Tavily /usage quota fetcher (Provider Limits); ignored when it points at api.tavily.com. Unset falls back to the connection's base URL. |
API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS |
300000 |
Overall server request timeout for the bridge. |
API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS |
60000 |
Time to send response headers via the bridge. |
API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS |
5000 |
Bridge keep-alive idle timeout. |
API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS |
0 |
Raw socket timeout (0 = disabled). |
SHUTDOWN_TIMEOUT_MS |
30000 |
Grace period on SIGTERM/SIGINT before force-exit. |
OMNIROUTE_DEFAULT_FETCH_TIMEOUT_MS |
120000 |
Fallback used by src/shared/utils/fetchTimeout.ts when FETCH_TIMEOUT_MS is unset. |
OMNIROUTE_PROVIDER_PROBE_TIMEOUT_MS |
8000 |
Timeout (ms) for the validationRead and modelsProbe presets in src/shared/network/safeOutboundFetch.ts. Raise for slow endpoints (Cerebras, Cloudflare AI, Groq) to prevent flapping between active/error in the dashboard. Falls back to 8000ms for invalid (<1000) or non-numeric values. |
OMNIROUTE_RELAY_FETCH_TIMEOUT_MS |
25000 |
Relay-specific fetch timeout in open-sse/utils/proxyFetch.ts (#9158). A hung relay must fail before the client/agent timeout (~30s) so callers see a relay-specific failure instead of a generic upstream timeout. Capped at 29000 so it always fires first. |
OMNIROUTE_RETRY_BACKOFF_MS |
10 |
Shared retry backoff for the direct/relay/proxy retry-once paths in open-sse/utils/proxyFetch.ts (#9158). 0 = retry immediately. |
OMNIROUTE_CLAUDE_TLS_TIMEOUT_MS |
60000 |
Native wreq-js request timeout (claudeTlsClient.ts). |
OMNIROUTE_CLAUDE_TLS_GRACE_MS |
10000 |
Absolute JS hard-deadline grace added on top of the native timeout. |
OMNIROUTE_PPLX_TLS_TIMEOUT_MS |
30000 |
Native wreq-js request timeout (perplexityTlsClient.ts). |
OMNIROUTE_PPLX_TLS_GRACE_MS |
10000 |
Absolute JS hard-deadline grace added on top of the native timeout. |
OMNIROUTE_PPLX_SEARCH_HINT |
0 (off) |
Appends "You have built-in web search. Answer questions directly using search results." to the caller's system message (perplexity-web/protocol.ts). Off by default — Perplexity searches anyway, and the sentence leaks into replies as meta-commentary for coding clients. Set 1/true/yes/on to restore. |
OMNIROUTE_GROK_TLS_TIMEOUT_MS |
60000 |
Native wreq-js request timeout (grokTlsClient.ts). |
OMNIROUTE_GROK_TLS_GRACE_MS |
10000 |
Absolute JS hard-deadline grace added on top of the native timeout. |
OMNIROUTE_NOTION_TLS_TIMEOUT_MS |
30000 |
Native wreq-js request timeout (notionTlsClient.ts); notion-web raises it per request to 180000 for long generations. |
OMNIROUTE_NOTION_TLS_GRACE_MS |
10000 |
Absolute JS hard-deadline grace added on top of the native timeout. |
OMNIROUTE_BROWSER_POOL |
on |
Shared Playwright browser pool for browser-backed web-cookie chat (browserPool.ts); set off to disable. |
OBSCURA_BIN |
auto-detect |
Path to the obscura binary used as the primary engine by the browser pool and Cloudflare Playground executor (open-sse/services/obscura.ts); auto-detected from the system PATH when unset. |
OBSCURA_CDP_ENDPOINT |
(unset) | Point at an already-running Obscura (http://host:port) instead of spawning one; the module does not own that process (open-sse/services/obscura.ts). |
OBSCURA_PORT |
random free port |
Explicit port for the spawned obscura serve; a free port is chosen automatically when unset (open-sse/services/obscura.ts). |
WEB_COOKIE_USE_BROWSER |
0 |
Opt a web-cookie chat request into the browser-backed path (browserBackedChat.ts); 1 to enable. |
KIMI_WEB_BASE_URL |
https://www.kimi.ai |
Base URL for the Kimi Web (international kimi.ai Connect-RPC) executor (kimi-web.ts); override only for mirror/proxy endpoints. |
KIMI_WEB_CHAT_URL |
<KIMI_WEB_BASE_URL>/apiv2/kimi.gateway.chat.v1.ChatService/Chat |
Full chat endpoint for the Kimi Web executor (kimi-web.ts). |
OMNIROUTE_LOGIN_BROWSER_PATH |
(auto-detected) | Path to a system Chrome/Edge executable for the Adobe Firefly interactive browser sign-in (adobeFireflyBrowserLogin.ts); overrides per-OS auto-detection. |
OMNIROUTE_STANDALONE_DIR |
.build/ standalone output | Build-time override for the standalone output directory consumed by the post-build colocation step (scripts/build/colocate-standalone.mjs); build tooling, not runtime. |
Combo target attempts inherit the resolved upstream request timeout (FETCH_TIMEOUT_MS, or
REQUEST_TIMEOUT_MS when it supplies the fetch default). Set targetTimeoutMs in a combo,
combo defaults, or provider override only to make combo fallback faster; values above the
current upstream timeout are capped to the upstream timeout.
comboTimeoutMs is a separate whole-combo wall-clock budget across failover targets.
Leave it unset or 0 to keep unlimited iteration (a 10-minute hardcoded hang-stop in
comboPredicates.ts still applies). A positive value replaces that
safety net for the combo. Keep comboTimeoutMs longer than targetTimeoutMs so failover
still has time after a slow first target.
Circuit Breaker Thresholds
Provider-level circuit breaker tuning. Defaults reflect the scaled values used since v3.6 for 500+ connections.
| Variable | Default | Source File | Description |
|---|---|---|---|
OMNIROUTE_CIRCUIT_BREAKER_OAUTH_THRESHOLD |
8 |
open-sse/config/constants.ts |
Consecutive failure threshold for OAuth providers before the breaker trips. |
OMNIROUTE_CIRCUIT_BREAKER_OAUTH_RESET_MS |
60000 |
open-sse/config/constants.ts |
Reset window (ms) for OAuth provider breaker. |
OMNIROUTE_CIRCUIT_BREAKER_API_KEY_THRESHOLD |
12 |
open-sse/config/constants.ts |
Consecutive failure threshold for API-key providers. |
OMNIROUTE_CIRCUIT_BREAKER_API_KEY_RESET_MS |
30000 |
open-sse/config/constants.ts |
Reset window (ms) for API-key provider breaker. |
OMNIROUTE_CIRCUIT_BREAKER_LOCAL_THRESHOLD |
2 |
open-sse/config/constants.ts |
Consecutive failure threshold for local providers (Ollama, LM Studio, ...). |
OMNIROUTE_CIRCUIT_BREAKER_LOCAL_RESET_MS |
15000 |
open-sse/config/constants.ts |
Reset window (ms) for local provider breaker. |
OMNIROUTE_PROVIDER_BREAKER_OAUTH_FAILURE_THRESHOLD |
10 |
open-sse/config/constants.ts |
Provider-level breaker: failures within the window before the entire OAuth provider enters cooldown. |
OMNIROUTE_PROVIDER_BREAKER_OAUTH_FAILURE_WINDOW_MS |
900000 |
open-sse/config/constants.ts |
Provider-level breaker: rolling failure-count window (ms) for OAuth providers. |
OMNIROUTE_PROVIDER_BREAKER_OAUTH_COOLDOWN_MS |
300000 |
open-sse/config/constants.ts |
Provider-level breaker: cooldown (ms) once the OAuth provider threshold is reached. |
OMNIROUTE_PROVIDER_BREAKER_OAUTH_DEGRADATION_THRESHOLD |
5 |
open-sse/config/constants.ts |
OAuth provider enters DEGRADED at this many failures. |
OMNIROUTE_PROVIDER_BREAKER_OAUTH_MAX_BACKOFF_MULTIPLIER |
8 |
open-sse/config/constants.ts |
OAuth provider max resetTimeout escalation multiplier. |
OMNIROUTE_PROVIDER_BREAKER_OAUTH_BACKOFF_ESCALATION_COUNT |
2 |
open-sse/config/constants.ts |
OAuth provider escalates after this many open cycles. |
OMNIROUTE_PROVIDER_BREAKER_API_KEY_FAILURE_THRESHOLD |
15 |
open-sse/config/constants.ts |
Provider-level breaker: failures within the window before the entire API-key provider enters cooldown. |
OMNIROUTE_PROVIDER_BREAKER_API_KEY_FAILURE_WINDOW_MS |
1800000 |
open-sse/config/constants.ts |
Provider-level breaker: rolling failure-count window (ms) for API-key providers. |
OMNIROUTE_PROVIDER_BREAKER_API_KEY_COOLDOWN_MS |
600000 |
open-sse/config/constants.ts |
Provider-level breaker: cooldown (ms) once the API-key provider threshold is reached. |
OMNIROUTE_PROVIDER_BREAKER_API_KEY_DEGRADATION_THRESHOLD |
7 |
open-sse/config/constants.ts |
API-key provider enters DEGRADED at this many failures. |
OMNIROUTE_PROVIDER_BREAKER_API_KEY_MAX_BACKOFF_MULTIPLIER |
4 |
open-sse/config/constants.ts |
API-key provider max resetTimeout escalation multiplier. |
OMNIROUTE_PROVIDER_BREAKER_API_KEY_BACKOFF_ESCALATION_COUNT |
3 |
open-sse/config/constants.ts |
API-key provider escalates after this many open cycles. |
OMNIROUTE_PROVIDER_BREAKER_LOCAL_FAILURE_THRESHOLD |
2 |
open-sse/config/constants.ts |
Provider-level breaker: failures before the entire local provider enters cooldown. |
OMNIROUTE_PROVIDER_BREAKER_LOCAL_FAILURE_WINDOW_MS |
300000 |
open-sse/config/constants.ts |
Provider-level breaker: rolling failure-count window (ms) for local providers. |
OMNIROUTE_PROVIDER_BREAKER_LOCAL_COOLDOWN_MS |
60000 |
open-sse/config/constants.ts |
Provider-level breaker: cooldown (ms) once the local provider threshold is reached. |
OMNIROUTE_API_KEY_COOLDOWN_MS |
60000 |
open-sse/services/apiKeyRotator.ts |
Per-key cooldown (ms) applied by multi-key API-key rotation when an upstream 429 carries no Retry-After (#14573). Non-positive or non-numeric values fall back to the default. |
OMNIROUTE_AVALANCHE_PROTECTION_ENABLED |
false |
open-sse/services/accountFallback/antiAvalanche.ts |
Opt-in anti-avalanche guard: only an explicit true enables it. When on, a 429 that names a tokens-per-minute limit (and a context-overflow 400) stops the cascading failover across the provider's remaining keys. A quota-exhausted 429 keeps failing over however large the prompt is, and HTTP 413 is not affected (it keeps the #13350 retry-on-another-account behaviour). |
OMNIROUTE_AVALANCHE_BURST_COOLDOWN_MS |
60000 |
open-sse/services/accountFallback/antiAvalanche.ts |
Model-lockout cooldown (ms) applied when the guard fires, instead of the escalating lockout. A longer upstream reset always wins. Non-positive or non-numeric values fall back to the default. |
PIN_DROP_BACKOFF_LEVEL |
2 |
open-sse/services/combo.ts |
Backoff depth at which a context-cache pin's provider is deemed durably unhealthy and the pin is dropped for failover. |
PIN_DROP_GRACE_MS |
20000 |
open-sse/services/combo.ts |
Anti-flap window (ms) tolerating brief transient cooldowns before dropping a context-cache pin. |
Scenarios
| Scenario | Configuration |
|---|---|
| Long-running code generation | REQUEST_TIMEOUT_MS=900000 (15 min) |
| Bound total stream lifetime | STREAM_ACTIVE_TIMEOUT_MS=1260000 (21 min) |
| Fast-fail for production API | API_BRIDGE_PROXY_TIMEOUT_MS=10000 |
| Extended thinking models | STREAM_IDLE_TIMEOUT_MS=300000 (5 min between chunks) |
16. Logging
The logging system writes to both stdout and rotated log files. All configuration is read by src/lib/logEnv.ts.
| Variable | Default | Description |
|---|---|---|
APP_LOG_LEVEL |
info |
Minimum log level: debug, info, warn, error. |
APP_LOG_FORMAT |
text |
Output format: text (human-readable) or json (structured). |
APP_LOG_TO_FILE |
true |
Write logs to file alongside stdout. |
APP_LOG_FILE_PATH |
logs/application/app.log |
Log file path (relative to project root or DATA_DIR). |
APP_LOG_MAX_FILE_SIZE |
50M |
Max file size before rotation. Accepts: 50M, 1G, 512K, or plain bytes. |
APP_LOG_RETENTION_DAYS |
7 |
Days to keep rotated application log files. |
APP_LOG_MAX_FILES |
20 |
Maximum rotated log file backups. |
CALL_LOG_RETENTION_DAYS |
7 |
Days to keep request/call log entries in the database. |
CALL_LOG_MAX_ENTRIES |
10000 |
Max call log entries in the in-memory buffer. |
CALL_LOGS_TABLE_MAX_ROWS |
100000 |
Max rows in the call_logs SQLite table before pruning. |
MEDIA_STORE_MAX_MB |
2048 |
Size cap in MiB for the generated media kept under DATA_DIR/media. Past the cap the oldest files are removed first; the file just written always stays. A whole number above 0; any other value is ignored. Wins over the dashboard setting Settings > Storage > Media store size cap. Source: src/lib/media/mediaStore.ts. |
ENABLE_REQUEST_LOGS |
(unset) | Force detailed request logging on or off, overriding the dashboard setting. |
MAX_PENDING_REQUEST_AGE_MS |
3600000 (1 hour) |
Max age for orphaned active request log entries before in-memory cleanup. |
MAX_PENDING_DETAILS |
5000 |
Max pending details (positive integer); count cap: sweep; byte/map caps: insert. |
CALL_LOG_PIPELINE_CAPTURE_STREAM_CHUNKS |
false |
Store stream chunks in pipeline artifacts when call_log_pipeline_enabled=true. Opt-in (true) — off by default to save disk. |
CALL_LOG_PIPELINE_MAX_SIZE_KB |
512 |
Max pipeline call log artifact size in KB when call_log_pipeline_enabled=true. |
CALL_LOG_MIN_FREE_DISK_MB |
512 |
Minimum free disk space in MB on the volume that holds DATA_DIR/call_logs. Below it, call log artifact writes are skipped and the row shows detail_state missing. 0 turns the check off. A failed check never drops a log. |
PROXY_LOGS_TABLE_MAX_ROWS |
100000 |
Max rows in the proxy_logs SQLite table before pruning. |
PROXY_LOG_INCLUDE_IPS |
false |
Include client/egress IPs and account prefixes in [ProxyEgress] console logs. The dashboard/database proxy-log records retain full details. |
PROXY_LOG_FIRST_CHUNK_TIMING |
false |
Set to "true" or "1" to record first_chunk_ms (send start to first useful body byte) on proxy-log rows. Wraps each upstream body in a lazy passthrough stream and patches the row once the byte arrives; off by default so responses pass through untouched. |
APP_LOG_ROTATION_CHECK_INTERVAL_MS |
60000 (1 min) |
How often src/lib/logRotation.ts re-checks the active log file size. |
CHAT_LOG_TEXT_LIMIT |
65536 |
Max string length retained in chat log artifacts (default 64 KB). |
CHAT_LOG_ARRAY_TAIL_ITEMS |
128 |
Number of array items retained from the tail when truncating chat log payloads. |
CHAT_LOG_MAX_DEPTH |
6 |
Max nesting depth before chat log payloads are truncated. |
CHAT_LOG_MAX_OBJECT_KEYS |
80 |
Max object keys retained in chat log payloads (0 = unlimited). |
CHAT_LOG_MAX_BODY_KB |
1024 |
Whole request/response body size (KB) before it's replaced by a bare summary instead of the full clone. Raise this if long agentic conversations show a placeholder instead of the real messages in the dashboard. |
CHAT_DEBUG_FILE |
false |
When true, serializeArtifactForStorage skips size-based truncation. Debug only. |
17. Memory Optimization
| Variable | Default | Description |
|---|---|---|
OMNIROUTE_HEAP_DIAGNOSTICS_ENABLED |
0 (off) |
Set 1 to log V8 heap pressure metrics from src/lib/healthzLag.ts. Logs sizes and inflight count, never request content, traces or heap snapshots. Runs inside the event-loop stall recorder, so OMNIROUTE_EVENT_LOOP_STALL_THRESHOLD_MS=0 also turns it off. |
OMNIROUTE_HEAP_DIAGNOSTICS_THRESHOLD_MB |
900 |
Positive threshold for heapUsed (MiB) that triggers an opt-in diagnostic log. Invalid values use 900 MiB; high-heap messages are limited to once per 60 seconds. |
OMNIROUTE_MEMORY_MB |
auto (bare metal); 1024 in the Docker image |
Recommended Docker/standalone V8 heap limit (MB). When unset, calibrated dynamically (~35% of system RAM, clamped to [512, 4096]); 512 is only the floor when total memory can't be read. On run-standalone.mjs (Docker CMD), an explicit value is appended as --max-old-space-size and wins over a conflicting NODE_OPTIONS heap flag (V8 last-flag). omniroute serve still prefers an existing NODE_OPTIONS heap (#5238). Do not set both to different numbers — the process logs a warn naming both values and the winner. The official Docker image always sets 1024, so calibration never runs there. Coding-agent /v1/responses needs 8192–12288 plus cgroup headroom — see Docker Guide — runtime RAM. |
OMNIROUTE_RSS_PRESSURE_MB |
auto (max(3072, 2 × OMNIROUTE_MEMORY_MB); off when OMNIROUTE_MEMORY_MB is unset) |
open-sse/utils/resourcePressure.ts |
PROMPT_CACHE_MAX_SIZE |
50 |
Max cached system prompt entries. |
PROMPT_CACHE_MAX_BYTES |
2097152 (2 MB) |
Max total prompt cache size. |
PROMPT_CACHE_TTL_MS |
300000 (5 min) |
Prompt cache entry TTL. |
SEMANTIC_CACHE_MAX_SIZE |
100 |
Max cached temperature=0 responses. |
SEMANTIC_CACHE_MAX_BYTES |
4194304 (4 MB) |
Max total semantic cache size. |
SEMANTIC_CACHE_MAX_ENTRY_BYTES |
262144 (256 KB) |
Max size of one entry in the in-memory semantic cache. A larger answer is stored in SQLite only and never evicts other memory entries. |
SEMANTIC_CACHE_TTL_MS |
1800000 (30 min) |
Semantic cache entry TTL. |
OMNIROUTE_SEMANTIC_CACHE_PRUNE_INTERVAL_MS |
1800000 (30 min) |
SQLite prune interval. 0 disables startup and periodic runs; other values below 60000 fall back to the default. Values above 2147483647 ms clamp to Node's maximum timer delay, avoiding overflow to 1ms polling. First run after 1s; timers are unref'd and runs never overlap. |
OMNIROUTE_SEMANTIC_CACHE_PRUNE_BATCH_SIZE |
2000 |
Rows per SQLite prune DELETE, clamped to [100, 50000]; yields to the event loop between batches. |
OMNIROUTE_SEMANTIC_CACHE_PRUNE_MAX_BATCHES |
50 |
Shared DELETE batch budget per run across expiry and optional row-cap passes, clamped to [1, 10000]. Backlogs continue on later runs. |
OMNIROUTE_SEMANTIC_CACHE_MAX_ROWS |
0 |
Optional SQLite row cap (0 = none). After deleting expires_at <= the run-start ISO timestamp, evict oldest created_at, then rowid, including live rows, subject to the shared batch budget. Counts are truncated to integers (up to the safe-integer limit). Empty, non-numeric, non-finite or negative values for all four prune variables fall back to their defaults; fractions round down. Pruning does not change TTL, memory LRU or vector-cache behavior. |
OMNIROUTE_CORPUS_CACHE_SIZE |
5 |
Local-corpus roots that keep a live in-memory index at once (src/lib/localCorpus/configured.ts). LRU: at the limit the least-recently-used root's index is evicted and rebuilt on its next query. Clamped to a minimum of 1; a non-numeric value falls back to the default. |
STREAM_HISTORY_MAX |
50 |
Max recent stream events in the Dashboard live view buffer. |
CONTEXT_LENGTH_DEFAULT |
(unset) | Global context-length override (tokens) for every provider that has no CONTEXT_LENGTH_<PROVIDER> variable. When set, it replaces the catalog, dashboard override and registry values for those providers; when unset, OmniRoute uses its built-in chain, whose last resort is 128000. See Per-provider context length. |
USAGE_TOKEN_BUFFER |
100 |
Extra token headroom reserved when tracking usage quotas. |
Per-provider context length (CONTEXT_LENGTH_<PROVIDER>)
open-sse/services/contextManager.ts (getEnvOverride() / resolveTokenLimit()) also reads a
per-provider form whose name is built from the provider ID at runtime, so it cannot be
listed row by row in the table above or in .env.example.
Name. CONTEXT_LENGTH_<PROVIDER>, where <PROVIDER> is the provider ID upper-cased, with
every character outside A-Z / 0-9 replaced by _. The provider ID is the canonical one after
alias resolution (the provider part of a provider/model string once a short alias has been
resolved). Custom OpenAI- or Anthropic-compatible nodes use their generated node ID, so the
UUID is part of the variable name. The value is a positive integer number of tokens; anything
else (empty, 0, negative, non-numeric) is ignored and resolution moves on to the next step.
| Provider ID | Variable name |
|---|---|
| agentrouter | CONTEXT_LENGTH_AGENTROUTER |
| openrouter | CONTEXT_LENGTH_OPENROUTER |
| openai-compatible-chat-0f8e2c1a-5b7d-4e3f-9a6c-2d1b8e4f7a90 | CONTEXT_LENGTH_OPENAI_COMPATIBLE_CHAT_0F8E2C1A_5B7D_4E3F_9A6C_2D1B8E4F7A90 |
Precedence. For a provider/model pair, the first step that yields a value wins:
CONTEXT_LENGTH_<PROVIDER>for that provider.CONTEXT_LENGTH_DEFAULT(global environment override).- The per-model window: a persisted context override (set in the dashboard, or auto-pinned by
the discovery reconciler, see
CONTEXT_WINDOW_RECONCILE_INTERVAL), otherwise the synced catalog / models.dev value. - The provider's registry
defaultContextLength. - Model-name heuristics (
claude200000,gemini1000000,gpt/o1/o3/o4/codex400000). - Built-in per-provider defaults, then
128000.
Both environment steps apply to the whole provider: every model of that provider gets the same limit, and they win over per-model dashboard overrides. When only one model of a provider needs a different window, use a per-model override in the dashboard instead.
Scope. This chain drives the request-time context-window check (the
context_length_exceeded / "Input exceeds context window" rejection in
open-sse/handlers/chatCore.ts), prompt compression budgets and combo context limits. The
context_length advertised by GET /v1/models can still come from catalog or registry
metadata and is not guaranteed to reflect the environment override.
Example. A provider whose model accepts a 1,050,000-token window while the catalog reports 128,000:
CONTEXT_LENGTH_AGENTROUTER=1050000
Restart the server after changing it: the value is read from the server process environment.
On the desktop app the server runs as a child process and does not see a system variable
set after the app was launched; put the line in the .env file the app loads (lookup order in
Electron Guide: Environment file lookup),
then fully quit and relaunch the app.
Compression
| Variable | Default | Description |
|---|---|---|
OMNIROUTE_RTK_TRUST_PROJECT_FILTERS |
unset | Trust project .rtk/filters.json without a .rtk/trust.json hash. Use only in controlled local development. |
Memory Engine (plan 21)
Event-loop cost of memory, skills, and token refresh (#10349)
OmniRoute is a single Node process. Memory extraction/retrieval, skills injection, and provider token refresh run on that same event loop as GET /healthz and the dashboard. They are not a worker thread.
| Work | Code | Default | Operator control |
|---|---|---|---|
| Memory extraction / retrieval | src/lib/memory/ |
Dashboard memoryEnabled (default on) | Turn off Settings → Memory. There is no separate env kill switch beyond disabling the feature in settings. |
| Skills injection | src/lib/skills/injection.ts |
Dashboard skillsEnabled (default on) | Turn off Settings → Memory/Skills (skillsEnabled). Sandbox knobs below only bound execution after injection is already on. |
| Token refresh | src/sse/services/tokenRefresh.ts |
On for connected OAuth/web providers | Disconnect the provider or let tokens stay valid; there is no TOKEN_REFRESH=0 env today. |
If /healthz is slow on a quiet box, disable memory + skills first, then check catalog/compression load (#10303, #9685). These features yield at await points but still compete for the one thread.
Embedding layer, vector store and reranking knobs for the persistent memory subsystem (src/lib/memory/).
| Variable | Default | Description |
|---|---|---|
MEMORY_EMBEDDING_CACHE_TTL_MS |
300000 (5 min) |
TTL for the in-memory embedding cache (per source/model/dim signature). |
MEMORY_EMBEDDING_CACHE_MAX |
1000 |
Max LRU entries kept in the embedding cache. |
MEMORY_TRANSFORMERS_MODEL |
Xenova/all-MiniLM-L6-v2 |
HF repo id for the opt-in @huggingface/transformers local MiniLM pipeline (~23 MB int8, ~400 MB RAM). |
MEMORY_STATIC_MODEL |
minishlab/potion-base-8M |
HF repo id for the static potion/Model2Vec lookup-table embedder. Downloaded lazily into the cache dir. |
MEMORY_STATIC_CACHE_DIR |
<DATA_DIR>/embeddings |
Directory used to cache the static potion model files. Defaults under DATA_DIR when unset. |
HF_HUB_ENDPOINT |
https://huggingface.co |
Override Hugging Face Hub base URL used by staticPotion.ts (e.g. mirror endpoint for air-gapped setups). |
MEMORY_VEC_TOP_K |
20 |
Default top-K used by the sqlite-vec brute-force vector search inside src/lib/memory/vectorStore.ts. |
MEMORY_RRF_K |
60 |
Reciprocal Rank Fusion constant k for hybrid FTS5 + vector retrieval (sqlite-vec recipe). |
VECTOR_STORE_DISABLE_VEC |
false |
Test/diagnostic seam in getVectorStore() (src/lib/memory/vectorStore.ts): when true, forces the vector store to null (simulates a cloud/WASM environment without sqlite-vec), degrading memory retrieval to FTS5 keyword search. Leave unset in production. |
NOTION_API_KEY |
(unset) | API key for Notion backend (used by genericBackend.ts known backend preset). |
NOTION_API_URL |
https://api.notion.com/v1 |
Base URL for Notion API (can override for self-hosted Notion alternatives). |
OBSIDIAN_API_KEY |
(unset) | API key for Obsidian Vault backend (used by genericBackend.ts known backend preset). |
OBSIDIAN_API_URL |
http://localhost:27123 |
Base URL for Obsidian Vault API (can override for remote vault). |
MEMORY_TYPED_DECAY_ENABLED |
false |
TV6 typed memory decay master switch. Opt-in (default off) — the sweep deletes decayed memories. With it off, access_count/last_accessed_at are pure telemetry and nothing is ever deleted. |
MEMORY_TYPED_DECAY_EPISODIC_DAYS |
30 |
TTL (days) after which an unused episodic memory decays. 0 makes episodic immune too. Durable types (factual/procedural/semantic) are always immune. The decay clock re-bases on last_accessed_at. |
MEMORY_TYPED_DECAY_ACCESS_IMMUNITY |
3 |
A memory injected >= this many times becomes immune to decay regardless of type. 0 disables access immunity. |
MEMORY_TYPED_DECAY_SWEEP_INTERVAL |
0 (disabled) |
Interval (seconds) for the optional periodic decay sweep in src/lib/memory/typedDecay.ts. 0/unset = no periodic sweep. Doubly opt-in: also requires MEMORY_TYPED_DECAY_ENABLED=true. |
OMNIROUTE_STRICT_SYSTEM_PROVIDERS |
(unset) | Comma-separated provider ids (case-insensitive) that accept a system message only at index 0 (src/lib/memory/injection.ts). For these, the cache-safe mid-array memory splice is unsafe in multi-turn conversations, so memory is merged/prepended as the leading system message instead. Defaults to only xiaomi-mimo/mimo; extend for self-hosted OpenAI-compatible endpoints (e.g. Qwen3.5+/3.6) whose chat template enforces the same single-leading-system-message constraint. |
Low-RAM Docker Example
128 is dashboard-only. Coding agents on this heap FATAL ERROR during long /v1/responses. Do not use this example as a Claude/Codex/Grok gateway.
OMNIROUTE_MEMORY_MB=128
PROMPT_CACHE_MAX_SIZE=20
PROMPT_CACHE_MAX_BYTES=524288 # 512 KB
SEMANTIC_CACHE_MAX_SIZE=25
SEMANTIC_CACHE_MAX_BYTES=1048576 # 1 MB
STREAM_HISTORY_MAX=10
18. Pricing Sync
Automatic model pricing data synchronization from external sources.
| Variable | Default | Source File | Description |
|---|---|---|---|
PRICING_SYNC_ENABLED |
false |
src/lib/pricingSync.ts |
Opt-in periodic pricing sync. |
PRICING_SYNC_INTERVAL |
86400 (24h) |
src/lib/pricingSync.ts |
Sync interval in seconds. |
PRICING_SYNC_SOURCES |
litellm |
src/lib/pricingSync.ts |
Comma-separated data sources. |
Arena ELO Sync
| Variable | Default | Source File | Description |
|---|---|---|---|
ARENA_ELO_SYNC_ENABLED |
true |
src/shared/constants/featureFlagDefinitions.ts |
Periodic Arena AI leaderboard ELO sync, configurable from Dashboard Feature Flags or with false to opt out. |
MODELS_CATALOG_PREFIX_MODE |
dual |
src/shared/constants/featureFlagDefinitions.ts, src/app/api/v1/models/catalog.ts |
Prefix form used for model ids in GET /v1/models. dual advertises both the short alias prefix and the canonical provider prefix for every model (backward compatibility — roughly doubles the catalog); alias emits one id per model; canonical emits only the full provider-id prefix (providers whose alias already is the canonical id keep their single entry). Clients can override per request with ?prefix=alias. See API_REFERENCE. |
ARENA_ELO_SYNC_INTERVAL |
86400 (24h) |
src/lib/arenaEloSync.ts |
Sync interval in seconds. |
PromptQL Playground Provider (Unofficial/Experimental)
Reverse-engineered GraphQL session bridge for prompt.ql.app (src/shared/constants/providers/web-cookie.ts). All optional — defaults point at the public playground endpoints; override only for a self-hosted/alternate PromptQL deployment.
| Variable | Default | Source File | Description |
|---|---|---|---|
PROMPTQL_GRAPHQL_ENDPOINT |
https://data.prompt.ql.app/promptql/playground-v2-hge/v1/graphql |
open-sse/executors/promptql.ts |
GraphQL endpoint used for chat/session operations. |
PROMPTQL_CREDITS_ENDPOINT |
https://data.pro.ql.app/v1/graphql |
open-sse/executors/promptql.ts, open-sse/services/usage/promptql.ts |
GraphQL endpoint used to query credit balance/usage. |
PROMPTQL_TOKEN_REFRESH_URL |
https://auth.pro.ql.app/ddn/project/token |
open-sse/executors/promptql.ts |
Endpoint used for best-effort token refresh. |
PROMPTQL_POLL_TIMEOUT_MS |
180000 |
open-sse/executors/promptql.ts |
Max time (ms) to poll thread_events before timing out. |
HyperAgent Web Provider (Unofficial/Experimental)
Reverse-engineered session bridge for hyperagent.com (src/shared/constants/providers/web-cookie.ts). Optional — the default points at the public billing/usage endpoint; override only for a self-hosted/alternate HyperAgent deployment.
| Variable | Default | Source File | Description |
|---|---|---|---|
HYPERAGENT_USAGE_URL |
https://hyperagent.com/api/settings/billing/usage |
open-sse/services/usage/hyperagent.ts |
Endpoint used to fetch billing/usage credit blocks. |
Unpriced Usage Budget Policy
| Variable | Default | Source File | Description |
|---|---|---|---|
UNPRICED_USAGE_BUDGET_POLICY |
(unset; fail closed unless the boolean opt-out is enabled) | src/shared/utils/featureFlags.ts |
Per-key daily/weekly USD limits: fail_closed blocks genuinely unpriced usage; count_as_zero counts it as $0 while enforcing priced spend. An explicit enum (DB before env) overrides the boolean opt-out. Invalid values and pricing lookup failures fail closed. |
USAGE_LIMIT_IGNORE_UNPRICED |
false |
src/shared/utils/featureFlags.ts |
Upstream boolean compatibility opt-out: counts genuinely unpriced usage as $0 only when no explicit enum policy is configured. Priced spend and failed lookups remain enforced. |
Kilo Code Usage Quotas
Personal USD balance and Kilo Pass usage lookup for the Kilo Code provider. 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.
| Variable | Default | Source File | Description |
|---|---|---|---|
KILO_API_URL |
https://api.kilo.ai |
open-sse/services/usage/kilocode.ts |
Base URL used to fetch personal Kilo Code balance and Kilo Pass usage. |
Adobe Firefly Web Provider (Unofficial/Experimental)
Browser-driven session refresh for the Adobe Firefly web provider
(open-sse/services/adobeFireflyBrowserLogin.ts, open-sse/services/adobeFireflySession.ts,
open-sse/services/adobeFireflyClient.ts). Optional — all defaults are tuned for a normal
desktop install.
Removed in #9255. The old CDP-attached Chrome runtime (adobeFireflyChromeRuntime.ts) was replaced by a Playwright browser-login service, and its knobs no longer exist. The ADOBE_FIREFLY_CHROME_ CDP_PORT / VISIBLE / HEADED / PING / FORCE_RESTART variables, plus ADOBE_FIREFLY_LOGIN_WAIT_MS and ADOBE_FIREFLY_FORTER_WAIT_MS, are read nowhere in the codebase — setting them has no effect.
| Variable | Default | Source File | Description |
|---|---|---|---|
ADOBE_FIREFLY_CHROME_HEADLESS |
0 |
open-sse/services/adobeFireflyBrowserLogin.ts |
Set to 1 for true headless Chrome (known-broken for generate; debug only). |
ADOBE_FIREFLY_BROWSER_REFRESH |
1 |
open-sse/services/adobeFireflySession.ts |
Proactive browser warm opt-in/out. 0 disables proactive warm (mid-batch 408 recovery still applies). |
ADOBE_FIREFLY_SESSION_DISK |
1 |
open-sse/services/adobeFireflySession.ts |
Set to 0 to disable persisting the Adobe Firefly session to disk. |
ADOBE_FIREFLY_MIN_SUBMIT_GAP_MS |
(unset) | open-sse/services/adobeFireflySession.ts |
Minimum gap (ms) enforced between successive submits, overriding the built-in default. |
ADOBE_FIREFLY_BATCH_EXTRA_GAP_MS |
(unset) | open-sse/services/adobeFireflySession.ts |
Extra gap (ms) added after a successful batch, overriding the built-in default. |
ADOBE_FIREFLY_SUBMIT_BASE_DELAY_MS |
(unset) | open-sse/services/adobeFireflyClient.ts |
Base delay (ms) before submitting a generation request, overriding the built-in default. |
19. Model Sync (Dev)
| Variable | Default | Source File | Description |
|---|---|---|---|
MODELS_DEV_SYNC_ENABLED |
(unset) | src/lib/modelsDevSync.ts |
Hard override for models.dev pricing sync. Unset = honor Settings > AI (modelsDevSyncEnabled). 0/false/off/no wins over the DB and skips both periodic sync and getModelsDevPricing() SQL/JSON scans (recovery when the dashboard is wedged on the same event loop). 1/true/on/yes forces sync on. Pricing save/clear still call backupDbFile("pre-write"), which is no-op under the 60-minute throttle or DISABLE_SQLITE_AUTO_BACKUP. |
MODELS_DEV_SYNC_INTERVAL |
86400 (24h) |
src/lib/modelsDevSync.ts |
Development-time model catalog sync interval in seconds. |
CONTEXT_WINDOW_RECONCILE_INTERVAL |
86400 (24h) |
src/lib/contextWindowResolver.ts |
Interval (seconds) for the self-correcting context-window reconciler (5004): pins provider-declared windows from /models discovery as auto:discovery overrides when they diverge from the catalog. Set to 0 to disable. Reuses already-synced data (no new fetch); never overwrites manual overrides. |
20. Provider-Specific Settings
| Variable | Default | Source File | Description |
|---|---|---|---|
OPENROUTER_CATALOG_TTL_MS |
86400000 (24h) |
src/lib/catalog/openrouterCatalog.ts |
OpenRouter model catalog cache TTL. |
MODEL_CATALOG_INCLUDE_NAMES |
true |
src/shared/constants/featureFlagDefinitions.ts |
Include display-friendly name fields in /v1/models responses. Disable for clients that expect IDs only. |
OMNIROUTE_GEMINI_WEB_ARGON_ENABLED |
0 (off) |
open-sse/config/providers/registry/gemini/web/index.ts |
Opt-in (#16573). Set 1 (or true/yes) to advertise gweb/gemini-4-argon on the Gemini Web provider and let its executor select that mode. Off by default because the Argon mode-menu selectors have not been checked against a live Gemini Web account; while off, the model is not listed and a request for it is rejected as an unknown model, as before. Read at startup, so a change needs a restart. |
CATALOG_BUILD_TIMEOUT_MS |
8000 (8s) |
src/app/api/v1/models/catalogCache.ts |
Cold-path wait bound for a coalesced GET /v1/models catalog rebuild (#12627). On timeout, a last-good 200 is served when one exists. |
OMNIROUTE_SYNCED_CATALOG_STALE_AFTER_MS |
2592000000 (30 days) |
src/lib/db/models/activeSyncedCatalog.ts |
Age after which a connection's synced model list stops being authoritative for routing and fails open to the registry (#12849). Never-timestamped rows count as stale. |
OMNIROUTE_ANALYTICS_CACHE_TTL_MS |
60000 (60s) |
src/lib/usage/analyticsResponseCache.ts |
How long a slow GET /api/usage/analytics response is reused for the same query string (#15629). 0 disables the cache. |
OMNIROUTE_ANALYTICS_CACHE_MIN_COMPUTE_MS |
100 (100ms) |
src/lib/usage/analyticsResponseCache.ts |
Only analytics responses that took at least this long to build are cached, so small instances always see fresh data. |
OMNIROUTE_CACHE_METRICS_MIN_COMPUTE_MS |
unset (off) | src/app/api/cache/route.ts via src/lib/usage/analyticsResponseCache.ts |
Opt-in (#16361). When set to a non-negative integer N, the usage-history part of GET /api/cache (prompt-cache totals + trend) is served from the shared analytics response cache when it took at least N ms to build, per clamped trendHours window, for OMNIROUTE_ANALYTICS_CACHE_TTL_MS (history may lag up to that TTL; DELETE /api/cache invalidates it). Unset or invalid = history read live on every request. |
NANOBANANA_POLL_TIMEOUT_MS |
120000 |
open-sse/handlers/imageGeneration.ts |
Max wait for NanoBanana image generation jobs. |
NANOBANANA_POLL_INTERVAL_MS |
2500 |
open-sse/handlers/imageGeneration.ts |
NanoBanana job polling frequency. |
ADOBE_FIREFLY_SUBMIT_BASE_DELAY_MS |
8000 |
open-sse/services/adobeFireflyUpscale.ts |
Base delay for the Adobe Firefly upscale submit-retry exponential backoff. |
AWS_REGION |
(unset) | src/lib/providers/validation.ts, open-sse/handlers/audioSpeech.ts |
Region used to construct AWS Bedrock endpoints (Kiro, audio). |
AWS_DEFAULT_REGION |
(unset) | src/lib/providers/validation.ts, open-sse/handlers/audioSpeech.ts |
Fallback when AWS_REGION is not set. |
CLOUDFLARE_ACCOUNT_ID |
(unset) | open-sse/executors/cloudflare-ai.ts |
Account ID for Cloudflare Workers AI. |
CLOUDFLARE_PLAYGROUND_CHROME_PATH |
(unset) | open-sse/executors/cloudflare-playground.ts |
Full desktop Chrome binary path for the Cloudflare AI Playground executor, used when the headless fingerprint check blocks Playwright's bundled Chromium. |
CODEBUDDY_SYSTEM_PROMPT_MAX_LEN |
∅ (∞) — unset = no length cap | open-sse/executors/codebuddy/shared.ts |
Optional length cap for caller system prompts sent to CodeBuddy (CN and International). By default only a prompt carrying a coding-agent identity marker is replaced by a neutral one (Tencent's content filter rejects those); long prompts are kept. An integer > 0 also replaces any system prompt longer than that many characters; unset, 0 or a non-integer value disables the cap. Each replacement logs which rule fired (identity marker or length). |
CLOUDFLARE_API_BASE |
https://api.cloudflare.com/client/v4 |
src/app/api/settings/proxy/cloudflare-deploy/route.ts |
Override the Cloudflare REST API base used by the proxy-pool Workers relay deployer (#4640 / 9router#1360). |
NEXT_PUBLIC_CLOUDFLARE_RELAY_DEFAULT_PROJECT |
omniroute-relay |
src/app/(dashboard)/dashboard/settings/components/proxy/CloudflareRelayModal.tsx |
Default worker project name suggested in the proxy-pool "Deploy Relay" modal. |
NEXT_PUBLIC_CLOUDFLARE_RELAY_ENABLED |
true |
src/app/(dashboard)/dashboard/settings/components/proxy/ProxyPoolTab.tsx |
Set to false to hide the Cloudflare Workers relay option from the Proxy Pool tab. |
CLOUDFLARED_BIN |
auto-detect | src/lib/cloudflaredTunnel.ts |
Custom path to cloudflared binary. |
CLOUDFLARED_PROTOCOL |
http2 |
src/lib/cloudflaredTunnel.ts |
Tunnel transport protocol: http2 (default), quic, or auto. |
CLOUDFLARED_CONFIG |
(unset) | src/lib/cloudflaredTunnel.ts |
Path to a locally-managed cloudflared config.yml (with tunnel:, credentials-file:, ingress:). When set, OmniRoute runs tunnel --config <path> run (named tunnel) instead of an ephemeral quick tunnel. |
CLOUDFLARED_HOSTNAME |
(from config ingress) | src/lib/cloudflaredTunnel.ts |
Override for the named tunnel's public hostname (e.g. ai.example.com), reported as publicUrl/apiUrl. When unset it is read from the config's first ingress hostname. |
DENO_DEPLOY_API_BASE |
https://api.deno.com/v2 |
src/app/api/settings/proxy/deno-deploy/route.ts |
Override the Deno Deploy REST API base used by the proxy-pool relay deployer (#4643 / 9router#1437). |
NEXT_PUBLIC_DENO_RELAY_DEFAULT_PROJECT |
omniroute-deno-relay |
src/app/(dashboard)/dashboard/settings/components/proxy/DenoRelayModal.tsx |
Default Deno Deploy app name suggested in the proxy-pool "Deploy Relay" modal. |
NEXT_PUBLIC_DENO_RELAY_ENABLED |
true |
src/app/(dashboard)/dashboard/settings/components/proxy/ProxyPoolTab.tsx |
Set to false to hide the Deno Deploy relay option from the Proxy Pool tab. |
SEARCH_CACHE_TTL_MS |
300000 (5 min) |
open-sse/services/searchCache.ts |
TTL for search API (Perplexity, Brave, etc.) response caching. |
ENABLE_CC_COMPATIBLE_PROVIDER |
false |
src/shared/utils/featureFlags.ts |
Reveal the experimental CC-compatible provider UI for Claude Code-only relays. |
NINEROUTER_HOST |
127.0.0.1 |
open-sse/executors/ninerouter.ts |
Override the host where the embedded 9router instance listens. |
NINEROUTER_PORT |
20130 |
open-sse/executors/ninerouter.ts |
Override the port where the embedded 9router instance listens. |
EMBED_WS_PROXY_HOST |
127.0.0.1 |
src/lib/services/embedWsProxy.ts |
Bind host for the embedded-service WebSocket proxy (loopback only by default). |
EMBED_WS_PROXY_PORT |
20131 |
src/lib/services/embedWsProxy.ts |
Port for the embedded-service WebSocket proxy server. |
CLIPROXYAPI_HOST |
127.0.0.1 |
open-sse/executors/cliproxyapi.ts |
CLIProxyAPI bridge host (legacy integration). |
CLIPROXYAPI_PORT |
5544 |
open-sse/executors/cliproxyapi.ts |
CLIProxyAPI bridge port. |
CLIPROXYAPI_API_KEY |
(empty) | open-sse/handlers/chatCore/cliproxyapiCredentials.ts |
Data-plane key fallback when the cliproxyapi_api_key setting is absent. |
CLIPROXYAPI_MANAGEMENT_KEY |
(empty) | src/lib/services/cliproxyAccountHealth.ts |
Management key for account-health reads from an externally managed CLIProxyAPI instance. |
OPENCODE_SERVER_URL |
http://127.0.0.1:4096 |
open-sse/executors/opencodeServer.ts |
Address of the opencode CLI headless server (opencode serve) used by the opencode-server provider. Wins over the opencode_server_url dashboard setting. |
OPENCODE_SERVER_BIN |
(auto-detect) | open-sse/services/opencodeServerLauncher.ts |
Absolute path to the opencode executable when it is not on PATH. Env-only by design: there is no dashboard setting for the binary. |
OPENCODE_SERVER_CWD |
(process cwd) | open-sse/services/opencodeServerLauncher.ts |
Working directory of the opencode server started from the dashboard. |
OPENCODE_SERVER_TIMEOUT_MS |
180000 |
open-sse/executors/opencodeServer.ts |
Per-request timeout for the opencode server. |
OPENCODE_SERVER_START_TIMEOUT_MS |
45000 |
open-sse/services/opencodeServerLauncher.ts |
How long the dashboard Start action waits for the opencode server to become healthy. |
OMNIROUTE_LOG_DIR |
~/.omniroute/logs |
open-sse/services/opencodeServerLauncher.ts |
Directory for the dashboard-started opencode server's opencode-serve.log and opencode-serve.err.log. |
CLIPROXYAPI_CONFIG_DIR |
~/.cli-proxy-api |
src/lib/versionManager/processManager.ts |
CLIProxyAPI config directory. |
CLIPROXY_BIND_HOST |
127.0.0.1 |
docker-compose.yml |
Host interface docker-compose publishes the cliproxyapi sidecar on (#12578). 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 0.0.0.0 exposes a credential-bearing service to the whole LAN. |
MUX_SERVICE_PORT |
8322 |
src/lib/services/bootstrap.ts |
Override the port where the embedded Mux (coder/mux) agent-orchestration daemon listens (always 127.0.0.1). |
OPENWA_SERVICE_PORT |
8323 |
src/lib/services/bootstrap.ts |
Override the port where the embedded open-wa (WhatsApp Web automation) daemon listens (always 127.0.0.1). |
DARIO_HOST |
127.0.0.1 |
open-sse/executors/dario.ts |
Dario embedded-service bind/connect host (loopback only by default). |
DARIO_PORT |
3456 |
open-sse/executors/dario.ts |
Dario embedded-service port. |
DARIO_HOST |
127.0.0.1 |
open-sse/executors/dario.ts |
Dario embedded-service bind/connect host (loopback only by default). |
DARIO_PORT |
3456 |
open-sse/executors/dario.ts |
Dario embedded-service port. |
LOCAL_HOSTNAMES |
(empty) | open-sse/config/providerRegistry.ts |
Comma-separated additional hostnames treated as "local" (Docker service names, etc.). |
ENABLE_CC_COMPATIBLE_PROVIDER is only for third-party relays that accept Claude Code clients
exclusively. OmniRoute rewrites requests so those relays accept them. 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.
21. Proxy Health
| Variable | Default | Source File | Description |
|---|---|---|---|
PROXY_FAST_FAIL_TIMEOUT_MS |
2000 |
src/lib/proxyHealth.ts |
Fast-fail health check timeout. |
PROXY_LATENCY_WINDOW_HOURS |
3 |
src/lib/db/proxies.ts |
Time window (hours) for calculating the average latency of candidate proxies in the latency-optimized pool strategy. |
PROXY_HEALTH_CACHE_TTL_MS |
30000 |
src/lib/proxyHealth.ts |
Health check result cache TTL. |
NONE_HONORED_WINDOW_HOURS |
24 |
src/lib/db/reasoningEffortCompliance.ts |
Trailing window in hours for the reasoning_effort=none compliance reader on GET /v1/models/health. |
NONE_HONORED_CACHE_TTL_MS |
20000 |
src/lib/db/reasoningEffortCompliance.ts |
Cache TTL in ms for the none-compliance snapshot (15-30s). |
NONE_HONORED_MIN_SAMPLE |
3 |
src/lib/db/reasoningEffortCompliance.ts |
Minimum none requests before a model reads honored or not honored; below this the model reads unknown. |
PROXY_HEALTH_UNHEALTHY_CACHE_TTL_MS |
2000 |
src/lib/proxyHealth.ts |
Cache TTL for failed proxy health probes. Keep this shorter than PROXY_HEALTH_CACHE_TTL_MS so transient proxy timeouts under high concurrency retry quickly without disabling fast-fail for truly dead proxies. |
PROXY_HEALTH_ENABLED |
true |
src/lib/proxyHealth/scheduler.ts |
Set false to disable the background proxy health scheduler that periodically probes registered proxies. |
PROXY_HEALTH_INTERVAL_MS |
600000 |
src/lib/proxyHealth/scheduler.ts |
Background health-scheduler sweep interval in ms (minimum 60000). |
PROXY_HEALTH_RELAY_INTERVAL_MS |
21600000 |
src/lib/proxyHealth/relayCadence.ts |
Probe interval in ms for edge-relay proxies (deno/vercel/cloudflare), whose probes wake a billed serverless isolate (minimum 60000). |
PROXY_HEALTH_RECOVERY_INTERVAL_MS |
600000 |
src/lib/proxyHealth/scheduler.ts |
Background recovery-pass interval in ms: how often previously-unhealthy proxies are re-probed so a recovered proxy returns to rotation without a restart. Values below 60000 fall back to the default. |
PROXY_HEALTH_TEST_URL |
https://httpbin.org/ip |
src/lib/proxyHealth/probeTarget.ts |
Reachability probe target used by the scheduler and the /api/settings/proxies/auto-test endpoint. Point it at an internal/self-hosted URL to avoid the public default. |
PROXY_HEALTH_TEST_CONCURRENCY |
10 |
src/lib/proxyHealth/probeTarget.ts |
Probes started at once per batch, shared by the scheduler and the /api/settings/proxies/auto-test endpoint. Floored at 1 and capped at 50. |
PROXY_HEALTH_TEST_STAGGER_MS |
100 |
src/lib/proxyHealth/probeTarget.ts |
Delay in ms between two probe departures inside a batch. Without it the whole batch leaves at the same moment and a shared egress IP can trip a rate-limited target. Set to 0 to disable the spacing; capped at 5000. |
PROXY_HEALTH_USE_PROVIDER_TARGET |
true |
src/lib/proxyHealth/providerProbeTarget.ts |
Set "false" to stop probing the real host of a proxy's assigned provider (GET /models, no API key) and always use PROXY_HEALTH_TEST_URL instead. |
PROXY_HEALTH_AUTO_DEACTIVATE |
false |
src/lib/proxyHealth/statusPolicy.ts |
When false (default), automated reachability probes (the scheduler + the /api/settings/proxies/auto-test "Test All" button) are read-only and never write a proxy's status — only the operator sets active/inactive, so a flaky probe can't strand an assigned proxy (#6246). Set true to restore the legacy test-and-set behaviour. |
FLUSH_EMPTY_RETRY_ENABLED |
false |
src/shared/utils/featureFlags.ts |
Opt-in feature flag (see FEATURE_FLAGS.md; a dashboard DB override wins). true (or 1, yes) retries empty translated streaming turns through the normal credential path (up to STREAM_RECOVERY.EMPTY_TURN_RETRY_MAX retries) instead of exposing an empty 200 or an empty-content 502. |
EMPTY_STREAM_SIBLING_RECOVERY_ENABLED |
false |
src/shared/utils/featureFlags.ts |
Opt-in feature flag (see FEATURE_FLAGS.md; a dashboard DB override wins). true (or 1, yes) arms the Claude/Codex empty-stream content probe and spends the existing bounded retry on another eligible connection after an empty_content turn, with no cooldown or model lockout. |
STREAM_LATE_OUTPUT_PROBE_ENABLED |
false |
src/shared/utils/featureFlags.ts |
Opt-in feature flag (see FEATURE_FLAGS.md; a dashboard DB override wins). true (or 1, yes) keeps sampling one forwarded chunk in 16 after the first 64 so late visible output still marks the stream as having emitted output (a lone post-output 5xx stays request-scoped instead of a model-only lockout). |
PROXY_POOL_EGRESS_OBSERVATION |
false |
src/shared/utils/featureFlags.ts |
Opt-in feature flag (see FEATURE_FLAGS.md; a dashboard DB override wins). true (or 1, yes) shows the read-only pool egress observation under a proxy pool in the dashboard (distinct egress IPs, connections and the most seen behind one IP over the last 24 h, from the proxy log). Never used for routing. |
PROXY_OPERATOR_EGRESS_ENABLED |
false |
src/shared/utils/featureFlags.ts |
Opt-in feature flag (see FEATURE_FLAGS.md; a dashboard DB override wins). true (or 1, yes) accepts operator-pushed dated observed addresses per pool member and merges them with the journal read for display and pool order. |
PROXY_OPERATOR_EGRESS_WINDOW_HOURS |
24 |
src/lib/db/proxyOperatorEgress.ts |
Observation window in hours 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. |
PROXY_AUTO_REMOVE |
false |
src/lib/proxyHealth/scheduler.ts |
Set true to let the scheduler auto-remove proxies after repeated consecutive failures. |
PROXY_AUTO_REMOVE_AFTER |
3 |
src/lib/proxyHealth/scheduler.ts |
Consecutive failures before the scheduler auto-removes a proxy (when PROXY_AUTO_REMOVE=true). |
PROXY_AUTO_DISABLE |
false |
src/lib/proxyHealth/scheduler.ts |
Set true to let the scheduler soft-disable (status dead, never deleted) a proxy after repeated consecutive failures, instead of removing it. Non-destructive alternative to PROXY_AUTO_REMOVE: the proxy drops out of pool/rotation resolution immediately (the alive-status filter used by scope-pool resolution already excludes it) and is automatically re-activated once it starts passing probes again. Shares the PROXY_AUTO_REMOVE_AFTER threshold. If both flags are true, PROXY_AUTO_REMOVE wins. |
PROXY_HEALTH_PASSIVE_SKIP |
false |
src/lib/proxyHealth/scheduler.ts |
Opt-in passive skip: when true, the scheduler skips the live probe for an endpoint whose recent production traffic already proves it (at least one success and no attributed proxy failure in the window, exactly one provider observed). Off by default: every proxy is probed. |
PROXY_PASSIVE_WINDOW_MS |
300000 |
src/lib/proxyHealth/passiveVerdict.ts |
Window in ms of production traffic the passive skip looks at (bounded 60000..599999). Shorter than the 10-minute sweep interval so a recent failure dominates instead of being diluted. |
OMNIROUTE_CONTROL_PLANE_PROXY_DIRECT_FALLBACK |
false |
src/shared/constants/featureFlagDefinitions.ts |
Allow OAuth and provider validation flows to bypass a pinned proxy and connect directly when proxy reachability pre-checks fail. Effective precedence is Feature Flags DB override > env var > default. |
RATE_LIMIT_MAX_WAIT_MS |
30000 (30s) |
src/lib/resilience/settings.ts |
Default queue-wait budget: how long a request may wait for a provider slot and sit queued before it is rejected, never reaching the upstream. The timer is cleared once the job starts executing — execution is bounded separately by RATE_LIMIT_EXECUTION_MAX_WAIT_MS. Env sets the default only: a persisted resilienceSettings.requestQueue.maxWaitMs, and then a per-connection rateLimitOverrides.maxWaitMs, each win over it. |
RATE_LIMIT_EXECUTION_MAX_WAIT_MS |
600000 (10 min) |
open-sse/services/rateLimitManager.ts |
Ceiling for how long an admitted request may stay in execution before its rate-limit reservation expires — decoupled from the queue-wait budget so slow fetch-start on non-incremental gateways does not time out (#12027). |
RATE_LIMIT_MAX_QUEUE_DEPTH |
0 (disabled) |
open-sse/services/rateLimitManager.ts |
Queue admission cap: reject with a 429 queue_full once this many requests are already queued. 0 = unbounded (default). |
RATE_LIMIT_AUTO_ENABLE |
(unset) | open-sse/services/rateLimitManager.ts |
Force the auto-enable rate limit safety net on/off regardless of the persisted Dashboard setting (resilienceSettings.requestQueue.autoEnableApiKeyProviders). Accepts true/1/on to force on, false/0/off to force off. When active (default), active API-key connections are automatically rate-limit protected. Setting per-connection rateLimitProtection: false disables explicit protection but does not opt out of this safety net; setting this env var to false is the global mechanism to run API-key connections without rate-limit queues. |
PROVIDER_COOLDOWN_ENABLED |
(unset → off) | open-sse/services/providerCooldownTracker.ts |
Opt-in global cross-request provider/connection cooldown tracking. OFF by default (overlaps Connection Cooldown / Provider Circuit Breaker). Accepts true/1/on to enable. |
PROVIDER_COOLDOWN_MIN_MS |
5000 |
open-sse/services/providerCooldownTracker.ts |
Minimum cooldown (ms) before a failed provider/connection is retried. Scaled exponentially with consecutive failures. Only used when PROVIDER_COOLDOWN_ENABLED. |
PROVIDER_COOLDOWN_MAX_MS |
300000 (5 min) |
open-sse/services/providerCooldownTracker.ts |
Maximum cooldown (ms) cap before a failed provider/connection is retried regardless. Only used when PROVIDER_COOLDOWN_ENABLED. |
STREAM_RECOVERY_ENABLED |
(unset → off) | src/lib/resilience/settings.ts (seed) → open-sse/services/streamRecovery.ts (logic) |
What: transparent recovery of truncated upstream streams (free-claude-code port). Holds the opening SSE window up to STREAM_RECOVERY.HOLDBACK_MS (750 ms) so a pre-commit cutoff — one that happens before any byte reaches the client — is re-opened and retried invisibly. When to enable: flaky/upstreams that frequently 0-byte-truncate at stream start; leave OFF if you cannot afford up to 750 ms of added time-to-first-token on every stream. Accepts true/1/on. Seeds the persisted Resilience setting; the Dashboard setting wins once set. |
STREAM_RECOVERY_MIDSTREAM_ENABLED |
(unset → off) | src/lib/resilience/settings.ts (seed) → open-sse/services/streamRecovery.ts (logic) |
What: mid-stream continuation (Fase 4.4) — after a post-commit truncation (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 fires with a tool call in flight. When to enable: long generations that get cut mid-answer and you accept the recovered tail arriving as one burst rather than token-by-token. Independent of STREAM_RECOVERY_ENABLED (different risk profile). Accepts true/1/on. |
STREAM_THROUGHPUT_WATCHDOG_ENABLED |
(unset → off) | src/lib/resilience/settings.ts → open-sse/services/throughputWatchdog.ts |
Opt-in active-stream useful-output watchdog. Detects streams that keep sending chunks but remain below the configured assistant-output rate; heartbeats, usage events, empty deltas, and tool/reasoning phases do not masquerade as progress. Separate from idle and hard-deadline timeouts. Seeds the default only: a boolean saved in resilienceSettings (Dashboard → Settings → Resilience) takes precedence. |
STREAM_THROUGHPUT_WATCHDOG_WARMUP_MS |
30000 |
src/lib/resilience/settings/normalize.ts |
Grace period before throughput evaluation, bounded to 0–600000 ms. |
STREAM_THROUGHPUT_WATCHDOG_WINDOW_MS |
30000 |
src/lib/resilience/settings/normalize.ts |
Rolling useful-output window, bounded to 1000–600000 ms; one complete window is required before abort. |
STREAM_THROUGHPUT_WATCHDOG_MIN_BYTES_PER_SECOND |
4 |
src/lib/resilience/settings/normalize.ts |
Minimum UTF-8 assistant-output byte rate (conservative token proxy), bounded to 1–1000000. |
STREAM_THROUGHPUT_WATCHDOG_MIN_USEFUL_BYTES |
1 |
src/lib/resilience/settings/normalize.ts |
Minimum non-zero useful-output sample considered measurable, bounded to 1–1000000 bytes. |
HEALTHCHECK_STAGGER_MS |
3000 |
src/lib/tokenHealthCheck.ts |
Stagger interval (ms) between provider token healthchecks at startup. |
HEALTHCHECK_JITTER_MIN_MS |
500 |
src/lib/tokenHealthCheck.ts |
Minimum randomized jitter (ms) added on top of HEALTHCHECK_STAGGER_MS between provider token healthchecks, to prevent bursting (Issue #1220). |
HEALTHCHECK_JITTER_MAX_MS |
5000 |
src/lib/tokenHealthCheck.ts |
Maximum randomized jitter (ms) added on top of HEALTHCHECK_STAGGER_MS between provider token healthchecks, to prevent bursting (Issue #1220). |
HEALTHCHECK_BATCH_SIZE |
20 |
src/lib/tokenHealthCheck.ts |
Concurrent-check batch size for the startup token-healthcheck sweep; larger values check more connections in parallel, smaller values reduce burst load (Issue #7875, regression of #7719). |
REQUEST_RETRY |
2 |
src/sse/services/cooldownAwareRetry.ts |
Number of automatic retries on model-scoped cooldown responses before returning error to client. |
MAX_RETRY_INTERVAL_SEC |
30 |
src/sse/services/cooldownAwareRetry.ts |
Max backoff interval (seconds) between cooldown retries. Capped by this value regardless of upstream Retry-After. |
HEADROOM_URL |
http://localhost:8787 |
src/lib/headroom/detect.ts |
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. |
Stream-recovery tuning constants
The recovery holdback behavior is tuned by hardcoded constants in
open-sse/config/constants.ts (STREAM_RECOVERY), shown here for reference —
changing them requires a code edit, not an env var:
STREAM_RECOVERY.HOLDBACK_MS = 750— how long the opening SSE window is held so an early truncation can be retried before any byte is committed to the client.STREAM_RECOVERY.BUFFER_MAX_BYTES = 65536— hard cap on the held window; commit (flush + passthrough) as soon as this many bytes accumulate, regardless of the timer.STREAM_RECOVERY.EARLY_RETRY_MAX = 4— max transparent re-opens of the upstream stream while the holdback is still uncommitted.
Per-provider sliding-window rate limit (no env var): the FCC-ported per-provider sliding-window rate-limit fallback exists in code (
open-sse/services/providerDefaultRateLimit.ts, wired throughopen-sse/services/rateLimitManager.ts) but ships with an empty default map and has no operator env var today — it is enabled only via a test hook / code edit. It is intentionally not listed in the table above. The per-(token, IP)relay limiter that does have a knob isRELAY_IP_PER_MINUTE(§3 Network & Ports).
22. Debugging
Caution
These variables produce verbose output and may leak sensitive data. Never enable in production.
| Variable | Default | Source File | Description |
|---|---|---|---|
CURSOR_DEBUG |
(unset) | open-sse/executors/cursor.ts |
Set 1 to enable verbose Cursor executor logs (decoded SSE chunks, etc.). |
CURSOR_STREAM_DEBUG |
(unset) | open-sse/executors/cursor.ts |
Backward-compatible alias of CURSOR_DEBUG. |
CURSOR_DUMP_FILE |
(unset) | open-sse/executors/cursor.ts |
Optional file path that receives raw decoded Cursor chunks when CURSOR_DEBUG=1. |
CURSOR_STREAM_TIMEOUT_MS |
300000 |
open-sse/executors/cursor.ts |
Stream idle timeout (ms) for the Cursor executor. |
CURSOR_KV_GRACE_MS |
2000 |
open-sse/executors/cursor.ts |
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. |
CURSOR_TOOL_DIRECTIVE |
enabled (!== "0") |
open-sse/executors/cursor.ts |
Tool-commit directive that makes composer-2.5 reliably issue tool calls. Set 0 to disable. |
OMNIROUTE_SYSTEM_INSTRUCTION_APPEND |
(unset) | open-sse/translator/request/claude-to-openai.ts, open-sse/translator/response/openai-to-claude.ts |
Operator-defined system prompt text appended to the system message AFTER translation (post-translation injection), reaching codex/Responses and /v1/messages paths. Also used as the directive prefix stripped from echoed system preamble blocks. Leave unset to disable. |
OMNIROUTE_STRIP_SYSTEM_PREAMBLE |
0 (off) |
open-sse/translator/response/openai-to-claude.ts, open-sse/utils/directivePreambleStripper.ts |
Set to 1 to strip echoed system-prompt preamble blocks from the start of an openai→claude stream. Off by default — the heuristics are English-prose shaped and mutate the response payload, so a reply that legitimately opens with such a section would lose it. |
CURSOR_IMAGE_FETCH_TIMEOUT_MS |
15000 |
open-sse/utils/cursorImages.ts |
Per-image fetch timeout (ms) for remote image_url vision input. |
CURSOR_STATE_DB_PATH |
(probed) | open-sse/utils/cursorVersionDetector.ts |
Override the Cursor IDE state DB lookup used for IDE version detection. |
CURSOR_AGENT_CLI_VERSION |
(detect / pin) | open-sse/utils/cursorAgentCliVersion.ts |
Agent CLI build id (YYYY.MM.DD-<hash>) for x-cursor-client-version: cli-… on Agent Run. |
CURSOR_AGENT_BIN |
(unset) | open-sse/handlers/imageGeneration/providers/cursorAgentImage.ts |
Path to the Cursor Agent binary used for image generation. Unset, the handler uses providerSpecificData.agentBin then PATH. |
CURSOR_IMG_TIMEOUT_MS |
210000 |
open-sse/handlers/imageGeneration/providers/cursorAgentImage.ts |
Per-image wall clock (ms) for Cursor Agent image jobs. |
CURSOR_IMG_MAX_CONCURRENT |
2 |
open-sse/handlers/imageGeneration/providers/cursorAgentImage.ts |
Shared-seat concurrency gate for Cursor image jobs. |
CURSOR_IMG_MODEL |
request / auto |
open-sse/handlers/imageGeneration/providers/cursorAgentImage.ts |
Override Cursor CLI --model for image jobs. |
UC_IMAGE_POLL_INTERVAL_MS |
2000 |
open-sse/handlers/imageGeneration/providers/ucImage.ts |
UC (uncensored.com) image-gen result-poll cadence (ms). |
UC_IMAGE_POLL_TIMEOUT_MS |
60000 |
open-sse/handlers/imageGeneration/providers/ucImage.ts |
UC image-gen result-poll wall clock (ms). |
UC_VIDEO_POLL_INTERVAL_MS |
3000 |
open-sse/handlers/videoGeneration/providers/ucVideo.ts |
UC (uncensored.com) video-gen result-poll cadence (ms). |
UC_VIDEO_POLL_TIMEOUT_MS |
300000 |
open-sse/handlers/videoGeneration/providers/ucVideo.ts |
UC video-gen result-poll wall clock (ms). |
CURSOR_DATA_DIR |
(probed) | open-sse/utils/cursorAgentCliVersion.ts |
Override Cursor Agent CLI data dir (…/versions/<id>); same var the official agent uses. |
CURSOR_TOKEN |
(unset) | scripts/ad-hoc/cursor-tap.cjs |
Direct Cursor bearer token used by developer tooling. |
OMNIROUTE_LOG_REQUEST_SHAPE |
disabled (opt-in via "1") |
src/app/api/v1/chat/completions/route.ts |
Log content-type/length markers for large chat payloads when "1" is set. Off by default to reduce log noise. |
DEBUG_RESPONSES_SSE_TO_JSON |
(unset) | open-sse/handlers/responseTranslator.ts |
Set true to log Responses API SSE→JSON translation details. |
DEBUG_CLAUDE_NONSTREAM |
(unset) | open-sse/handlers/responseTranslator.ts |
Set true to surface empty textContent chunks in the Claude response translation path (debug only). |
NEXT_PUBLIC_OMNIROUTE_E2E_MODE |
(unset) | E2E test harness | Set true to enable E2E test mode (relaxed auth, test hooks). |
23. GitHub Integration
Allow users to report issues directly from the Dashboard.
| Variable | Default | Source File | Description |
|---|---|---|---|
GITHUB_ISSUES_REPO |
(unset) | src/app/api/v1/issues/report/route.ts |
Repository in owner/repo format. |
GITHUB_ISSUES_TOKEN |
(unset) | src/app/api/v1/issues/report/route.ts |
GitHub Personal Access Token with issues:write scope. |
GITHUB_TOKEN |
(unset) | issue triage / cloud agent helpers | Generic GitHub access token used as fallback for GITHUB_ISSUES_TOKEN and consumed by cloud agent helpers in src/lib/cloudAgent/*. |
Render Free-Tier Keep-Alive
Render spins a free web service down after about 15 minutes without inbound traffic. The standalone
launcher (scripts/dev/run-standalone.mjs, which the Docker image runs) can ping the service's own public URL to
prevent that. It does nothing unless a public URL is available, and it logs only when the status
changes.
| Variable | Default | Description |
|---|---|---|
SELF_PING_ENABLED |
on when a URL is set | 0, false, off or no turns the pinger off. Use it on paid Render plans, where nothing spins down. |
SELF_PING_URL |
RENDER_EXTERNAL_URL |
Base URL to ping. Render sets RENDER_EXTERNAL_URL itself on every plan, so the pinger is on there by default. |
SELF_PING_PATH |
/api/monitoring/health |
Path on that URL. Must start with /; anything else disables the pinger with a warning. |
SELF_PING_INTERVAL_SECONDS |
180 |
Seconds between pings, after a first ping 60 seconds in. Values below 30 fall back to 180. |
A service kept awake for a whole month uses about 744 instance hours, so check it against Render's current free-tier allowance.
Deployment Scenarios
For relay backend SRE guidance (ts/bifrost/auto behavior, 9router vs CLIProxyAPI placement, and high-throughput fallback strategy), see Relay Backend Strategy.
Minimal Local Development
JWT_SECRET=$(openssl rand -base64 48)
API_KEY_SECRET=$(openssl rand -hex 32)
INITIAL_PASSWORD=dev123
PORT=20128
NODE_ENV=development
Docker Production
JWT_SECRET=<generated>
API_KEY_SECRET=<generated>
INITIAL_PASSWORD=<generated>
STORAGE_ENCRYPTION_KEY=<generated>
DATA_DIR=/data
PORT=20128
API_PORT=20129
NODE_ENV=production
AUTH_COOKIE_SECURE=true
REQUIRE_API_KEY=true
NEXT_PUBLIC_BASE_URL=https://omniroute.example.com
BASE_URL=http://localhost:20128
OMNIROUTE_MEMORY_MB=8192
CORS_ORIGIN=https://your-frontend.example.com
Air-Gapped / CI
JWT_SECRET=test-jwt-secret-for-ci
API_KEY_SECRET=test-api-key-secret-for-ci
INITIAL_PASSWORD=testpass
NODE_ENV=production
OMNIROUTE_DISABLE_BACKGROUND_SERVICES=true
APP_LOG_TO_FILE=false
VPS with Reverse Proxy (nginx + Cloudflare)
JWT_SECRET=<generated>
API_KEY_SECRET=<generated>
STORAGE_ENCRYPTION_KEY=<generated>
PORT=20128
AUTH_COOKIE_SECURE=true
REQUIRE_API_KEY=true
NEXT_PUBLIC_BASE_URL=https://omniroute.example.com
BASE_URL=http://127.0.0.1:20128
CORS_ORIGIN=https://omniroute.example.com
ENABLE_TLS_FINGERPRINT=true
CLI_COMPAT_ALL=1
24. Skills Sandbox (v3.8.0+)
Limits and safety knobs applied when the Skills framework (src/lib/skills/) executes user-defined automations in a sandboxed environment.
| Variable | Default | Source File | Description |
|---|---|---|---|
SKILLS_SANDBOX_TIMEOUT_MS |
10000 (10 s) |
src/lib/skills/builtins.ts |
Per-execution wall-clock timeout for sandboxed skill code. Hard cap; anything longer is killed. |
SKILLS_EXECUTION_TIMEOUT_MS |
(falls back to SKILLS_SANDBOX_TIMEOUT_MS) |
src/lib/skills/ |
High-level skill orchestration timeout. Set higher than SKILLS_SANDBOX_TIMEOUT_MS to allow multi-step workflows. |
SKILLS_MAX_FILE_BYTES |
1048576 (1 MB) |
src/lib/skills/builtins.ts |
Max bytes a skill may read from any single sandboxed file. |
SKILLS_MAX_HTTP_RESPONSE_BYTES |
256000 (250 KB) |
src/lib/skills/builtins.ts |
Max bytes captured from any single HTTP response inside a skill. |
SKILLS_MAX_SANDBOX_OUTPUT_CHARS |
100000 |
src/lib/skills/builtins.ts |
Hard cap on stdout/stderr characters returned from a sandbox invocation. |
SKILLS_SANDBOX_NETWORK_ENABLED |
false |
src/lib/skills/builtins.ts |
Set 1/true to allow outbound network from inside the sandbox. Defaults to isolated for safety. Ignored by the agent-sandbox runtime: network isolation, the read-only root filesystem and CPU/memory limits come from the operator's SandboxTemplate. |
SKILLS_ALLOWED_SANDBOX_IMAGES |
(empty) | src/lib/skills/builtins.ts |
Comma-separated allowlist of container images permitted for sandbox execution. Empty means built-in default only. |
SKILLS_SANDBOX_DOCKER_IMAGE |
(built-in default) | src/lib/skills/ |
Container image used when spawning a Docker-backed sandbox. Override to pin a custom hardened base image. |
SKILLS_SANDBOX_RUNTIME |
auto |
src/lib/skills/sandbox.ts, src/lib/skills/containerProvider.ts |
Container runtime for skill sandboxing: auto | docker | apple | wsl | orbstack | podman | agent-sandbox. auto picks the best installed runtime per host OS (Apple Container/OrbStack on macOS, WSL Container on Windows, Podman on Linux), falling back to Docker. agent-sandbox (remote Kubernetes warm pools) is opt-in only and never auto-detected. |
SKILLS_AGENT_SANDBOX_POOLS |
(empty) | src/lib/skills/agentSandboxProvider.ts |
image=pool pairs, comma-separated: which SandboxWarmPool serves each sandbox image when SKILLS_SANDBOX_RUNTIME=agent-sandbox. |
SKILLS_AGENT_SANDBOX_POOL |
(empty) | src/lib/skills/agentSandboxProvider.ts |
Fallback warm pool for images not listed in SKILLS_AGENT_SANDBOX_POOLS. A run fails (no fallback to local containers) when neither resolves. |
SKILLS_AGENT_SANDBOX_NAMESPACE |
default |
src/lib/skills/agentSandboxProvider.ts |
Namespace holding the warm pools; one SandboxClaim per run is created and deleted here. |
SKILLS_AGENT_SANDBOX_KUBECONFIG |
(kubectl default) | src/lib/skills/agentSandboxProvider.ts |
Kubeconfig for the agent-sandbox runtime. Needs only sandboxclaims create/get/list/watch/delete, pods get, pods/exec create in the namespace. |
SKILLS_AGENT_SANDBOX_KUBECTL |
kubectl |
src/lib/skills/agentSandboxProvider.ts |
kubectl binary used by the agent-sandbox runtime. |
SKILLS_AGENT_SANDBOX_CONTAINER |
main |
src/lib/skills/agentSandboxProvider.ts |
Container name inside the sandbox pod that commands are executed in. |
SKILLS_AGENT_SANDBOX_CLAIM_TIMEOUT_S |
60 |
src/lib/skills/agentSandboxProvider.ts |
Seconds to wait for a claim to become Ready (max 600). The claim is deleted if it never does. |
Caution
Enabling
SKILLS_SANDBOX_NETWORK_ENABLED=trueopens an egress path from arbitrary skill code. Pair withOUTBOUND_SSRF_GUARD_ENABLED=trueand a strictCORS_ORIGIN/proxy policy in shared deployments.
25. Provider Quotas, Tunnels, Backups & Misc Runtime
Redis session-affinity fallback invalidation (opt-in only; SQLite default is unchanged):
Each Redis affinity store admits at most 8 outstanding operations; at capacity, calls immediately use SQLite, and slots remain occupied until the underlying Redis work settles, even after the 100 ms caller deadline.
- R1. Any Redis reply delivered in time for a session operation is authoritative: accepted mutations, rejected/lost CAS, missing keys, absent-key deletes, and eviction hits or misses synchronously clear that session's local fallback row, with no await between reply and clear. Clearing is safe (at worst one re-selection during a later outage); a stale row is not.
- R2. An operation that times out or errors and writes a local fallback records exactly what it wrote as serialized bytes. If its Redis command completes late, synchronous SQLite compare-and-delete clears only that byte-identical row, never by account or connection match. A newer outage write survives.
- R3. Eviction always removes the failed account's local pin, including during an outage; its reply handling then follows R1/R2. Healthy Redis never writes local pins: there is no mirror or ordering ledger, and instances may diverge during an outage.
Provider quota endpoints, network tunnels (Tailscale, Ngrok, MITM debug proxy), the 1Proxy egress pool, database backups and small per-feature overrides referenced by the executor layer or scripts.
| Variable | Default | Source File | Description |
|---|---|---|---|
OMNIROUTE_SESSION_AFFINITY_STORE |
sqlite |
src/lib/db/sessionAffinity/storeFactory.ts |
Session-to-account affinity backend. Only redis plus configured REDIS_URL enables sharing; unset/unknown values or missing Redis configuration use SQLite. Requires positive sessionAffinityTtlMs. Redis routing stores hashed usage-account identity plus connection ID; default SQLite routing keeps the legacy four-field JSON shape. Matches identity within the eligible local pool before ID. Uses the shared client's REDIS_KEY_PREFIX, JSON values and PX TTL; mutations compare the exact observed value. Healthy Redis replies invalidate the local outage fallback, and a late reply can clear only the exact serialized fallback row written by that timed-out operation. Prefetched pins are revalidated at use. Redis errors, timeouts or admission saturation fall back to SQLite with throttled warnings (100 ms bound per store call); successful Redis misses do not read the shadow. Does not share combo stickiness, native Codex turn pins, account concurrency, lockouts or spend limits. |
REDIS_URL |
redis://localhost:6379 |
src/shared/utils/rateLimiter.ts |
Redis connection string for the rate limiter backend. |
ALIBABA_CODING_PLAN_HOST |
(production host) | open-sse/services/bailianQuotaFetcher.ts |
Override the host used to fetch Alibaba Bailian coding-plan quotas. |
ALIBABA_CODING_PLAN_QUOTA_URL |
derived from host | open-sse/services/bailianQuotaFetcher.ts |
Full quota URL override for Alibaba Bailian. |
QWEN_CLOUD_COOKIE |
(unset) | open-sse/services/qwenTokenPlanQuotaFetcher.ts |
Console session cookie for the Qwen Cloud / Model Studio personal Token Plan quota gateway (the inference API key cannot read it). Copy the whole Cookie request header — it contains login_qwencloud_ticket — from any api.json call to cs-data.qwencloud.com on home.qwencloud.com › Billing › Subscription (F12 › Network). Sensitive and session-scoped; prefer the per-connection qwenCloudCookie Dashboard field. |
QWEN_CLOUD_SEC_TOKEN |
(unset) | open-sse/services/qwenTokenPlanQuotaFetcher.ts |
Manual sec_token override for the Token Plan console gateway. Sensitive; when unset the fetcher resolves it from the dashboard HTML using the cookie. |
QWEN_TOKEN_PLAN_HOST |
https://cs-data.qwencloud.com |
open-sse/services/qwenTokenPlanQuotaFetcher.ts |
Gateway host override for the personal Token Plan quota fetcher (e.g. bailian-singapore-cs.alibabacloud.com for the Model Studio console). |
QWEN_TOKEN_PLAN_DASHBOARD_URL |
https://home.qwencloud.com/ |
open-sse/services/qwenTokenPlanQuotaFetcher.ts |
Dashboard URL used to resolve sec_token from the logged-in HTML. |
XIAOMI_MIMO_CONSOLE_COOKIE |
(unset) | open-sse/services/usage/xiaomi-mimo.ts |
Console session cookie for the Xiaomi MiMo Token Plan quota API (platform.xiaomimimo.com/api/v1/tokenPlan/usage + tokenPlan/detail — the inference API key cannot read it). Copy the whole Cookie request header — it contains api-platform_serviceToken and userId — from any request to platform.xiaomimimo.com on the Token Plan page (F12 › Network). Sensitive and session-scoped; prefer the per-connection xiaomiMimoConsoleCookie Dashboard field. |
XIAOMI_MIMO_MONTHLY_TOKEN_LIMIT |
4100000000 |
open-sse/services/usage/xiaomi-mimo.ts |
Monthly budget (Credits) for the OmniRoute-tracked Xiaomi MiMo fallback used when no console cookie is configured. Defaults to the Lite tier's 4.1B; set it to the plan's Credits (Standard 11B / Pro 38B / Max 82B). A per-connection providerSpecificData.monthlyTokenLimit override wins over this env var. |
ALIBABA_FREE_TIER_VISION_FE_PATH |
/costing-balance/free-quota-image-video |
open-sse/services/alibabaFreeTierQuotaFetcher.ts |
Console front-end path override for fetching Alibaba Model Studio free-tier vision/media quota. |
ALIBABA_FREE_TIER_MULTIMODAL_FE_PATH |
/costing-balance/free-quota-multimodal |
open-sse/services/alibabaFreeTierQuotaFetcher.ts |
Console front-end path override for fetching Alibaba Model Studio free-tier multimodal quota. |
ALIBABA_FREE_TIER_AUDIO_FE_PATH |
/costing-balance/free-quota-audio |
open-sse/services/alibabaFreeTierQuotaFetcher.ts |
Console front-end path override for fetching Alibaba Model Studio free-tier audio quota. |
ALIBABA_FREE_TIER_ALLOWLIST_PATH |
(unset) | open-sse/services/alibabaFreeTierAllowlist.ts |
Optional path to a local JSON override for the built-in Alibaba free-tier text-model allowlist. Falls back to $DATA_DIR/alibaba-free-tier-allowlist.json, then config/alibaba-free-tier-allowlist.json. |
CONTEXT_RESERVE_TOKENS |
1024 |
open-sse/services/contextManager.ts |
Tokens reserved for completion output when computing prompt budgets. |
CONTEXT_KEEP_LATEST_IMAGES |
2 |
open-sse/services/contextManager.ts |
How many of the newest inline images to keep when pruning older ones to fit the context window (#8560). |
MODEL_ALIAS_COMPAT_ENABLED |
enabled | open-sse/services/model.ts |
Toggle the legacy model-alias compatibility layer used by older clients. |
OMNIROUTE_EMERGENCY_FALLBACK |
enabled | open-sse/services/emergencyFallback.ts |
Set false (or 0) to disable the emergency budget-exhaustion fallback that reroutes failed requests to the free nvidia/nvidia/nemotron-3.5-super-vl-120b-a12b model. Effective precedence is Feature Flags DB override > env var > default; if unavailable, the service falls back to the raw env value. |
COMMAND_CODE_CALLBACK_PORT |
(unset) | src/app/api/providers/command-code/auth/shared.ts |
Local port used for OAuth-style callbacks from the Command Code CLI helper. |
COMMAND_CODE_VERSION |
0.33.2 |
open-sse/executors/commandCode.ts |
Value sent as the x-command-code-version header to the Command Code upstream. Override to bump the CLI version. |
COMMANDCODE_API_URL |
https://api.commandcode.ai |
open-sse/services/usage/command-code.ts |
Base URL for the Command Code usage/quota upstream used by the smartphone quota-fetcher telemetry. Override for a self-hosted/alternative Command Code API. |
MITM_LOCAL_PORT |
443 |
src/mitm/server.cjs |
Local bind port for the MITM debug proxy. |
MITM_DISABLE_TLS_VERIFY |
0 |
src/mitm/server.cjs |
Set 1 to disable upstream TLS verification (development only). |
MITM_IDLE_TIMEOUT_MS |
60000 |
src/mitm/socketTimeouts.ts, src/mitm/server.cjs |
Idle socket timeout (ms) for proxied connections; idle sockets past this are torn down to avoid leaking half-open tunnels. |
BRIDGE_PORT |
20129 |
bin/antigravity-bridge.mjs |
Port the Antigravity MITM bridge listens on. |
ROUTER_URL |
http://127.0.0.1:20128/v1/antigravity |
bin/antigravity-bridge.mjs |
Router endpoint the bridge forwards Antigravity traffic to. |
CERT_DIR |
<DATA_DIR>/mitm |
bin/antigravity-bridge.mjs |
Overrides the directory the bridge reads its TLS material from. The cert model is picked like the AgentBridge server does: server.crt/server.key for a legacy leaf install, otherwise ca.crt/ca.key (root CA, a leaf per intercepted host; forced by MITM_ROOT_CA_ENABLED=true). The bridge exits at startup if the files for the active model are missing. |
MITM_VERBOSE |
1 |
src/mitm/server.cjs, src/mitm/_internal/bypass.cjs |
Routing-decision log verbosity: 0 silences, higher values log more bypass/route decisions. |
MITM_ROOT_CA_ENABLED |
false |
src/mitm/manager.ts |
Set true to opt in to the root-CA + per-host-leaf cert model (#6684). Fresh installs get it automatically; installs with a pre-existing trusted legacy leaf keep the legacy fixed-SAN cert unless opted in. |
MITM_CERT_MODE |
legacy |
src/mitm/manager.ts, src/mitm/server.cjs |
Set BY the MITM manager for the spawned proxy process (root-ca | legacy) — reflects the cert-migration decision; not meant to be set manually. |
OMNIROUTE_NO_SUDO |
0 |
src/mitm/systemCommands.ts |
Set 1 (truthy) to strip the leading sudo from MITM cert-trust commands — for root-less / user-namespaced deployments where the operator trusts the CA manually (e.g. via Node's extra-CA-certs mechanism). |
SKIP_ANTIGRAVITY_DNS |
(unset) | src/mitm/dns/provision.ts |
Set true to skip provisioning /etc/hosts DNS entries for the Antigravity proxy hostnames entirely — for containers with no sudo/root available. |
OMNIROUTE_SKIP_DNS_WRITE |
(unset) | src/mitm/dns/dnsConfig.ts |
Set 1 to skip writing to the hosts file when adding/removing DNS entries — for sandboxed or read-only test environments. |
OMNIROUTE_SKIP_SYSTEM_TRUST |
0 |
src/mitm/cert/install.ts, src/mitm/tproxy/caTrust.ts |
Test/CI-only guard: set 1 to make cert trust install/uninstall a no-op so the suite never mutates the OS trust store. Set automatically by the test setup and CI workflows. |
CHANGELOG_BASE_REF |
(auto) | scripts/check/check-changelog-integrity.mjs |
Explicit base ref for the anti CHANGELOG-eat gate (defaults to the PR base branch in CI, or the highest release/v*). |
MIGRATION_BASE_REF |
(auto) | scripts/check/lib/migrationBaseDiff.mjs |
Explicit base ref for the comparison check:migration-numbering makes with the base (deleted, renamed, edited or out-of-order migrations). --base <ref> wins over it; in CI it defaults to the first parent of the PR merge ref, merge_group.base_sha or the merge-base with origin/$GITHUB_BASE_REF. |
MIGRATION_COMMUTATION_SCRIPT |
(unset) | scripts/check/lib/migrationBaseDiff.mjs |
Test-only hook: path of a stand-in for scripts/check/migration-commutation.ts, used by tests/unit/check-migration-numbering-base-diff.test.ts. Never set it in CI or production. |
FREE_PROXY_AUTO_SYNC_ENABLED |
false |
src/lib/freeProxyProviders/scheduler.ts |
Set true to enable the background free-proxy pool auto-sync scheduler. Opt-in, off by default. |
FREE_PROXY_AUTO_SYNC_INTERVAL_MS |
1800000 |
src/lib/freeProxyProviders/scheduler.ts |
Auto-sync interval in milliseconds (default 30 min). |
FREE_PROXY_1PROXY_ENABLED |
true |
src/lib/freeProxyProviders/oneproxy.ts |
Enable the 1proxy free proxy source. Set to false to disable. |
FREE_PROXY_1PROXY_API_URL |
(see oneproxy.ts) | src/lib/freeProxyProviders/oneproxy.ts |
1proxy API URL override. |
FREE_PROXY_1PROXY_MAX |
500 |
src/lib/freeProxyProviders/oneproxy.ts |
Maximum proxies fetched per sync from 1proxy. |
FREE_PROXY_1PROXY_MIN_QUALITY |
50 |
src/lib/freeProxyProviders/oneproxy.ts |
Minimum quality score threshold for 1proxy imports. |
FREE_PROXY_PROXIFLY_ENABLED |
true |
src/lib/freeProxyProviders/proxifly.ts |
Enable the Proxifly free proxy source. Set to false to disable. |
FREE_PROXY_PROXIFLY_QUANTITY |
100 |
src/lib/freeProxyProviders/proxifly.ts |
Number of proxies to fetch per Proxifly sync. |
FREE_PROXY_PROXIFLY_ANONYMITY |
elite |
src/lib/freeProxyProviders/proxifly.ts |
Anonymity level filter for Proxifly (elite, anonymous, transparent). |
FREE_PROXY_IPLOCATE_ENABLED |
false |
src/lib/freeProxyProviders/iplocate.ts |
Enable the IPLocate free proxy source. Opt-in only. |
FREE_PROXY_IPLOCATE_BASE_URL |
https://raw.githubusercontent.com/iplocate/free-proxy-list/main/protocols |
src/lib/freeProxyProviders/iplocate.ts |
IPLocate proxy list base URL override. |
FREE_PROXY_WEBSHARE_ENABLED |
true |
src/lib/freeProxyProviders/webshare.ts |
Enable the Webshare proxy pool source. Set to false to disable; also requires FREE_PROXY_WEBSHARE_API_KEY to be set. |
FREE_PROXY_WEBSHARE_API_KEY |
(none) | src/lib/freeProxyProviders/webshare.ts |
Webshare account API token (Authorization: Token <key>). Required — the provider stays disabled without it. |
FREE_PROXY_WEBSHARE_API_URL |
https://proxy.webshare.io/api/v2/proxy/list/ |
src/lib/freeProxyProviders/webshare.ts |
Webshare proxy list API URL override. |
FREE_PROXY_WEBSHARE_MAX |
500 |
src/lib/freeProxyProviders/webshare.ts |
Maximum proxies imported per Webshare sync. |
NEXT_PUBLIC_VERCEL_RELAY_ENABLED |
true |
src/app/(dashboard)/…/ProxyPoolTab.tsx |
Show/hide the Deploy Vercel Relay button in the Proxy Pool tab. |
VERCEL_API_BASE |
https://api.vercel.com |
src/app/api/settings/proxy/vercel-deploy/route.ts |
Vercel API base URL override (for testing). |
NEXT_PUBLIC_VERCEL_RELAY_DEFAULT_PROJECT |
omniroute-relay |
src/app/(dashboard)/…/VercelRelayModal.tsx |
Default project name pre-filled in the Vercel Relay deploy modal. |
TAILSCALE_BIN |
(auto-detect) | src/lib/tailscaleTunnel.ts |
Explicit path to the tailscale binary. |
TAILSCALED_BIN |
(auto-detect) | src/lib/tailscaleTunnel.ts |
Explicit path to the tailscaled daemon binary. |
TAILSCALE_AUTHKEY |
(unset) | src/lib/tailscaleTunnel.ts |
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. |
NGROK_AUTHTOKEN |
(unset) | src/lib/ngrokTunnel.ts |
Authenticates outbound ngrok tunnels. |
DB_BACKUP_MAX_FILES |
20 |
src/lib/db/backup.ts |
Maximum SQLite backup files retained by manual/scheduled backup cleanup. Migration snapshots are content-addressed and reused for an identical DB state; they are not pruned inside the concurrent migration window. Overrides the value saved from Settings → Database backup retention. |
DB_BACKUP_RETENTION_DAYS |
0 |
src/lib/db/backup.ts |
Maximum age (days) retained by manual/scheduled backup cleanup. 0 disables age-based pruning. Migration snapshots are not pruned inside the concurrent migration window. Overrides the value saved from Settings → Database backup retention. |
OMNIROUTE_BACKUP_SCHEDULE_JOB_INTERVAL_MS |
30000 |
src/lib/jobs/backupScheduleJob.ts |
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 30000. |
CONTAINER_HOST |
docker |
scripts/check-permissions.sh |
Container runtime hint for the entrypoint permission check. Set to podman for any Podman topology. Because the container cannot determine whether the engine is local or reached through Podman Machine, the warning stays topology-neutral and points to contrib/podman/README.md. |
QUOTA_STORE_DRIVER |
sqlite |
src/lib/quota/storeFactory.ts |
Quota-share consumption store backend: sqlite (default) or redis. |
QUOTA_STORE_REDIS_URL |
(unset) | src/lib/quota/storeFactory.ts |
Redis connection string used when QUOTA_STORE_DRIVER=redis (e.g. redis://localhost:6379). |
QUOTA_SATURATION_THRESHOLD |
0.5 |
src/lib/quota/enforce.ts |
Pool saturation ratio (0..1); at/above it the pool enters strict mode (no borrowing). |
QUOTA_SOFT_DEPRIORITIZE_FACTOR |
0.7 |
open-sse/services/combo.ts |
Score multiplier (0..1) applied to a target when the soft quota policy deprioritizes it. |
STATUS_SOFT_DEPRIORITIZE_FACTOR |
0.5 |
open-sse/services/combo/autoStrategy.ts |
Score multiplier (0..1) applied to an exhausted provider (credits_exhausted/rate_limited) in auto-combo scoring when the preflight quota cutoff is OFF (#4540). |
QUOTA_CONSUMPTION_RETENTION_DAYS |
14 |
src/lib/db/quotaConsumption.ts |
Retention window (days) for quota_consumption buckets before GC (gcQuotaConsumption). |
QUOTA_PREFLIGHT_CUTOFF_ENABLED |
false |
src/lib/resilience/settings.ts |
Opt-in (default OFF): enables the auto-routing hard quota cutoff that drops low-quota candidates before scoring. Seeds the default only: a boolean saved in resilienceSettings (Dashboard → Settings → Resilience) takes precedence. |
OMNIROUTE_AUTO_FREE_FALLBACK_TO_FULL_POOL |
false |
open-sse/services/autoCombo/virtualFactory.ts |
Opt-in (default OFF): when an auto/<category>:<tier> filter matches no connected candidates, restore the legacy behavior of falling back to the full (unfiltered) pool instead of returning an empty pool. Default OFF makes :free mean "free tier only". |
OMNIROUTE_CHAOS_MAX_PANEL |
5 |
open-sse/services/autoCombo/virtualFactory.ts |
Panel-size cap (clamped 1–10) for the auto/*:chaos broadcast variant — one request fans out to at most this many provider-diverse models. |
OMNIROUTE_CHAOS_MIN_PANEL |
(engine default) | open-sse/services/autoCombo/virtualFactory.ts |
Minimum panel-size tuning forwarded to the chaos broadcast handler; unset keeps the engine default. |
OMNIROUTE_CHAOS_PANEL_TIMEOUT_MS |
(engine default) | open-sse/services/autoCombo/virtualFactory.ts |
Hard timeout (ms) for the whole chaos panel fan-out; unset keeps the engine default. |
GROK_AUTH_PATH |
~/.grok/auth.json |
open-sse/services/grokQuotaFetcher.ts |
Path of the Grok CLI auth.json used to fetch the grok-web weekly quota; override for tests or a non-standard CLI install. |
AGENTBRIDGE_UPSTREAM_CA_CERT |
(unset) | src/mitm/manager.ts |
Extra CA certificate (PEM) trusted for AgentBridge upstream TLS connections. |
INSPECTOR_BUFFER_SIZE |
1000 |
src/mitm/inspector/buffer.ts |
Max captured requests held in the Traffic Inspector ring buffer. |
INSPECTOR_MAX_BODY_KB |
1024 |
src/mitm/inspector/buffer.ts |
Max captured request/response body size (KB) before truncation. |
INSPECTOR_HTTP_PROXY_PORT |
8080 |
src/mitm/inspector/httpProxyServer.ts |
Local port for the Traffic Inspector HTTP proxy. |
INSPECTOR_HTTP_PROXY_AUTOSTART |
false |
src/mitm/inspector/httpProxyServer.ts |
Auto-start the inspector HTTP proxy on boot. |
INSPECTOR_LLM_HOSTS_EXTRA |
(unset) | src/lib/inspector/captureState.ts |
Extra hostnames (comma-separated) treated as LLM endpoints for capture. |
INSPECTOR_MASK_SECRETS |
true |
src/mitm/inspector/buffer.ts |
Mask secrets (auth headers / API keys) in captured traffic. |
INSPECTOR_SYSTEM_PROXY_GUARD_MINUTES |
30 |
src/app/api/tools/traffic-inspector/capture-modes/system-proxy/route.ts |
Minutes before the system-proxy guard auto-reverts OS proxy settings. |
INSPECTOR_INTERNAL_INGEST_TOKEN |
(auto) | src/app/api/tools/traffic-inspector/internal/ingest/route.ts |
Token authenticating internal capture ingest into the inspector. |
PLAYGROUND_COMPARE_MAX_COLUMNS |
4 |
src/app/(dashboard)/dashboard/playground/ |
Max number of side-by-side columns in the Playground compare mode. |
PLAYGROUND_IMPROVE_PROMPT_DEFAULT_MODEL |
(unset) | src/app/(dashboard)/dashboard/playground/ |
Default model for the Playground 'improve prompt' action (falls back to the active model when unset). |
BIFROST_ENABLED |
1 |
src/app/api/v1/relay/chat/completions/bifrost/route.ts |
Master kill switch for the bifrost sidecar proxy. When set to 0, the route returns 503 with the X-Bifrost-Killswitch header and the operator is bounced to the TS path. Use to disable the sidecar without redeploying (tier-1 router incident, key rotation). |
BIFROST_BASE_URL |
(unset) | src/app/api/v1/relay/chat/completions/bifrost/route.ts |
When set, the Bifrost sidecar proxy route forwards /v1/chat/completions traffic to this Go gateway instead of the TS relay handler. Unset → 503-with-fallback. Trailing slash is stripped. |
BIFROST_PORT |
8080 |
src/lib/services/bootstrap.ts |
Port the supervised Bifrost embedded service binds to (127.0.0.1:<port>) when OmniRoute manages the Bifrost sidecar lifecycle. Defaults to 8080. |
SINGBOX_PORT |
20140 |
src/lib/services/bootstrap.ts |
Port the supervised sing-box embedded service binds to (127.0.0.1:<port>) when OmniRoute manages the sing-box sidecar lifecycle. Defaults to 20140. |
LLMLINGUA_PORT |
20135 |
src/lib/services/bootstrap.ts |
Port the supervised LLMLingua compression service binds to (127.0.0.1:<port>). Defaults to 20135. |
LLMLINGUA_BASE_URL |
http://127.0.0.1:20135 |
open-sse/services/compression/engines/llmlingua/index.ts |
Base URL for the local LLMLingua HTTP compression microservice daemon. Defaults to http://127.0.0.1:20135. |
LLMLINGUA_MODEL |
atjsh/llmlingua-2-js-tinybert-meetingbank |
src/lib/services/installers/llmlingua.ts |
Hugging Face model id the supervised LLMLingua sidecar loads (passed to the child process env). |
BIFROST_API_KEY |
(unset) | src/app/api/v1/relay/chat/completions/bifrost/route.ts |
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_STREAMING_ENABLED |
true |
src/app/api/v1/relay/chat/completions/bifrost/route.ts |
When true, the Bifrost sidecar route streams responses back via SSE through the gateway rather than the TS streaming executor. Set to 0 to force non-streaming JSON responses through the gateway. |
BIFROST_TIMEOUT_MS |
30000 |
src/app/api/v1/relay/chat/completions/bifrost/route.ts |
Per-request timeout when proxying to the Bifrost gateway (ms). On timeout the route returns the TS relay path via the X-Bifrost-Fallback header. |
OMNIROUTE_BIFROST_KEY |
(unset) | src/app/api/v1/relay/chat/completions/bifrost/route.ts |
Alias for BIFROST_API_KEY (used by scripts that read the env via OMNIROUTE_*). BIFROST_API_KEY takes precedence when both are set. |
OMNIROUTE_RELAY_BACKEND |
ts / auto |
src/app/api/v1/relay/chat/completions/routingBackend.ts |
Relay backend for /api/v1/relay/chat/completions: ts | bifrost | auto. ts = TypeScript relay (default when Bifrost unconfigured); auto selects Bifrost when BIFROST_BASE_URL is set and BIFROST_ENABLED ≠ 0, with automatic TS fallback if the sidecar is unreachable; bifrost forces Bifrost (strict, no fallback). Auth/rate-limit/injection-guard/allowlist always run in the Next route first. Responses carry X-Routing-Backend / X-Routing-Fallback / X-Routing-Fallback-Reason. |
RELAY_ROUTING_BACKEND |
(unset) | src/app/api/v1/relay/chat/completions/routingBackend.ts |
Accepted alias for OMNIROUTE_RELAY_BACKEND (same ts | bifrost | auto values). OMNIROUTE_RELAY_BACKEND takes precedence when both are set. |
OMNIROUTE_BIFROST_FAILURE_COOLDOWN_MS |
5000 |
src/app/api/v1/relay/chat/completions/bifrostCooldown.ts |
Cooldown (ms) after a Bifrost sidecar hop fails in auto mode before the relay re-attempts the sidecar; it routes straight to the TS path while the cooldown lasts, then probes again. 0 disables. Only applies when OMNIROUTE_RELAY_BACKEND=auto. |
OMNIROUTE_TLS_CERT |
(unset) | bin/cli/commands/serve.mjs |
Path to a PEM TLS certificate to serve omniroute serve over HTTPS (equivalent to --tls-cert). Must be paired with OMNIROUTE_TLS_KEY; the standalone server then terminates TLS on the same listener (wss:// works unchanged). Unset → plain HTTP. Providing only one of cert/key, or an unreadable path, logs a warning and stays HTTP. |
OMNIROUTE_TLS_KEY |
(unset) | bin/cli/commands/serve.mjs |
Path to the PEM TLS private key for omniroute serve HTTPS (equivalent to --tls-key). Must be paired with OMNIROUTE_TLS_CERT. See OMNIROUTE_TLS_CERT. |
OMNIROUTE_LOCAL_ENDPOINTS_ENABLED |
0 |
src/lib/security/localEndpoints.ts |
Master switch for /api/local/* routes. When unset or 0, all /api/local/* routes return 503 in production. Must be 1 in non-loopback deploys to enable the Redis launcher and similar 1-click local service starters. Belt-and-suspenders with isLocalOnlyPath() route-guard classification (LOCAL_ONLY_API_PREFIXES in src/server/authz/routeGuard.ts). |
OMNIROUTE_LOCAL_ENDPOINTS_TOKEN |
(unset) | src/lib/security/localEndpoints.ts |
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. |
OMNIROUTE_REDIS_CONTAINER_NAME |
omniroute-redis |
bin/cli/commands/redis.mjs |
Container name for the 1-click Redis launcher (omniroute redis up). Used by both the CLI and the RedisLauncherPanel GUI. |
OMNIROUTE_REDIS_HOST_PORT |
6379 |
bin/cli/commands/redis.mjs |
Host port for the 1-click Redis launcher. Bump if the host already binds 6379. The container's internal port stays 6379. |
OMNIROUTE_REDIS_BIND_HOST |
127.0.0.1 |
bin/cli/commands/redis.mjs |
Host interface the 1-click Redis launcher publishes on. 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. |
REDIS_BIND_HOST |
127.0.0.1 |
docker-compose.yml |
Host interface docker-compose publishes the Redis sidecar on (#9286). The compose Redis runs without requirepass; app containers reach it over the compose network (redis:6379) — the published port exists only for host-side tooling. 0.0.0.0 exposes an unauthenticated Redis to the whole LAN. |
REDIS_PORT |
6379 |
docker-compose.yml |
Host port for the compose Redis sidecar. |
APP_BIND_HOST |
127.0.0.1 |
docker-compose.yml, docker-compose.prod.yml |
Host interface docker-compose publishes the app's own dashboard/API/live-WS ports on (#12568). With REQUIRE_API_KEY=false shipping as the .env.example default, 0.0.0.0 exposes the anonymous /v1 LLM proxy to the whole LAN/WAN — only widen once REQUIRE_API_KEY=true or a reverse proxy in front enforces its own auth. |
QDRANT_BIND_HOST |
127.0.0.1 |
docker-compose.yml |
Host interface docker-compose publishes the Qdrant memory sidecar on (#12578). Same LAN-exposure reasoning as REDIS_BIND_HOST. |
BIFROST_BIND_HOST |
127.0.0.1 |
docker-compose.yml |
Host interface docker-compose publishes the Bifrost router sidecar on (#12578). Same LAN-exposure reasoning as REDIS_BIND_HOST. |
REDIS_KEY_PREFIX |
omniroute: |
src/shared/utils/rateLimiter.ts |
Namespace prefix applied to every OmniRoute Redis key (rate limiter, auth cache, quota store, warmup circuit breaker). Prevents key collisions when the Redis instance is shared with other apps (#11042). |
OMNIROUTE_INTERNAL_SERVICE_TOKEN |
(unset — mechanism disabled) | src/lib/api/internalServiceAuth.ts |
Shared secret for identity-preserving internal REST hops (#9260): OmniRoute components calling other local OmniRoute routes send it as x-omniroute-internal-service-token so the original caller identity is preserved. Compared with timingSafeEqual. |
OMNIROUTE_INTERNAL_SERVICE_TOKEN_FILE |
(unset) | src/lib/api/internalServiceAuth.ts |
Secret-file variant of the internal service token: path to a file whose trimmed content is the token. Only consulted when the inline var is unset. |
OPENROUTER_PROVIDER_STATS_ENABLED |
true |
src/lib/catalog/openrouterProviderStats.ts |
Enrich the dashboard providers list with OpenRouter weekly ranking stats (#9324). On by default; set false to skip the background fetch entirely (non-blocking, never fatal). |
OPENROUTER_PROVIDER_STATS_TTL_MS |
86400000 (24h) |
src/lib/catalog/openrouterProviderStats.ts |
Cache TTL for the OpenRouter provider-stats snapshot, in milliseconds. |
OMNIROUTE_REDIS_IMAGE |
redis:7-alpine |
bin/cli/commands/redis.mjs |
Redis image used by the 1-click Redis launcher. Override to redis:8-alpine or a private registry mirror as needed. |
QDRANT_HOST |
qdrant |
(opt-in cluster profile) | Hostname of the Qdrant sidecar when --profile memory is active. Default points to the in-network qdrant service name; override for an external deployment. Only consumed when qdrantEnabled is true in code (src/lib/memory/vectorStore.ts:108). |
QDRANT_PORT |
6333 |
(opt-in cluster profile) | REST port of the Qdrant sidecar. |
QDRANT_GRPC_PORT |
6334 |
(opt-in cluster profile) | gRPC port of the Qdrant sidecar. Used by client libraries that prefer gRPC over REST for streaming ops. |
QDRANT_API_KEY |
(unset) | (opt-in cluster profile) | Optional API key for Qdrant Cloud or an authenticated on-prem instance. Empty → no api-key header sent. |
QDRANT_COLLECTION |
omniroute-memory |
(opt-in cluster profile) | Collection name for OmniRoute's conversation memory embeddings. Created on first run with QDRANT_VECTOR_SIZE dimensions. |
QDRANT_EMBEDDING_MODEL |
text-embedding-3-small |
(opt-in cluster profile) | Default embedding model name recorded in the Qdrant collection metadata. Actual embeddings are generated by whatever provider the embeddingModel field in OmniRoute's settings points to. |
QDRANT_VECTOR_SIZE |
1536 |
(opt-in cluster profile) | Embedding vector dimension. Must match the model you embed with (text-embedding-3-small → 1536; ada-002 → 1536; nomic-embed-text → 768). |
QDRANT_HNSW_EF_CONSTRUCT |
128 |
(opt-in cluster profile) | HNSW index construction-time accuracy. Higher = slower build, faster search. |
OMNIROUTE_ROTATION_ENABLED |
true |
open-sse/services/rotationConfig.ts |
Master switch for operator-configurable account rotation. When false, none of the OMNIROUTE_ROTATE_* classes below trigger account fallback (the master-off state also blocks the default-enabled 429/500/502 classes). Lets a supervising front-end (e.g. the VibeProxy desktop app) mirror its own rotation rules onto the backend's account-fallback engine. |
OMNIROUTE_ROTATION_RATE_LIMIT_RESET_SECONDS |
0 |
open-sse/services/rotationConfig.ts |
Cooldown (seconds) applied to a rate-limited account when the upstream gives no explicit reset hint. 0 = use the engine default cooldown instead of a fixed override. |
OMNIROUTE_ROTATION_DISABLE_TAG_WITHOUT_RESET |
true |
open-sse/services/rotationConfig.ts |
Mirror of the front-end "don't tag as rate-limited without a reset time" preference. |
OMNIROUTE_ROTATE_ON_429 |
true |
open-sse/services/rotationConfig.ts |
Per-status fallback enable for 429 errors. When false (and OMNIROUTE_ROTATION_ENABLED=true), a 429 no longer triggers account rotation and is returned to the client instead. |
OMNIROUTE_ROTATE_429_THRESHOLD |
1 |
open-sse/services/rotationConfig.ts |
Number of 429 errors within OMNIROUTE_ROTATE_429_WINDOW_SECONDS required before the account is rotated. 1 (default) rotates immediately, preserving historical behavior. |
OMNIROUTE_ROTATE_429_WINDOW_SECONDS |
120 |
open-sse/services/rotationConfig.ts |
Sliding window (seconds) over which 429 errors are counted toward OMNIROUTE_ROTATE_429_THRESHOLD. |
OMNIROUTE_ROTATE_ON_500 |
true |
open-sse/services/rotationConfig.ts |
Per-status fallback enable for 5xx server errors (excluding 502, which has its own class). When false, these errors no longer trigger account rotation. |
OMNIROUTE_ROTATE_500_THRESHOLD |
1 |
open-sse/services/rotationConfig.ts |
Number of 5xx errors within OMNIROUTE_ROTATE_500_WINDOW_SECONDS required before the account is rotated. 1 (default) rotates immediately. |
OMNIROUTE_ROTATE_500_WINDOW_SECONDS |
120 |
open-sse/services/rotationConfig.ts |
Sliding window (seconds) over which 5xx errors are counted toward OMNIROUTE_ROTATE_500_THRESHOLD. |
OMNIROUTE_ROTATE_ON_502 |
true |
open-sse/services/rotationConfig.ts |
Per-status fallback enable for 502 (bad gateway) errors. When false, 502s no longer trigger account rotation. |
OMNIROUTE_ROTATE_502_THRESHOLD |
1 |
open-sse/services/rotationConfig.ts |
Number of 502 errors within OMNIROUTE_ROTATE_502_WINDOW_SECONDS required before the account is rotated. 1 (default) rotates immediately. |
OMNIROUTE_ROTATE_502_WINDOW_SECONDS |
120 |
open-sse/services/rotationConfig.ts |
Sliding window (seconds) over which 502 errors are counted toward OMNIROUTE_ROTATE_502_THRESHOLD. |
OMNIROUTE_ROTATE_ON_400 |
false |
open-sse/services/rotationConfig.ts |
Opt-in (default OFF): when true, a plain 400 (bad request) also triggers account rotation. This is additive only — it never blocks the engine's existing behavior where a 400 carrying rate-limit/quota text still falls over regardless of this flag. |
OMNIROUTE_ROTATE_400_THRESHOLD |
1 |
open-sse/services/rotationConfig.ts |
Number of 400 errors within OMNIROUTE_ROTATE_400_WINDOW_SECONDS required before the account is rotated (only consulted when OMNIROUTE_ROTATE_ON_400=true). |
OMNIROUTE_ROTATE_400_WINDOW_SECONDS |
120 |
open-sse/services/rotationConfig.ts |
Sliding window (seconds) over which 400 errors are counted toward OMNIROUTE_ROTATE_400_THRESHOLD. |
Claude Warmup Scheduler
Cron-driven warmup for opted-in Anthropic OAuth connections, so the 5-hour rate-limit window is opened by a trivial scheduled request instead of by the first real one (#8848). The scheduler is off unless OMNIROUTE_WARMUP_ENABLED is truthy and the connection is flagged in settings.claudeWarmup.connections; an empty connection list means nothing is warmed even with the env var on.
| Variable | Default | Source File | Description |
|---|---|---|---|
OMNIROUTE_WARMUP_ENABLED |
(unset → off) | src/lib/warmupScheduler.ts |
Master switch for the warmup scheduler. Accepts 1/true/yes/on (case-insensitive, trimmed). Any other value, or unset, leaves the scheduler off. |
OMNIROUTE_WARMUP_CRON |
0 7 * * * |
src/lib/warmupScheduler.ts |
Five-field cron expression for the warmup tick, evaluated in America/Los_Angeles (Anthropic's reset timezone) regardless of the host clock. |
OMNIROUTE_WARMUP_CONCURRENCY |
3 |
src/lib/warmupScheduler.ts |
How many connections are warmed in parallel per tick. Clamped to 1-10; a non-numeric value falls back to 3. |
OMNIROUTE_WARMUP_MODEL |
claude-3-5-haiku-20241022 |
src/lib/warmupScheduler.ts |
Model used for the warmup request. Override only if the default is unavailable on your plan; pick the cheapest model that still opens the window. |
Browser-Login VNC Sessions & Data-Dir Alias
Containerized Chromium+VNC used for interactive browser-login credential capture (/api/vnc-session), plus a legacy DATA_DIR alias. All optional — the VNC defaults target the bundled omniroute-vnc-chromium:local image and are only overridden for a custom container image, ports, or lifecycle tuning.
| Variable | Default | Source File | Description |
|---|---|---|---|
OMNIROUTE_VNC_IMAGE |
omniroute-vnc-chromium:local |
src/lib/vncSession/manifest.ts |
Docker image tag for the Chromium+VNC login container. Build docker/vnc-browser/chromium or point this at a custom image. |
OMNIROUTE_DOCKER_BIN |
docker |
src/lib/vncSession/manifest.ts |
Container runtime binary used to launch the VNC container (e.g. set to podman). |
OMNIROUTE_VNC_CONTAINER_VNC_PORT |
3000 |
src/lib/vncSession/manifest.ts |
VNC/noVNC port exposed inside the container. |
OMNIROUTE_VNC_CONTAINER_CDP_PORT |
9223 |
src/lib/vncSession/manifest.ts |
Chrome DevTools Protocol port inside the container. |
OMNIROUTE_VNC_CONTAINER_PROFILE_DIR |
/config |
src/lib/vncSession/manifest.ts |
Chromium profile directory path inside the container. |
OMNIROUTE_VNC_PROFILE_DIR |
$HOME/.omniroute/browser-login-profiles |
src/lib/vncSession/manifest.ts |
Host directory holding persisted browser-login profiles. |
OMNIROUTE_VNC_IDLE_MS |
600000 (10 min) |
src/lib/vncSession/manifest.ts |
Idle timeout (ms) before an inactive VNC session is reaped. |
OMNIROUTE_VNC_MAX_MS |
1800000 (30 min) |
src/lib/vncSession/manifest.ts |
Hard cap (ms) on a single VNC session's lifetime. |
OMNIROUTE_VNC_MAX_SESSIONS |
4 |
src/lib/vncSession/manifest.ts |
Maximum number of concurrent VNC sessions. |
OMNIROUTE_VNC_READY_MS |
45000 |
src/lib/vncSession/manifest.ts |
Timeout (ms) waiting for the containerized browser to become CDP-ready. |
OMNIROUTE_VNC_HARVEST_MS |
20000 |
src/lib/vncSession/manifest.ts |
Timeout (ms) for harvesting the captured session/cookies after login completes. |
OMNIROUTE_VNC_CHROMIUM_ARGS |
--remote-debugging-port=9222 --no-first-run --no-default-browser-check |
src/lib/vncSession/manifest.ts |
Extra command-line flags passed to the containerized Chromium. |
OMNIROUTE_VNC_NETWORK |
omniroute-vnc-browser-login |
src/lib/vncSession/manifest.ts |
Dedicated Docker network the VNC login container joins (#12571) instead of the default bridge, so sibling containers can't reach its CDP bridge port. |
VIBEPROXY_DATA_DIR |
(unset) | open-sse/services/notionThreadSessions.ts |
Legacy alias for DATA_DIR, checked only after both DATA_DIR and OMNIROUTE_DATA_DIR are unset. Locates the Notion web-thread session cache (<dir>/notion-web-thread-sessions.json). |
26. Test & E2E Harness
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. Leave every
value below unset in production deployments.
| Variable | Default | Source File | Description |
|---|---|---|---|
OMNIROUTE_E2E_BOOTSTRAP_MODE |
auth |
scripts/dev/run-next-playwright.mjs |
E2E bootstrap mode (auth, fresh, reuse) for the Playwright runner. |
OMNIROUTE_E2E_PASSWORD |
falls back to INITIAL_PASSWORD |
scripts/dev/run-next-playwright.mjs |
Admin password injected into the Playwright environment. |
OMNIROUTE_DISABLE_LOCAL_HEALTHCHECK |
true |
scripts/dev/run-next-playwright.mjs |
Disable the local healthcheck poll during Playwright runs. |
OMNIROUTE_DISABLE_TOKEN_HEALTHCHECK |
true |
scripts/dev/run-next-playwright.mjs |
Disable the OAuth token healthcheck loop during tests. |
OMNIROUTE_HEALTHCHECK_SKIP_PROVIDERS |
(unset) | src/lib/tokenHealthCheck.ts |
Comma-separated providers excluded from the proactive token-refresh sweep (e.g. codex,openai). Targeted alternative to fully disabling the healthcheck — short-TTL providers keep refreshing while cascade providers stay reactive-only. |
OMNIROUTE_HIDE_HEALTHCHECK_LOGS |
true |
scripts/dev/run-next-playwright.mjs |
Silence healthcheck noise in Playwright stdout. |
OMNIROUTE_PLAYWRIGHT_SKIP_BUILD |
0 |
scripts/dev/run-next-playwright.mjs |
Skip the Next.js production build before Playwright starts (CI optimization). |
OMNIROUTE_SKIP_UNINSTALL_HOOK |
0 |
scripts/build/uninstall.mjs |
Skip the OmniRoute uninstall hook (used by CI to keep node_modules intact). |
ECOSYSTEM_SERVER_WAIT_MS |
180000 |
scripts/dev/run-ecosystem-tests.mjs |
Wait time (ms) for the server to become healthy before running ecosystem/protocol tests. |
ELECTRON_SMOKE_URL |
http://127.0.0.1:20128/login |
scripts/dev/smoke-electron-packaged.mjs |
URL the Electron smoke harness expects the packaged app to serve. |
ELECTRON_SMOKE_TIMEOUT_MS |
45000 |
scripts/dev/smoke-electron-packaged.mjs |
Total timeout (ms) before the smoke harness gives up. |
ELECTRON_SMOKE_SETTLE_MS |
2000 |
scripts/dev/smoke-electron-packaged.mjs |
Settle window (ms) after the page loads. |
ELECTRON_SMOKE_APP_EXECUTABLE |
(auto) | scripts/dev/smoke-electron-packaged.mjs |
Explicit path to the packaged Electron executable. |
ELECTRON_SMOKE_DATA_DIR |
(tmpdir) | scripts/dev/smoke-electron-packaged.mjs |
Data directory for the Electron smoke run. |
ELECTRON_SMOKE_KEEP_DATA |
0 |
scripts/dev/smoke-electron-packaged.mjs |
Set 1 to preserve the smoke data directory after the run. |
ELECTRON_SMOKE_STREAM_LOGS |
0 |
scripts/dev/smoke-electron-packaged.mjs |
Set 1 to stream Electron logs to stdout during the run. |
ELECTRON_SMOKE_COLD_RESTART |
0 |
scripts/dev/smoke-electron-packaged.mjs |
#7592: relaunch against the same data dir and assert the second launch selects the native SQLite driver. |
OMNI_COVERAGE_ROOT |
(unset) | scripts/quality/coverage-node-register.mjs |
Repository root used by the coverage capture harness (Node register hook + Vitest provider) to resolve the exact-commit coverage source scope. Set by the quality harness only; leave unset in production. |
CLI_DEVIN_BIN |
(PATH lookup) | open-sse/executors/devin-cli.ts |
Override the Devin CLI binary path. |
Docs translation pipeline
Used by scripts/i18n/run-translation.mjs (the npm run i18n:run command).
All six variables are unset by default — set them in .env only on machines
that should be able to run the docs translator.
| Variable | Default | Source File | Description |
|---|---|---|---|
OMNIROUTE_TRANSLATION_API_URL |
(unset) | scripts/i18n/run-translation.mjs |
OpenAI-compatible base URL for the translation backend. |
OMNIROUTE_TRANSLATION_API_KEY |
(unset) | scripts/i18n/run-translation.mjs |
Bearer token for the translation backend (never logged). |
OMNIROUTE_TRANSLATION_MODEL |
(unset) | scripts/i18n/run-translation.mjs |
Model id, e.g. gpt-4o-mini or cx/gpt-5.4-mini. |
OMNIROUTE_TRANSLATION_FALLBACK_MODELS |
(unset) | scripts/i18n/lib/translate-backend.mjs |
Optional comma-separated model chain tried in order when the primary model fails (429 quota, 401/402, 5xx, timeout, network); a malformed request (400/413/422) is not retried elsewhere. |
OMNIROUTE_TRANSLATION_TIMEOUT_MS |
60000 |
scripts/i18n/run-translation.mjs |
Per-request timeout in milliseconds. |
OMNIROUTE_TRANSLATION_REASONING_EFFORT |
(unset) | scripts/i18n/lib/translate-backend.mjs |
Optional reasoning control, sent as-is to the backend when set. |
OMNIROUTE_TRANSLATION_CONCURRENCY |
4 |
scripts/i18n/run-translation.mjs |
Parallel translation requests when running over multiple files / locales. |
OMNIROUTE_TRANSLATION_ENGINE |
llm |
scripts/i18n/run-translation.mjs |
llm uses the backend above; google translates through the structure-safe Google engine and needs none of the LLM variables. |
OMNIROUTE_TRANSLATION_GOOGLE_FALLBACK |
1 |
scripts/i18n/run-translation.mjs |
With the llm engine, a chunk the model could not produce (output guard failed on every attempt, or a model error) is translated by Google instead of failing the locale. 0 disables it. |
OMNIROUTE_TRANSLATION_GOOGLE_API_KEY |
(unset) | scripts/i18n/lib/google-translate.mjs |
Optional Cloud Translation v2 key. Unset uses the keyless web endpoint (rate-limited, fine for occasional waves). |
OMNIROUTE_TRANSLATION_GOOGLE_CONCURRENCY |
6 |
scripts/i18n/lib/google-translate.mjs |
Parallel Google requests shared by every locale of a run. |
OMNIROUTE_TRANSLATION_GOOGLE_TIMEOUT_MS |
30000 |
scripts/i18n/lib/google-translate.mjs |
Per-request timeout for the Google engine, in milliseconds. |
UI_KIT_READ_TOKEN |
(unset) | scripts/check/check-ui-kit-upstream.mjs |
Read-only token for the private upstream UI kit repo, used by npm run check:ui-kit-upstream and the weekly "UI Kit upstream watch" workflow. Locally the check uses your git credentials. |
27. Radar Feed (Self-Hosting)
Optional add-on gated by the RADAR_ENABLED feature flag (default off — a feature
flag toggled via Settings/DB, not an env var; see
docs/frameworks/RADAR.md).
The first four variables below are optional overrides for a self-hosted or forked feed and
supporter-key flows. The fifth, RADAR_ADMIN_URL, is a separate default-free link to the owner's
private operations panel. See docs/frameworks/RADAR.md for the full
module doc and its
end-to-end activation and guided-setup sequence.
The generic Home/Changelog announcement reader is not configured by an environment
variable and does not depend on the RADAR_ENABLED feature flag. It reads the public repository
news.json URL declared in src/shared/utils/releaseNotes.ts by
GET only; dismissal IDs remain in browser local storage.
| Variable | Default | Source File | Description |
|---|---|---|---|
RADAR_FEED_URL |
https://radar.omniroute.online |
src/lib/radar/{sync,referralsSync,offersSync,intelSync}.ts |
Base URL shared by the separately signed catalog, referrals, supporter-offers, and Intel feeds. Override to point at a self-hosted or forked service. |
RADAR_FEED_PUBKEY |
(pinned default key) | src/lib/radar/pinnedKeys.ts |
Ed25519 public key (base64-DER SPKI or PEM) used to verify feed signatures from a custom feed. |
RADAR_CONTRIBUTOR_CLAIM_URL |
https://radar.omniroute.online/auth/github |
src/lib/radar/links.ts |
URL the "I'm a contributor" dashboard button opens (GitHub OAuth supporter-key claim flow). |
RADAR_SUPPORTER_PLANS_URL |
https://radar.omniroute.online/planos |
src/lib/radar/links.ts |
URL the "Support the project" dashboard button opens (payment/plans page). |
RADAR_ADMIN_URL |
(unset) | src/lib/radar/links.ts |
Owner-only private operations-panel link. HTTPS is required except for an HTTP loopback SSH forward; unset or invalid values create no navigation item. |
Audit: Removed / Dead Variables
The following variables appeared in previous versions of .env.example but have no runtime references in the current codebase. They have been removed:
| Variable | Reason |
|---|---|
STORAGE_DRIVER=sqlite |
Never read by any source file. SQLite is the only supported driver — no selection needed. |
INSTANCE_NAME=omniroute |
Present in old docs/env templates but unused at runtime. May return in a future multi-instance feature. |
SQLITE_MAX_SIZE_MB=2048 |
Not referenced in source code. Database size is not artificially limited. |
SQLITE_CLEAN_LEGACY_FILES=true |
Not referenced in source code. Legacy cleanup was likely removed. |
CLI_ROO_BIN |
Not registered in src/shared/services/cliRuntime.ts. |
CLI_KIMI_CODING_BIN |
Not registered in src/shared/services/cliRuntime.ts (Kimi Coding uses OAuth, not a CLI binary). |
IFLOW_OAUTH_CLIENT_ID / IFLOW_OAUTH_CLIENT_SECRET |
Not referenced anywhere in source code. |
CEREBRAS_API_KEY / COHERE_API_KEY / FIREWORKS_API_KEY / GROQ_API_KEY / MISTRAL_API_KEY / NEBIUS_API_KEY / PERPLEXITY_API_KEY / TOGETHER_API_KEY / XAI_API_KEY |
Removed in v3.8.0. The runtime no longer reads these env vars — credentials come from Dashboard / data/provider-credentials.json / encrypted DB. |
CURSOR_PROTOBUF_DEBUG |
Removed in v3.8.0. Cursor executor uses CURSOR_DEBUG / CURSOR_STREAM_DEBUG (see §22). |
CLI_COMPAT_KIRO |
Removed in v3.8.0. Kiro is in CLI_COMPAT_OMITTED_PROVIDER_IDS — its toggle has no effect. |
QIANFAN_API_KEY |
Removed alongside other unused provider API key stubs in v3.8.0. |
Default Value Corrections
| Variable | Old .env.example Value |
Actual Code Default | Fixed |
|---|---|---|---|
APP_LOG_RETENTION_DAYS |
90 |
7 |
✅ Removed misleading value; documented 7 as default |
CALL_LOG_RETENTION_DAYS |
90 |
7 |
✅ Removed misleading value; documented 7 as default |
OpenCode config regeneration (ad-hoc tooling)
Used by scripts/ad-hoc/regen-opencode-config.ts to regenerate an opencode.json
with accurate limit.context and limit.output values pulled from the running
OmniRoute instance. None of these are required for normal operation — the script
is developer tooling only.
| Variable | Default | Source File | Description |
|---|---|---|---|
OMNIROUTE_URL |
http://localhost:20128 |
scripts/ad-hoc/regen-opencode-config.ts |
Base URL of the OmniRoute instance to query for /v1/models. |
OMNIROUTE_KEY |
(unset) | scripts/ad-hoc/regen-opencode-config.ts |
API key to authenticate against the OmniRoute /v1/models endpoint. Falls back to OPENCODE_API_KEY when unset. |
OPENCODE_API_KEY |
(unset) | scripts/ad-hoc/regen-opencode-config.ts |
OpenCode-style API key (sk-...) written into the regenerated opencode.json. Falls back to OMNIROUTE_KEY when unset. |
Compression offline-eval harness (ad-hoc tooling)
Used by scripts/compression-eval/index.ts, the offline compression evaluation CLI.
Not required for normal operation — developer tooling only.
| Variable | Default | Source File | Description |
|---|---|---|---|
OMNIROUTE_EVAL_CREDENTIALS |
{} (empty) |
scripts/compression-eval/index.ts |
Operator-supplied JSON credentials for the provider exercised by the offline compression-eval CLI (parsed with JSON.parse). Leave unset for a dry run. |
VNC Browser Sessions
Used by src/lib/vncSession/manifest.ts to configure Docker-based headless Chromium sessions for browser-automation providers. All optional — defaults shown below.
| Variable | Default | Source File | Description |
|---|---|---|---|
OMNIROUTE_DOCKER_BIN |
docker |
src/lib/vncSession/manifest.ts |
Path to the Docker binary used to spawn VNC containers. |
OMNIROUTE_VNC_IMAGE |
omniroute-vnc-chromium:local |
src/lib/vncSession/manifest.ts |
Docker image for the VNC Chromium container. |
OMNIROUTE_VNC_CHROMIUM_ARGS |
(built-in flags) | src/lib/vncSession/manifest.ts |
Extra Chromium CLI args passed to the browser inside the container. |
OMNIROUTE_VNC_CONTAINER_VNC_PORT |
3000 |
src/lib/vncSession/manifest.ts |
VNC port inside the container. |
OMNIROUTE_VNC_CONTAINER_CDP_PORT |
9223 |
src/lib/vncSession/manifest.ts |
Chrome DevTools Protocol port inside the container. |
OMNIROUTE_VNC_CONTAINER_PROFILE_DIR |
/config |
src/lib/vncSession/manifest.ts |
Profile directory inside the container. |
OMNIROUTE_VNC_PROFILE_DIR |
(unset) | src/lib/vncSession/manifest.ts |
Host-side directory for persistent browser profiles. |
OMNIROUTE_VNC_IDLE_MS |
600000 |
src/lib/vncSession/manifest.ts |
Idle timeout (ms) before a VNC session is harvested. |
OMNIROUTE_VNC_MAX_MS |
1800000 |
src/lib/vncSession/manifest.ts |
Maximum session duration (ms). |
OMNIROUTE_VNC_MAX_SESSIONS |
4 |
src/lib/vncSession/manifest.ts |
Maximum concurrent VNC sessions. |
OMNIROUTE_VNC_READY_MS |
45000 |
src/lib/vncSession/manifest.ts |
Browser readiness timeout (ms). |
OMNIROUTE_VNC_HARVEST_MS |
20000 |
src/lib/vncSession/manifest.ts |
Harvest/cleanup timeout (ms). |
OMNIROUTE_VNC_NETWORK |
omniroute-vnc-browser-login |
src/lib/vncSession/manifest.ts |
Dedicated Docker network the container joins (#12571), off the default bridge. |
VIBEPROXY_DATA_DIR |
(unset) | open-sse/services/notionThreadSessions.ts |
Directory for Notion thread session persistence. |
Internal service auth
| Variable | Default | Description |
|---|---|---|
OMNIROUTE_INTERNAL_SERVICE_TOKEN |
– | Inline token for management-plane service-to-service authentication. |
OMNIROUTE_INTERNAL_SERVICE_TOKEN_FILE |
– | Path to a file containing the internal service token (preferred in containers; overrides the inline variable). |
OpenRouter provider stats
| Variable | Default | Description |
|---|---|---|
OPENROUTER_PROVIDER_STATS_ENABLED |
true |
Set to false to skip fetching OpenRouter per-provider stats for catalog enrichment. |
OPENROUTER_PROVIDER_STATS_TTL_MS |
3600000 |
Cache TTL (ms) for the fetched OpenRouter provider stats. |
Embedded Redis binding
| Variable | Default | Description |
|---|---|---|
REDIS_BIND_HOST |
127.0.0.1 |
Bind address for the embedded Redis service. |
REDIS_PORT |
6379 |
Port for the embedded Redis service. |
OMNIROUTE_REDIS_BIND_HOST |
– | OmniRoute-scoped override for the embedded Redis bind address. |
24. Release v3.8.50 additions
These settings were introduced after the previous environment-contract snapshot.
| Variable | Default | Source File | Description |
|---|---|---|---|
OMNIROUTE_CHAT_ADMISSION_QUEUE_MS |
2000 |
src/shared/middleware/chatBodyAdmission.ts |
Maximum wait for a heavyweight chat admission slot before a retryable 503; a short bounded wait serializes agent bursts instead of an instant 503. 0 restores immediate rejection. |
OMNIROUTE_CHAT_ADMISSION_MAX_QUEUED_BYTES |
4194304 (4 MB) |
src/shared/middleware/chatBodyAdmission.ts |
Queued-bytes budget for the admission wait: bounds total buffered body bytes parked process-wide so the wait cannot amplify the heap (#4380). Over-budget waits receive a retryable 503 immediately. |
OMNIROUTE_CHAT_VIRTUAL_TTL_MS |
60000 (60 s) |
src/shared/middleware/chatBodyAdmission.ts |
Deprecated no-op since #10110: per-session admission lanes were removed in favor of one process-wide budget. Accepted for configuration compatibility; ignored. |
OMNIROUTE_CHAT_VIRTUAL_MAX_SESSIONS |
64 |
src/shared/middleware/chatBodyAdmission.ts |
Deprecated no-op since #10110: per-session admission lanes were removed in favor of one process-wide budget. Accepted for configuration compatibility; ignored. |
OMNIROUTE_CHAT_VIRTUAL_LANES |
0 (off) |
open-sse/services/admission/runtime.ts |
Adaptive runtime virtual admission lanes (#9654): master switch for the per-tenant adaptive gate (system 2). Distinct from the deprecated per-connection lane vars above (TTL_MS / MAX_SESSIONS, no-ops since #10110). Dashboard feature flag of the same name; the env var wins over the dashboard override; requires restart. |
OMNIROUTE_RUNNOW_TIMEOUT_MS |
30000 |
src/app/api/jobs/[id]/run-now/route.ts |
Bounds how long a run-now call waits for an in-flight job before starting the queued run. |
ADOBE_FIREFLY_BROWSER_REFRESH |
enabled | open-sse/services/adobeFireflySession.ts |
Keeps IMS and browser-risk state fresh through account-scoped Chrome CDP sessions; set 0 to disable. |
ADOBE_FIREFLY_SESSION_DISK |
enabled | open-sse/services/adobeFireflySession.ts |
Persists repaired Adobe sessions under DATA_DIR; set 0 for memory-only state. |
ADOBE_FIREFLY_MIN_SUBMIT_GAP_MS |
12000 |
open-sse/services/adobeFireflySession.ts |
Minimum spacing between Adobe Firefly generate submissions. |
ADOBE_FIREFLY_BATCH_EXTRA_GAP_MS |
15000 |
open-sse/services/adobeFireflySession.ts |
Extra quiet period after every third successful Adobe submission. |
ADOBE_FIREFLY_CHROME_HEADLESS |
0 |
open-sse/services/adobeFireflyBrowserLogin.ts |
Debug-only true-headless mode; Adobe colligo normally rejects the resulting risk session. |
CHROME_PATH |
auto-detect | open-sse/executors/cloudflare-playground.ts, open-sse/executors/chatgpt-web-codex.ts |
Optional absolute Chrome executable used by the browser-driven executors when platform auto-detection is insufficient. |
TELEGRAM_BOT_TOKEN |
(unset) | src/lib/telegram/config.ts |
BotFather token that enables the inbound webhook and signs Mini App initData. |
TELEGRAM_WEBHOOK_SECRET |
(unset) | src/lib/telegram/config.ts |
Shared secret registered via setWebhook and verified against the X-Telegram-Bot-Api-Secret-Token header on every webhook delivery. Required for the webhook path; unset means webhook deliveries are refused with 503. |
TELEGRAM_DEFAULT_MODEL |
auto/chat |
src/lib/telegram/chatProxy.ts |
Model used for Telegram chat replies. |
TELEGRAM_BOT_API_BASE |
https://api.telegram.org |
src/lib/telegram/config.ts |
Bot API base URL override for proxies or self-hosted Bot API servers. |
TELEGRAM_WEBHOOK_TIMEOUT_MS |
60000 |
src/lib/telegram/config.ts |
Timeout in milliseconds for outbound Bot API calls. |
TELEGRAM_USER_ALLOWLIST_ENABLED |
false |
src/lib/telegram/config.ts |
Set to true to serve only the Telegram users listed in TELEGRAM_ALLOWED_USER_IDS (others: Mini App 403, webhook message dropped). Off by default: every Telegram user is served and gets a minted API key that spends upstream quota. |
TELEGRAM_ALLOWED_USER_IDS |
(unset) | src/lib/telegram/config.ts |
Comma-separated numeric Telegram user ids served when TELEGRAM_USER_ALLOWLIST_ENABLED=true. Entries that are not plain positive integers are ignored with a one-time warning. Ignored while the allowlist is off; empty with the allowlist on serves nobody. |
OMNIROUTE_OPTIONAL_PACK_TAR |
1 (enabled) |
scripts/build/optionalPackStaging.mjs |
Set 0 to skip emitting .tar.gz tarballs while staging optional ML/browser packs for the Electron standalone tree (pack directories and optional-packs.index.json are still produced). Used by the desktop release workflow to trim artifact upload size. |
GROK_SUBSCRIPTION_IMAGES_ENABLED |
false |
open-sse/config/imageRegistry.ts |
Enables registration of the xAI subscription image routes; disabled by default so the API-key image path remains unchanged. |
OMNIROUTE_API_KEY_COOLDOWN_MS |
60000 |
open-sse/services/apiKeyRotator.ts |
Per-key cooldown in milliseconds when a 429 response has no usable Retry-After hint. |
OMNIROUTE_ESTIMATOR_CALIBRATION |
enabled | open-sse/services/estimatorCalibration.ts |
Set to off, 0, or false to disable in-memory estimator calibration recording and application. |
NEXT_MANUAL_SIG_HANDLE |
(internal) | scripts/dev/standalone-server-ws.mjs |
Internal standalone-server signal-handler override; normally set and cleared by the launcher rather than configured by operators. |
CHATGPT_WEB_TURN_TIMEOUT_MS |
180000 |
open-sse/utils/chatgptWebExecutorAdapter.ts |
Per-turn ceiling for a ChatGPT Web (Clean Room) text turn; values below 1000 are ignored. |
CHATGPT_WEB_TOOL_TURN_TIMEOUT_MS |
180000 |
open-sse/utils/chatgptWebExecutorAdapter.ts |
Per-turn ceiling for a ChatGPT Web (Clean Room) turn that carries client tools (emulated <tool> envelope); lower it to return control to the client sooner. Values below 1000 are ignored. |
CHATGPT_WEB_HEADLESS |
1 (headless) |
open-sse/utils/chatgptWebExecutorAdapter.ts |
Run the ChatGPT Web (Clean Room) browser headless. Set 0 only for accounts whose first-party challenge rejects headless mode (the default changed from headed to headless in #14948). |
CHATGPT_WEB_BROWSER_ACQUIRE_TIMEOUT_MS |
45000 |
open-sse/utils/chatgptWebExecutorAdapter.ts |
Ceiling for launching the ChatGPT Web (Clean Room) browser and warming up chatgpt.com, so a dead browser or session cannot consume the request-queue deadline. |
UI_KIT_CLONE |
_references/cheaper-inference-ui-kit |
scripts/check/check-ui-kit-snapshot.mjs |
Path of the private CI UI Kit clone the vendored-snapshot gate diffs packages/ui-kit/src against (KEA-7886); the gate skips with a warning when the clone is absent. |
ChatGPT Web (Codex)
Globale Defaults für den headless Browser und den ausgehenden Tool-Tunnel. Im Dashboard gesetzte Connection-Werte haben Vorrang.
| Variable | Default | Source File | Description |
|---|---|---|---|
CHATGPT_WEB_CODEX_CHROME_PATH |
(auto-detect) | open-sse/executors/chatgpt-web-codex.ts |
Expliziter Chrome-/Chromium-Pfad für npm-, systemd- und PM2-Betrieb. |
CHROME_PATH |
(auto-detect) | open-sse/executors/chatgpt-web-codex.ts |
Gemeinsamer Fallback für einen expliziten Chrome-/Chromium-Pfad. |
CHATGPT_WEB_CODEX_CDP_URL |
(unset) | open-sse/executors/chatgpt-web-codex.ts |
Interner CDP-Endpunkt; Docker verwendet den Sidecar auf Port 9223. |
CHATGPT_WEB_CODEX_USE_CDP_PROFILE |
(unset — off) | open-sse/vendor/codex-chatgpt-web/persistent-cdp-context.ts |
Set to 1 (with a CDP endpoint configured) to reuse the externally managed, signed-in browser profile's existing ChatGPT page instead of an isolated context per turn; also caps concurrent ChatGPT tabs at 1. Off by default. See persistent CDP profile. |
CDP_PROXY_TOKEN |
(unset) | docker/chatgpt-web-codex-browser/cdp-proxy.mjs |
Wenn gesetzt, muss jede Anfrage an den CDP-Proxy-Sidecar diesen Wert im Header X-Omni-Cdp-Token mitschicken (#13679). Ohne Wert leitet der Proxy unauthentifiziert weiter — dann schützt nur die Netzisolierung des Compose-Netzes chatgpt-web-codex-net. Erzeugen mit openssl rand -hex 32. |
CHATGPT_WEB_CODEX_TUNNEL_ID |
(unset) | open-sse/executors/chatgpt-web-codex.ts |
Globale OpenAI-Tunnel-ID für lokale Codex-Tool-Runden. |
CHATGPT_WEB_CODEX_RUNTIME_KEY |
(unset) | open-sse/executors/chatgpt-web-codex.ts |
Globaler Tunnel Runtime-Key; niemals in Logs ausgeben. |
CHATGPT_WEB_CODEX_CONNECTOR_NAME |
OmniRoute Codex v2 |
open-sse/executors/chatgpt-web-codex.ts |
Exakter Name des neu erstellten ChatGPT-Custom-Connectors für die MCP-Brücke. |
CODEX_CHATGPT_WEB_HOME |
<DATA_DIR>/chatgpt-web-codex |
open-sse/vendor/codex-chatgpt-web/config.ts |
Dediziertes Verzeichnis für Browser-, Broker- und Tunnelzustand. |
CODEX_CHATGPT_WEB_BROWSER_DIAGNOSTICS |
0 |
open-sse/vendor/codex-chatgpt-web/adapters/chatgpt-web/browser-worker.ts |
Bei 1 werden Browser-Diagnosebilder an jedem Checkpoint erfasst. |
CODEX_CHATGPT_WEB_LAUNCHER |
(unset) | open-sse/vendor/codex-chatgpt-web/config.ts |
Optionaler absoluter Pfad zu einem dauerhaften Launcher-Binary. |
CODEX_CHATGPT_WEB_BUN |
(auto-detect) | open-sse/vendor/codex-chatgpt-web/config.ts |
Optionaler absoluter Pfad zum Bun-Runtime-Binary. |
CODEX_WEB_GPT_BUN |
(unset) | open-sse/vendor/codex-chatgpt-web/config.ts |
Legacy-Fallback für CODEX_CHATGPT_WEB_BUN; neue Setups verwenden den kanonischen Namen. |
OmniConductor Bridge
Long-lived SSE consumer that mirrors OmniConductor hub tasks into the local A2A TaskManager (src/lib/conductor/). Opt-in — the bridge only starts when CONDUCTOR_HUB_URL is set. Server-side only: the hub token must never reach the browser.
| Variable | Default | Source File | Description |
|---|---|---|---|
CONDUCTOR_HUB_URL |
(empty) | src/lib/conductor/boot.ts |
Base URL of the OmniConductor hub (e.g. http://127.0.0.1:7910). Unset = bridge disabled. |
CONDUCTOR_HUB_TOKEN |
(empty) | src/lib/conductor/boot.ts |
Hub credential for the SSE feed — emit a spokesperson-kind peer on the hub (POST /v1/peers, admin). |
CONDUCTOR_ORCHESTRATOR_TOKEN |
(empty) | src/lib/conductor/hubProxy.ts |
Credential for inbound A2A→hub task delegation (POST /v1/tasks); falls back to CONDUCTOR_HUB_TOKEN when unset. |
CONDUCTOR_SPOKESPERSON_URL |
http://127.0.0.1:7920 |
src/lib/conductor/faroProxy.ts |
Base URL of the spokesperson (Faro) service behind the dashboard chat proxy (/api/conductor/ask). |
Video Bridge isolated validation
scripts/ad-hoc/video-live-isolation.ts --prepare requires
OMNIROUTE_VIDEO_LIVE_SOURCE_DIR to name an absolute directory containing
storage.sqlite. There is no default. The tool opens that database read-only and
prepares a private temporary copy with isolated client keys and settings;
credentials remain on the validation host. This variable is only for the explicit
preparation command and is not consumed by normal server startup. Preparation
does not call a model; the separate live smoke command requires --execute-real.
Preparation requires a fresh process: it refuses a database module or connection
already bound to another directory before changing client keys or settings. The
loopback STT component accepts only the generated isolated owner key and claims
one request before reading its body; concurrent requests are rejected.
Quota-aware scheduling
Used by open-sse/services/combo.ts and src/lib/quota/quotaScheduler.ts for pre-request token-budget checks. Opt-in — default routing behavior is unchanged when unset.
| Variable | Default | Source File | Description |
|---|---|---|---|
OMNIROUTE_QUOTA_AWARE_ROUTING |
0 |
open-sse/services/combo.ts |
When 1, skip connections whose per-window token budget (rateLimitOverrides.tpm, table provider_quota_state) cannot afford the estimated request cost before dispatch. Fail-open when no budget configured. |
OMNIROUTE_ESTIMATOR_CALIBRATION |
(on) | open-sse/services/estimatorCalibration.ts |
Feedback calibration of the context-guard token estimator (#14931): per (provider, model, tools present) EMA of usage.prompt_tokens / estimate, clamped to 0.15–2.0, in memory only. off, 0 or false disables recording and application. |
GROK_SUBSCRIPTION_IMAGES_ENABLED |
false |
open-sse/config/imageRegistry.ts |
Registers the xai-oauth (xao) and grok-cli image routes. Dashboard feature flag of the same name; a DB override wins over this value. |
Model synchronization diagnostics
| Variable | Default | Source File | Description |
|---|---|---|---|
OMNIROUTE_MODEL_SYNC_TIMINGS |
0 |
src/lib/providerModels/modelSyncTimings.ts |
Set to 1 to log phase timing, a generated request ID and phase success/error outcomes during model synchronization. Disabled for all other values. Logs omit request, account, catalog and error payloads. |
Local OpenCode media-analysis tool
Used by scripts/cli/omniroute-media-mcp.mjs. Set these in the local tool process environment.
| Variable | Default | Description |
|---|---|---|
OMNIROUTE_MEDIA_CONFIG |
$XDG_CONFIG_HOME/opencode/opencode.json (or ~/.config/opencode/opencode.json) |
OpenCode configuration read by the media tool and installer. |
OMNIROUTE_MEDIA_PROVIDER |
omniroute |
Provider entry read from the OpenCode configuration by the media tool. |
OMNIROUTE_MEDIA_MODEL |
auto |
Model submitted by the media tool. Its provider must support the requested media types. |
OMNIROUTE_MEDIA_API_KEY |
Configured provider API key or its environment reference | Optional credential override. Keep it in the local process environment; never commit it. |
Session tracking
| Variable | Default | Source File | Description |
|---|---|---|---|
OMNIROUTE_SESSION_TTL_MIN |
15 |
open-sse/services/sessionManager.ts |
Idle TTL in minutes for the in-memory session map. Governs sticky connection reuse (getSessionConnection) and the active-sessions views; raising it keeps a session pinned to its connection longer. Read once at startup. Blank, non-numeric or <= 0 values fall back to the default. |