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

Configure OmniRoute by setting environment variables in a .env file for runtime settings, editing 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 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:

# .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 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 and src/sse/services/auth.ts, with key storage managed by src/lib/db/apiKeys.ts. When REQUIRE_API_KEY=true, the middleware in src/middleware/promptInjectionGuard.ts intercepts requests lacking valid credentials.

OAuth configuration for provider-specific flows resides in src/lib/oauth/constants/oauth.ts. For example, XAI integration requires:

// 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. This file contains the master registry of 288+ providers including OpenAI, Anthropic, and custom endpoints.

// 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, with runtime resolution handled by src/lib/db/comboResolver.ts.

Available routing strategies (defined in 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:

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 module expands these definitions into ResolvedComboTarget objects consumed by open-sse/services/combo.ts.

Compression and Guardrails Configuration

Prompt compression is controlled through src/lib/db/compression.ts and the engine registry in 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)
• 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. Tool access is controlled via scopes defined in src/shared/validation/schemas/cli.ts.

The A2A (Agent-to-Agent) server exposes capabilities at /.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 using CLOUDFLARE_TUNNEL_TOKEN
• Ngrok Tunnel: Configure via 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:

# 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, including PORT, HOST, and REQUIRE_API_KEY
• Provider definitions live in 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. 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 and enforced by the middleware chain in src/middleware/promptInjectionGuard.ts and the auth service in src/sse/services/auth.ts. Valid API keys are stored and validated against the apiKeys table via 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: 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.

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, 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.

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