How Environment Variables Control Provider Behavior in OmniRoute: A Complete Configuration Guide

OmniRoute determines which LLM providers are available and how they authenticate entirely from environment variables read at import-time, enabling or disabling providers through flag checks without code modifications.

OmniRoute uses a purely configuration-driven architecture where environment variables determine provider availability, authentication, and operational parameters. This design allows operators to enable, disable, or reconfigure LLM providers entirely through environment configuration. Understanding how these variables control the provider lifecycle—from registration through request execution—is essential for deploying and managing OmniRoute instances.

Provider Enablement via Environment Flags

OmniRoute categorizes providers into free-proxy services and commercial API-key services, each using distinct environment variable patterns for activation.

Free-Proxy Provider Configuration

The free-proxy modules in src/lib/freeProxyProviders/ use boolean flags to control registration. Each provider exports an isEnabled() helper that checks specific process.env variables at import-time.

OneProxy (src/lib/freeProxyProviders/oneproxy.ts, lines 35-41):

• FREE_PROXY_1PROXY_ENABLED – When set to "false", the provider returns false from isEnabled() and is excluded from the catalog
• FREE_PROXY_1PROXY_API_URL – Base endpoint URL
• FREE_PROXY_1PROXY_MAX – Maximum connection limit

Proxifly (src/lib/freeProxyProviders/proxifly.ts, lines 58-68):

• FREE_PROXY_PROXIFLY_ENABLED
• FREE_PROXY_PROXIFLY_QUANTITY
• FREE_PROXY_PROXIFLY_ANONYMITY

Webshare (src/lib/freeProxyProviders/webshare.ts, lines 37-45):

• FREE_PROXY_WEBSHARE_ENABLED
• FREE_PROXY_WEBSHARE_API_KEY
• FREE_PROXY_WEBSHARE_API_URL
• FREE_PROXY_WEBSHARE_MAX

If any ENABLED flag equals "false", the module prevents registration in the global provider catalog defined in src/shared/constants/providers.ts.

OAuth and API-Key Providers

Commercial providers rely on direct API key injection. The DefaultExecutor in open-sse/executors/default.ts reads provider-specific variables—such as process.env.OPENAI_API_KEY, ANTIGRAVITY_CLIENT_ID, ANTIGRAVITY_CLIENT_SECRET, and GEMINI_API_KEY—when constructing request headers. Missing keys trigger configuration errors that exclude the provider from the active catalog.

Configuration Patterns in OmniRoute Providers

Understanding when and how environment variables are evaluated is critical for managing provider state.

Import-Time Registration Checks

When the server initializes, src/shared/constants/providers.ts imports each provider implementation and invokes its isEnabled() function. Only providers returning true are added to the global provider catalog. This check occurs exactly once at import-time, meaning environment changes require a process restart to take effect.

Runtime Executor Configuration

Executors cache environment values for the duration of each request. When DefaultExecutor processes a request, it reads provider-specific variables from process.env to build authentication headers, with values cached in the executor instance for the request lifecycle.

Global System Flags

Beyond individual provider configuration, several variables control cross-cutting behavior affecting the request pipeline:

• REQUIRE_API_KEY – Enforced by src/middleware/auth.ts (lines 12-20), controls whether incoming requests must present valid API credentials
• DISABLE_GUARDRAILS – Toggles safety filtering in the request pipeline
• PII_REDACTION_ENABLED – Activates PII sanitization middleware
• DATA_DIR and STORAGE_ENCRYPTION_KEY – Read by src/lib/db/core.ts (lines 22-30) to set SQLite location and encryption, affecting where provider state (tokens, quotas) persists
• CLI_DEVIN_BIN – Overrides external binary paths for providers like the Devin Cloud-agent

Practical Configuration Examples

Configure providers via .env:

# Free-proxy toggles

FREE_PROXY_1PROXY_ENABLED=true
FREE_PROXY_1PROXY_API_URL=https://1proxy.example.com
FREE_PROXY_1PROXY_MAX=50

FREE_PROXY_PROXIFLY_ENABLED=false

# Commercial provider keys

OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx

# Global settings

REQUIRE_API_KEY=true
DATA_DIR=/var/omniroute/data
STORAGE_ENCRYPTION_KEY=super-secret-key

Start the server:

node --import tsx/esm ./src/server.ts

Using the executor in code:

import { DefaultExecutor } from '@/open-sse/executors/default';

const exe = new DefaultExecutor('openai', { model: 'gpt-4' });
await exe.execute(requestBody); // Internally uses process.env.OPENAI_API_KEY

Note that disabling a provider at runtime requires a restart:

// This only affects the next process start
process.env.FREE_PROXY_PROXIFLY_ENABLED = 'false';

Summary

• Import-time registration: OmniRoute evaluates provider isEnabled() functions from src/lib/freeProxyProviders/*.ts when loading src/shared/constants/providers.ts, requiring restart to change active providers.
• Flag-based enablement: Free-proxy providers use FREE_PROXY_*_ENABLED variables; commercial providers rely on API keys like OPENAI_API_KEY read by open-sse/executors/default.ts.
• Global middleware control: Variables such as REQUIRE_API_KEY (enforced in src/middleware/auth.ts) and DATA_DIR (used in src/lib/db/core.ts) affect authentication, storage encryption, and provider metadata persistence.
• Immutable runtime: Because environment checks occur at import, toggling providers or changing configuration requires restarting the Node process.

Frequently Asked Questions

Can I enable or disable providers without restarting OmniRoute?

No. According to the OmniRoute source code, provider registration occurs at import-time when src/shared/constants/providers.ts loads each module and checks its isEnabled() function. Changing environment variables after the process has started does not re-register providers; you must restart the Node process for changes to take effect.

What happens if an API key environment variable is missing?

The executor throws a configuration error and excludes the provider from the catalog. For example, open-sse/executors/default.ts reads process.env.OPENAI_API_KEY when building the authentication header, and missing keys prevent the provider from being usable in the routing pool.

How do I configure the storage location for provider metadata?

Set the DATA_DIR environment variable to specify the SQLite database location, and use STORAGE_ENCRYPTION_KEY to enable encryption at rest. These are read by src/lib/db/core.ts (lines 22-30) and affect where provider state—including tokens, quotas, and combo settings—is persisted.

Are free-proxy providers configured differently than commercial API providers?

Yes. Free-proxy providers in src/lib/freeProxyProviders/ use multiple environment variables for feature toggles (FREE_PROXY_1PROXY_ENABLED), endpoint configuration (FREE_PROXY_WEBSHARE_API_URL), and connection limits (FREE_PROXY_1PROXY_MAX). Commercial providers typically require only a single API key variable but follow the same import-time registration pattern.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}