# How to Configure OmniRoute: Environment Variables, Provider Catalogs, and Routing Strategies

> Learn how to configure OmniRoute by setting environment variables, managing provider catalogs, and defining routing strategies for efficient AI model selection and management.

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

---

**Configure OmniRoute by setting environment variables in a `.env` file for runtime settings, editing [`src/shared/constants/providers.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers.ts) to manage AI providers, and using SQLite-backed combo definitions to control routing strategies.**

OmniRoute is a modular AI proxy and router from the `diegosouzapw/OmniRoute` repository that centralizes configuration across environment variables, JSON/YAML files, and SQLite databases. Understanding how to configure OmniRoute properly ensures secure authentication, optimized request routing, and seamless integration with multiple LLM providers. This guide walks through every configuration layer—from basic server initialization to advanced combo routing—using the actual source implementation.

## Runtime and Process-Level Configuration

The entry point [`src/server-init.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server-init.ts) defines the core runtime behavior through environment variables that control networking, storage, and security policies.

**Key environment variables**

- `PORT`: HTTP server port (default: `3000`)
- `HOST`: Bind address (default: `127.0.0.1`, use `0.0.0.0` for external access)
- `DATA_DIR`: Root directory for SQLite databases and persistent state (default: `~/.omniroute`)
- `LOG_LEVEL`: Pino logger verbosity (`trace`, `debug`, `info`, `warn`, `error`)
- `REQUIRE_API_KEY`: Boolean flag enforcing API key authentication on all requests

Create a `.env` file in the repository root to override these defaults:

```bash

# .env

PORT=8080
HOST=0.0.0.0
DATA_DIR=/var/omniroute/data
LOG_LEVEL=debug
REQUIRE_API_KEY=true

```

The initialization logic in [`src/server-init.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server-init.ts) parses these variables at startup, with `XDG_CONFIG_HOME` taking precedence over `DATA_DIR` when set.

## Authentication and API Key Management

OmniRoute supports dual authentication modes: static API keys and OAuth flows for specific providers.

**API key validation** is implemented in [`src/lib/api/errorResponse.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/api/errorResponse.ts) and [`src/sse/services/auth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/services/auth.ts), with key storage managed by [`src/lib/db/apiKeys.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/apiKeys.ts). When `REQUIRE_API_KEY=true`, the middleware in [`src/middleware/promptInjectionGuard.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/middleware/promptInjectionGuard.ts) intercepts requests lacking valid credentials.

**OAuth configuration** for provider-specific flows resides in [`src/lib/oauth/constants/oauth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/oauth/constants/oauth.ts). For example, XAI integration requires:

```typescript
// src/lib/oauth/constants/oauth.ts
export const XAI_OAUTH_CONFIG = {
  clientId: "YOUR_XAI_CLIENT_ID",
  clientSecret: "YOUR_XAI_CLIENT_SECRET",
  tokenUrl: "https://x.ai/oauth/token",
  scope: "read write",
};

```

## Provider Catalog Configuration

All supported AI providers are centralized in [`src/shared/constants/providers.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers.ts). This file contains the master registry of 288+ providers including OpenAI, Anthropic, and custom endpoints.

```typescript
// src/shared/constants/providers.ts
export const PROVIDERS = [
  { id: "openai", name: "OpenAI", auth: "apiKey", baseUrl: "https://api.openai.com/v1" },
  { id: "anthropic", name: "Anthropic", auth: "apiKey", baseUrl: "https://api.anthropic.com/v1" },
  // ... additional providers
];

```

To add a custom provider:

1. Append a new object to the `PROVIDERS` array with `id`, `name`, `auth`, and `baseUrl` fields
2. Create a custom executor in `open-sse/executors/` if the provider deviates from OpenAI-compatible APIs
3. Run `npm run check:fabricated-docs` to validate the new entry against Zod schemas in `src/shared/validation/`

## Combo Routing Engine Setup

Combos define ordered sets of provider targets and routing strategies. The schema lives in [`src/lib/db/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/combo.ts), with runtime resolution handled by [`src/lib/db/comboResolver.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/comboResolver.ts).

**Available routing strategies** (defined in [`src/shared/validation/schemas/routing.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/validation/schemas/routing.ts)):

- **priority**: First reachable target wins
- **weighted**: Random selection based on weight fields
- **round-robin**: Cyclical distribution across targets
- **least-used**: Selects provider with lowest recent usage

Create combos via SQL or the CLI:

```sql
INSERT INTO combos (name, strategy, targets) VALUES (
  'fast-cheap',
  'weighted',
  '[{"provider":"openai","model":"gpt-4o-mini","weight":1},
    {"provider":"anthropic","model":"claude-3-haiku-20240307","weight":2}]'
);

```

