How to Configure OmniRoute Settings: A Complete Guide to Environment Variables, SQLite, and Provider Routing

OmniRoute settings are configured through three primary mechanisms: environment variables for runtime behavior, SQLite-backed tables for routing logic, and JSON/YAML files for provider definitions.

OmniRoute is a modular AI proxy/router from diegosouzapw/OmniRoute that surfaces configuration across every layer of its stack—from low-level networking to high-level provider catalogs. This guide walks through the eight configuration areas defined in the source code, with specific file paths and runnable examples you can apply immediately.

---

Runtime and Process-Level Settings

The entry point src/server-init.ts reads environment variables that control the core HTTP server, logging, and data persistence. These are evaluated at startup and validated against Zod schemas in src/shared/validation/schemas/settings.ts.

// src/server-init.ts
const PORT = process.env.PORT ? Number(process.env.PORT) : 3000;
const HOST = process.env.HOST ?? "127.0.0.1";
const DATA_DIR = process.env.DATA_DIR ?? path.join(os.homedir(), ".omniroute");
const LOG_LEVEL = process.env.LOG_LEVEL ?? "info";
const REQUIRE_API_KEY = process.env.REQUIRE_API_KEY === "true";

Essential Environment Variables

Variable	Default	Purpose
PORT	3000	HTTP server port
HOST	127.0.0.1	Bind address (use 0.0.0.0 for external access)
DATA_DIR	~/.omniroute	Root directory for SQLite databases and persistent state
LOG_LEVEL	info	Pino logger level: trace, debug, info, warn, error
REQUIRE_API_KEY	false	When true, mandates API key on every request
XDG_CONFIG_HOME	—	Overrides DATA_DIR with $XDG_CONFIG_HOME/omniroute if set

Create a .env file at the repository root:

# .env

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

All variables are type-checked at startup; mismatches trigger explicit Zod validation errors rather than silent failures.

---

Authentication and API-Key Policy

Authentication enforcement spans two layers. Middleware in src/middleware/promptInjectionGuard.ts guards the request pipeline, while the core service in src/sse/services/auth.ts validates credentials against the apiKeys database module (src/lib/db/apiKeys.ts).

OAuth Provider Configuration

Provider-specific OAuth flows are centralized in src/lib/oauth/constants/oauth.ts:

// 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",
};

Replace placeholder values with your actual credentials. The scope string determines token permissions.

Per-Request Guardrail Overrides

Disable specific guardrails for a single request via header:

curl -H "x-omniroute-disabled-guardrails: pii,prompt-injection" \
     -H "Authorization: Bearer $API_KEY" \
     http://localhost:8080/v1/chat/completions

---

Provider Catalog Configuration

The master provider registry lives in src/shared/constants/providers.ts. This single source of truth enumerates all 290+ supported backends.

// 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" },
  // ... 288 additional entries
];

Adding a Custom Provider

1. Append to PROVIDERS with id, name, auth type (apiKey or oauth), and baseUrl
2. Create a custom executor in open-sse/executors/ if the provider deviates from OpenAI-compatible formats
3. Validate with npm run check:fabricated-docs to sync documentation and Zod schemas

---

Combo Routing Engine Settings

Combos define ordered target sets and selection strategies for multi-provider routing. The database schema is defined in src/lib/db/combo.ts; runtime resolution happens in src/lib/db/comboResolver.ts.

Creating a Combo via 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}]'
);

Routing Strategies

Strategy	Behavior	Use Case
priority	First reachable target wins	Failover to premium models
weighted	Random selection by weight	Cost-aware load balancing
round-robin	Cyclical distribution	Uniform capacity utilization
least-used	Lowest recent usage first	Burst handling

Strategy values are enumerated in src/shared/validation/schemas/routing.ts as ROUTING_STRATEGY_VALUES. The combo resolver expands definitions into ResolvedComboTarget objects consumed by open-sse/services/combo.ts.

