# How to Configure Custom Routing Strategies in OmniRoute Beyond Built-in Options

> Learn to configure custom routing strategies in OmniRoute by implementing the RouterStrategy interface and registering your custom logic. Enhance your routing beyond built-in options.

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

---

**To configure custom routing strategies in OmniRoute, implement the `RouterStrategy` interface with a `select()` method, register it via `registerStrategy()`, and reference it in combo configurations.**

OmniRoute ships with 19 built-in routing strategies—ranging from `priority` and `weighted` to `auto` and `lkgp`—but its pluggable architecture lets you inject arbitrary decision logic. This guide explains how to extend the platform with your own routing policies, backed by the actual source code in `diegosouzapw/OmniRoute`.

## Overview of Router Strategies in OmniRoute

According to the OmniRoute source code, routing strategies are classes that implement a single `select(pool, context)` method. The `pool` contains available providers as `VirtualAutoComboCandidate` objects, while `context` carries task metadata like LKG‑P flags and latency history.

The built-in strategy identifiers live in [`src/shared/constants/routingStrategies.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/routingStrategies.ts). When you need behavior not covered by these 19 options—say, a custom cost‑latency threshold or domain‑specific heuristics—you create a custom implementation.

## Implementing a Custom Router Strategy

To build a valid custom strategy, you need three pieces from [`open-sse/services/autoCombo/routerStrategy.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/routerStrategy.ts):

- **The `RouterStrategy` interface** – requires `name`, `description`, and `select(pool, context)`
- **The `registerStrategy(name, instance)` function** – adds your strategy to the global runtime registry
- **The `select()` return format** – must return an object with `provider`, `model`, `strategy`, and optional `reason`

### Step-by-Step Implementation

```typescript
// myCustomStrategy.ts
import {
  registerStrategy,
  type RouterStrategy,
} from "@omniroute/open-sse/services/autoCombo/routerStrategy";

class MyCustomStrategy implements RouterStrategy {
  readonly name = "my-custom";
  readonly description = "Prefer providers with latency < 200ms and cost < $0.02";

  select(pool, context) {
    // Filter out unhealthy providers first
    const healthy = pool.filter(c => c.circuitBreakerState !== "OPEN");
    
    // Apply custom business logic
    const candidates = healthy.filter(
      c => c.p95LatencyMs < 200 && c.costPer1MTokens < 0.02
    );
    
    // Fallback if no candidates match strict criteria
    const chosen = candidates.length ? candidates[0] : healthy[0];

    return {
      provider: chosen.provider,
      model: chosen.model,
      strategy: this.name,
      reason: "MyCustomStrategy applied custom latency/cost filter",
    };
  }
}

// Register during module initialization (e.g., in a plugin file)
registerStrategy("my-custom", new MyCustomStrategy());

```

Key implementation details to note:

- **Circuit breaker awareness** – always check `circuitBreakerState !== "OPEN"`; the pool may contain unhealthy candidates
- **Graceful degradation** – your `select()` should handle empty filtered sets
- **Registration timing** – call `registerStrategy()` before any combos using it are instantiated

## Registering and Activating Your Strategy

The global strategy registry in [`open-sse/services/autoCombo/routerStrategy.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/routerStrategy.ts) is a simple mutable map that accepts registrations at runtime. This design lets you extend OmniRoute without modifying core source files.

### Method 1: Persisted Combo with Custom Strategy

Create a combo via API or UI that references your registered name:

```json
{
  "id": "my-combo",
  "name": "Fast-Cheap Combo",
  "strategy": "auto",
  "config": {
    "routerStrategy": "my-custom",
    "targets": [
      { "model": "anthropic/claude-3.5-sonnet" },
      { "model": "openai/gpt-4o-mini" }
    ]
  }
}

```

The `strategy: "auto"` tells OmniRoute to use the auto-combo engine, while `config.routerStrategy` overrides the default routing logic with your custom implementation.

### Method 2: Zero-Config Auto-Combo

For ad-hoc requests without persisted combos, force your strategy via the `X-OmniRoute-Mode` header:

```bash
curl -X POST http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -H "X-OmniRoute-Mode: my-custom" \
  -d '{"model":"auto/fast","messages":[{"role":"user","content":"Explain quantum tunneling"}]}'

```

This flow uses [`open-sse/services/autoCombo/virtualFactory.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/virtualFactory.ts) to build an in-memory combo configuration that respects your `routerStrategy` setting.

## Key Source Files for Custom Routing

| File | Purpose |
|------|---------|
| [`src/shared/constants/routingStrategies.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/routingStrategies.ts) | Canonical list of 19 built-in strategy identifiers |
| [`open-sse/services/autoCombo/routerStrategy.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/routerStrategy.ts) | `RouterStrategy` interface, registry, and `registerStrategy()` export |
| [`open-sse/services/autoCombo/virtualFactory.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/virtualFactory.ts) | Constructs ephemeral auto-combo configs; honors `config.routerStrategy` |
| [`src/sse/handlers/chat.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/handlers/chat.ts) | Entry point that detects `auto/` prefixes and dispatches to the auto-combo engine |
| [`docs/routing/AUTO-COMBO.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/routing/AUTO-COMBO.md) | User-facing documentation on custom router strategy workflows |

## Advanced Customization Patterns

**External decision services** – Your `select()` can call out to ML models, cost-forecasting APIs, or load balancers before returning a provider. The `context` parameter receives full request metadata to support this.

**Multi-factor scoring** – Combine latency, cost, token‑throughput, and provider‑specific SLAs using weighted formulas in `select()`.

**A/B testing strategies** – Register multiple experimental strategies and assign traffic percentages via `context` inspection or upstream headers.

## Summary

- **Custom routing strategies in OmniRoute** require implementing the `RouterStrategy` interface from [`open-sse/services/autoCombo/routerStrategy.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/routerStrategy.ts)
- **Registration** happens via `registerStrategy(name, instance)` before combo instantiation
- **Activation** works in persisted combos (`config.routerStrategy`) or zero-config calls (`X-OmniRoute-Mode` header)
- **Source authority**: The 19 built-ins are declared in [`src/shared/constants/routingStrategies.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/routingStrategies.ts); the extension API lives in [`open-sse/services/autoCombo/routerStrategy.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/routerStrategy.ts)

## Frequently Asked Questions

### What interface must a custom routing strategy implement?

A custom strategy must implement `RouterStrategy` from [`open-sse/services/autoCombo/routerStrategy.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/routerStrategy.ts), providing `name`, `description`, and a `select(pool, context)` method that returns a provider selection with `provider`, `model`, `strategy`, and optional `reason` fields.

### When should I use a persisted combo versus the zero-config auto-combo?

Use **persisted combos** when you need reusable, named configurations with fixed targets and consistent routing logic. Use **zero-config auto-combo** with `X-OmniRoute-Mode` for ad-hoc requests, prototyping, or dynamic strategy selection without creating persistent resources.

### Can I modify a custom strategy after registration?

Registration is additive only—you cannot unregister or replace strategies by name at runtime. To update logic, restart the OmniRoute process with a new strategy implementation registered under a different name, or version your strategy identifiers (e.g., `my-custom-v2`).

### Does OmniRoute validate custom strategy names against the built-in list?

No. The `ROUTING_STRATEGY_VALUES` constant in [`src/shared/constants/routingStrategies.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/routingStrategies.ts) documents public identifiers, but the runtime registry accepts any string name. Invalid or unregistered names will cause routing failures at request time, not at startup.