The [`comboResolver.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/comboResolver.ts) module expands these definitions into `ResolvedComboTarget` objects consumed by [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts).

## Compression and Guardrails Configuration

**Prompt compression** is controlled through [`src/lib/db/compression.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/compression.ts) and the engine registry in [`open-sse/services/compression/registry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/compression/registry.ts). Set the default mode via the `compressionMode` field in combo definitions, with `lite` as the standard preset.

**Guardrails** reside under `src/lib/guardrails/` and are opt-in by default:

- **PII masking**: Enable via `PII_REDACTION_ENABLED=true` (implements [`src/lib/guardrails/pii-masker.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/guardrails/pii-masker.ts))
- **Prompt injection detection**: Sanitizes suspicious patterns through middleware

Disable specific guardrails per-request using the header `x-omniroute-disabled-guardrails`.

## MCP and A2A Server Configuration

The **MCP (Multi-Channel Provider)** server starts with the `--mcp` CLI flag and registers 104 tools as defined in [`open-sse/mcp-server/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts). Tool access is controlled via scopes defined in [`src/shared/validation/schemas/cli.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/validation/schemas/cli.ts).

The **A2A (Agent-to-Agent)** server exposes capabilities at [`/.well-known/agent.json`](https://github.com/diegosouzapw/OmniRoute/blob/main//.well-known/agent.json) through the modules in `src/lib/a2a/`, including skill registries and health endpoints.

## Tunnel and Network Configuration

OmniRoute supports external tunnel exposure through environment-specific modules:

- **Cloudflare Tunnel**: Configure via [`src/lib/cloudflaredTunnel.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cloudflaredTunnel.ts) using `CLOUDFLARE_TUNNEL_TOKEN`
- **Ngrok Tunnel**: Configure via [`src/lib/ngrokTunnel.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/ngrokTunnel.ts) using `NGROK_AUTH_TOKEN`

Both modules automatically establish secure tunnels when their respective tokens are present in the environment.

## Production Deployment Example

Deploy a production instance with the following sequence:

```bash

# 1. Configure environment

cat > .env <<EOF
PORT=8080
HOST=0.0.0.0
DATA_DIR=/opt/omniroute/data
LOG_LEVEL=info
REQUIRE_API_KEY=true
PII_REDACTION_ENABLED=true
EOF

# 2. Initialize database

npm run db:migrate

# 3. Create routing combo

npm run combo:add -- \
  --name fast-cheap \
  --strategy weighted \
  --targets '[{"provider":"openai","model":"gpt-4o-mini","weight":1},{"provider":"anthropic","model":"claude-3-haiku-20240307","weight":2}]'

# 4. Build and start

npm run build
npm start

```

All configuration is validated at startup using Zod schemas under `src/shared/validation/`, preventing silent failures from typos or type mismatches.

## Summary

- **Runtime settings** are controlled via environment variables read by [`src/server-init.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server-init.ts), including `PORT`, `HOST`, and `REQUIRE_API_KEY`
- **Provider definitions** live in [`src/shared/constants/providers.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers.ts) and support custom endpoints through the executor pattern
- **Routing logic** is configured through SQLite combo entries using strategies like `weighted`, `priority`, or `round-robin`
- **Security features** include opt-in PII redaction and prompt injection guards, plus mandatory API key validation when enabled
- **External tunnels** activate automatically when `CLOUDFLARE_TUNNEL_TOKEN` or `NGROK_AUTH_TOKEN` environment variables are present

## Frequently Asked Questions

### What file controls the list of available AI providers in OmniRoute?

The master provider registry is located in [`src/shared/constants/providers.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers.ts). This TypeScript file exports a `PROVIDERS` array containing objects with `id`, `name`, `auth`, and `baseUrl` fields for each supported service. To add a new provider, append an entry to this array and create a custom executor in `open-sse/executors/` if the API differs from OpenAI's specification.

### How do I enforce API key authentication for all requests?

Set the environment variable `REQUIRE_API_KEY=true` in your `.env` file or shell environment. This variable is read by [`src/server-init.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server-init.ts) and enforced by the middleware chain in [`src/middleware/promptInjectionGuard.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/middleware/promptInjectionGuard.ts) and the auth service in [`src/sse/services/auth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/services/auth.ts). Valid API keys are stored and validated against the `apiKeys` table via [`src/lib/db/apiKeys.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/apiKeys.ts).

### What routing strategies are available for combo configurations?

OmniRoute supports four routing strategies defined in [`src/shared/validation/schemas/routing.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/validation/schemas/routing.ts): **priority** (first available target), **weighted** (random selection based on weight values), **round-robin** (cyclic distribution), and **least-used** (lowest recent usage). These are specified in the `strategy` field of combo entries managed by [`src/lib/db/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/combo.ts).

### How do I enable PII redaction and prompt injection protection?

Enable guardrails by setting `PII_REDACTION_ENABLED=true` in your environment variables. The PII masker implementation resides in [`src/lib/guardrails/pii-masker.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/guardrails/pii-masker.ts), while prompt injection detection runs through middleware. Both features are opt-in by default for security compliance. You can disable them per-request using the `x-omniroute-disabled-guardrails` header if specific workflows require unfiltered processing.