---

Prompt Compression and Guardrails

Compression and guardrails are opt-in by default (security rule #20 compliance).

Compression Modes

The pipeline in src/lib/db/compression.ts supports multiple modes. Override per-combo via the compressionMode field:

Mode	Description
none	No compression
lite	Default; token-efficient truncation
aggressive	Heavy semantic compression

Registry and engine selection live in open-sse/services/compression/registry.ts.

Guardrail Toggles

Environment Variable	Effect	Source File
PII_REDACTION_ENABLED=true	Activates src/lib/guardrails/pii-masker.ts	Redacts PII patterns
PROMPT_INJECTION_ENABLED=true	Activates src/lib/guardrails/prompt-injection/	Blocks suspicious patterns

---

MCP and A2A Server Configuration

MCP (Multi-Channel Provider)

Start with the --mcp CLI flag. The server in open-sse/mcp-server/server.ts registers 104 tools with scope-based access control. Default scopes are defined in src/shared/validation/schemas/cli.ts.

npm start -- --mcp

A2A (Agent-to-Agent)

The A2A endpoint (/.well-known/agent.json) exposes JSON-RPC capabilities from src/lib/a2a/. Skills, health status, and quota information are registered in the same directory.

---

Tunnel Configuration

OmniRoute can expose its endpoint through external tunnels without modifying firewall rules.

Tunnel	Environment Variable	Source File
Cloudflare	CLOUDFLARE_TUNNEL_TOKEN	src/lib/cloudflaredTunnel.ts
Ngrok	NGROK_AUTH_TOKEN	src/lib/ngrokTunnel.ts

Set the token and the tunnel initializes automatically on startup.

---

Production Deployment Example

Complete setup from fresh clone to running server:

# 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. Add routing combo via CLI

npm run combo:add -- \
  --name production \
  --strategy priority \
  --targets '[{"provider":"anthropic","model":"claude-3-opus-20240229"},{"provider":"openai","model":"gpt-4o"}]'

# 4. Build and start

npm run build
npm start

The server now listens on 0.0.0.0:8080, enforces API keys, redacts PII, and routes through the production combo with Anthropic priority.

---

Summary

• Environment variables in .env control host, port, logging, and feature flags (src/server-init.ts)
• SQLite tables store combos, API keys, rate limits, and compression settings
• Provider registry at src/shared/constants/providers.ts defines all 290+ backends
• Routing strategies (priority, weighted, round-robin, least-used) govern target selection
• Guardrails are opt-in via PII_REDACTION_ENABLED and request headers
• Tunnels activate with single environment tokens for Cloudflare or Ngrok
• Validation runs at startup via Zod schemas—failures are explicit and early

---

Frequently Asked Questions

How do I add a custom AI provider to OmniRoute?

Append a new entry to PROVIDERS in src/shared/constants/providers.ts with id, name, auth type, and baseUrl. If the response format differs from OpenAI's, implement a custom executor in open-sse/executors/. Run npm run check:fabricated-docs to synchronize schemas and documentation.

Where are OmniRoute settings stored?

Runtime settings come from environment variables or .env file. Persistent configuration lives in SQLite databases under DATA_DIR (default ~/.omniroute): combos, API keys, rate limits, and compression modes. Provider definitions are hardcoded in src/shared/constants/providers.ts.

How do I enable PII redaction?

Set PII_REDACTION_ENABLED=true in your environment, or pass x-omniroute-disabled-guardrails: (empty value) to keep all guardrails active. The feature is disabled by default per security rule #20. The implementation resides in src/lib/guardrails/pii-masker.ts.

What routing strategies does OmniRoute support?

Four strategies are implemented: priority (failover order), weighted (random by weight), round-robin (cyclic), and least-used (usage-based). Define in the strategy column of the combos table. The resolver in src/lib/db/comboResolver.ts processes these into executable targets.

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