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

> Master OmniRoute provider configuration with this guide. Learn how environment variables control LLM provider behavior and authentication without code changes. Enhance your setup today.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-07-12

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`:

```bash

# 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:

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

```

Using the executor in code:

```typescript
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:

```typescript
// 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/default.ts).
- **Global middleware control**: Variables such as `REQUIRE_API_KEY` (enforced in [`src/middleware/auth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/middleware/auth.ts)) and `DATA_DIR` (used in [`src/lib/db/core.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.