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

> Learn how to configure OmniRoute settings using environment variables, SQLite, and provider routing files. Master OmniRoute configuration for optimal performance.

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

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/validation/schemas/settings.ts).

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

```bash

# .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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/middleware/promptInjectionGuard.ts) guards the request pipeline, while the core service in [`src/sse/services/auth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/services/auth.ts) validates credentials against the `apiKeys` database module ([`src/lib/db/apiKeys.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/apiKeys.ts)).

### OAuth Provider Configuration

Provider-specific OAuth flows are centralized in [`src/lib/oauth/constants/oauth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/oauth/constants/oauth.ts):

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

```

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:

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers.ts). This single source of truth enumerates all 290+ supported backends.

```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" },
  // ... 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/combo.ts); runtime resolution happens in [`src/lib/db/comboResolver.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/comboResolver.ts).

### Creating a Combo via SQL

```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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/compression/registry.ts).

### Guardrail Toggles

| Environment Variable | Effect | Source File |
|----------------------|--------|-------------|
| `PII_REDACTION_ENABLED=true` | Activates [`src/lib/guardrails/pii-masker.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/validation/schemas/cli.ts).

```bash
npm start -- --mcp

```

### A2A (Agent-to-Agent)

The A2A endpoint ([`/.well-known/agent.json`](https://github.com/diegosouzapw/OmniRoute/blob/main//.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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cloudflaredTunnel.ts) |
| Ngrok | `NGROK_AUTH_TOKEN` | [`src/lib/ngrokTunnel.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```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. 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server-init.ts))
- **SQLite tables** store combos, API keys, rate limits, and compression settings
- **Provider registry** at [`src/shared/constants/providers.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/comboResolver.ts) processes these into executable targets.