How to Configure OmniRoute with 19 Different Routing Strategies

OmniRoute supports 19+ distinct routing algorithms through its combo engine, with 9 core strategies—including priority, round-robin, least-used, cost-optimized, and intelligent auto-routing—configurable via the /api/combos endpoint or per-provider fallback settings.

OmniRoute's routing layer, implemented in the diegosouzapw/OmniRoute repository, provides granular control over how LLM requests are dispatched across provider connections. While the platform supports extensive customization with over 19 different routing configurations, this guide focuses on the 9 primary strategies documented in the source code. These algorithms determine how the combo engine (located in open-sse/services/combo/) selects targets from eligible provider pools during the request pipeline: src/app/api/v1/chat/completions → open-sse/handlers/chatCore.ts → open-sse/services/combo/comboSetup.ts.

The 9 Core Routing Strategies

Each strategy is implemented as a distinct algorithm within the combo engine. When you configure a combo or set a fallback strategy, you select one of these identifiers which the system resolves through open-sse/services/combo/strategyDispatch.ts.

Priority (Sequential Failover)

The priority strategy sequentially tries targets in the order they appear and stops at the first successful response. This is the default behavior for named combos. The core logic resides in open-sse/services/combo/targetResolution.ts at line 71, where the engine checks strategy === "priority" before executing sequential resolution.

Fill-First (Guaranteed Primary)

The fill-first strategy behaves identically to priority but guarantees that the first target is always tried, even if later targets report healthier status. This serves as the default fallback strategy for certain provider configurations. The resolver logic appears in src/sse/services/auth.ts at line 1908, where it handles the <fill-first> default fallback directive.

Round-Robin (Load Distribution)

The round-robin strategy cycles through eligible connections in a rotating fashion to distribute load evenly. The implementation in open-sse/services/combo/autoStrategy.ts (line 400) maintains rotation state and advances the pointer with each request.

Random (Stochastic Selection)

The random strategy selects targets uniformly at random from the eligible pool on each request. The ordering logic lives in open-sse/services/combo/runtimeUnits.ts between lines 166-168 within the orderUnitsForStrategy function.

Least-Used (Quota Balancing)

The least-used strategy picks the connection with the fewest invocations in the recent time window, helping to balance provider quotas. The sorting algorithm is implemented in open-sse/services/combo/targetSorters.ts at line 120.

Cost-Optimized (Price-Based)

The cost-optimized strategy orders targets by effective price (cheapest first) before applying secondary filters. This sorter resides in open-sse/services/combo/targetSorters.ts at line 62, calculating per-token costs across candidate providers.

Reset-Aware (Recovery Preference)

The reset-aware strategy prefers connections that have recently recovered from a circuit-breaker open state (reset events). The detection logic appears in open-sse/services/combo/autoStrategy.ts at line 318, monitoring circuit-breaker health transitions.

LKGP (Least Known Good Provider)

The lkgp (Least Known Good Provider) strategy selects the provider with the highest historical health score, combining quota availability, latency percentiles, and error rates. The scoring implementation is found in open-sse/services/combo/autoStrategy.ts at line 280.

Auto (Intelligent 15-Factor Routing)

The auto strategy implements the full intelligent router, building a candidate pool and applying quota cutoffs, context-window filters, mode-packs, and 15 distinct scoring factors before final selection. The complete pipeline is defined in open-sse/services/combo/autoStrategy.ts between lines 19-31, with per-request control parsing at line 240.

Configuring Strategies Via REST API

To configure a combo with a specific strategy, POST to the combos endpoint:

POST /api/combos
Content-Type: application/json

{
  "name": "my-priority-combo",
  "strategy": "priority",
  "models": [
    "openai/gpt-4o",
    "anthropic/claude-3.5-sonnet"
  ],
  "description": "Sequential fallback for high-reliability workloads"
}

The strategy field accepts any of the nine string identifiers listed above. This value is persisted in src/lib/db/combo.ts and subsequently read by comboSetup.ts during request processing. The ACCOUNT_FALLBACK_STRATEGY_VALUES enum in src/shared/validation/settingsSchemas.ts defines the allowed values for validation.

Overriding Per-Provider Fallback Strategies

When no combo matches a request, OmniRoute uses per-provider fallback strategies configured via the settings endpoint:

PATCH /api/v1/settings
Content-Type: application/json

{
  "providerStrategies": {
    "codex": { "fallbackStrategy": "least-used" },
    "openai": { "fallbackStrategy": "round-robin" }
  }
}

The resolver in src/sse/services/auth.ts (line 1908) selects the strategy using the logic: providerOverride.fallbackStrategy || settings.fallbackStrategy. This allows fine-grained control over individual provider behavior without modifying combo definitions.

Per-Request Steering for Auto Strategies

Even when a combo uses the auto strategy, you can steer individual requests using HTTP headers parsed by open-sse/services/autoCombo/requestControls.ts:

• X-OmniRoute-Mode: Accepts values like fast, balanced, quality, cheap, reliable, offline, or a custom mode-pack name. This selects preset weight configurations for the 15-factor scoring engine.
• X-OmniRoute-Budget: Specifies a numeric USD cost ceiling. The engine prunes candidates with estimated costs exceeding this value.

These headers are processed in open-sse/services/combo/autoStrategy.ts at line 240 and affect only the current request without mutating the stored combo configuration.

Summary

• OmniRoute provides 9 core routing strategies—priority, fill-first, round-robin, random, least-used, cost-optimized, reset-aware, lkgp, and auto—implemented across open-sse/services/combo/ source files.
• Configuration persistence occurs via /api/combos (stored in src/lib/db/combo.ts) and per-provider overrides via /api/v1/settings (resolved in src/sse/services/auth.ts).
• Default behaviors can be overridden at the provider level using the providerStrategies configuration object.
• Runtime control of auto-strategy execution is available through X-OmniRoute-Mode and X-OmniRoute-Budget headers without API configuration changes.

Frequently Asked Questions

What is the difference between priority and fill-first strategies?

Both strategies attempt targets sequentially, but fill-first guarantees the primary target receives traffic even when secondary targets demonstrate superior health metrics. The priority strategy (default for named combos) will skip an unhealthy first target, while fill-first persists with the initial selection as defined in src/sse/services/auth.ts line 1908.

How do I change routing strategies for a single request without modifying the combo?

Send X-OmniRoute-Mode or X-OmniRoute-Budget headers with your request. These are parsed in open-sse/services/combo/autoStrategy.ts (line 240) and open-sse/services/autoCombo/requestControls.ts, allowing temporary overrides of the auto-strategy scoring weights without altering the persisted combo configuration in src/lib/db/combo.ts.

Where does OmniRoute validate allowed strategy names?

The allowed strategy strings are enumerated in src/shared/validation/settingsSchemas.ts within the ACCOUNT_FALLBACK_STRATEGY_VALUES constant. This schema validates inputs for both the /api/combos endpoint and the /api/v1/settings provider override configuration.

Which file contains the logic for cost-based routing selection?

The cost-optimized strategy implementation resides in open-sse/services/combo/targetSorters.ts at line 62. This sorter calculates effective pricing across candidate connections and orders them from cheapest to most expensive before the combo engine applies additional filters like context-window limits or quota checks.

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