How to Configure Custom Routing Strategies for Specific Provider Combinations in OmniRoute

To configure custom routing strategies for specific provider combinations in OmniRoute, add a providerOverrides entry that sets the routingStrategy field via the Settings API, which merges with global defaults and instantly applies to targeted combos.

OmniRoute's routing layer determines which provider-model combination satisfies a request based on configurable routing strategies. You can configure custom routing strategies for specific provider combinations by leveraging provider-specific overrides that take precedence over global defaults. This article explains the architecture and provides exact code examples from the diegosouzapw/OmniRoute source code.

Understanding OmniRoute's Routing Architecture

Before applying custom configurations, understand how OmniRoute resolves routing decisions. The system uses a routing strategy (such as priority, round-robin, or cost-optimized) to select the appropriate provider-model combo for each request.

Strategy Definitions

All user-selectable strategies are enumerated in src/shared/constants/routingStrategies.ts. This file defines the available identifiers that you can assign to the routingStrategy field.

Configuration Resolution

The default combo settings live in open-sse/services/comboConfig.ts. This file defines the shape of combo configurations and implements the merge logic that pulls provider-specific overrides:

const providerOverride = provider
  ? settings?.providerOverrides?.[provider] || {}
  : {};

The resolveComboConfig function merges global defaults with any providerOverrides, allowing targeted strategies to override the system default.

Configuring Provider-Specific Overrides

You configure custom strategies through the Settings API endpoint at src/app/api/settings/combo-defaults/route.ts. The database layer (src/lib/db/combo.ts) persists these configurations in SQLite.

Retrieving Current Defaults

To inspect the current configuration before making changes, send a GET request:

curl -X GET \
  -H "Authorization: Bearer $API_KEY" \
  https://your-omniroute-host/api/settings/combo-defaults

Applying Custom Strategy via PATCH

To set a custom strategy for a specific provider, send a PATCH request with the providerOverrides object. For example, to use cost-optimized only for OpenAI:

curl -X PATCH \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "providerOverrides": {
          "openai": {
            "routingStrategy": "cost-optimized"
          }
        }
      }' \
  https://your-omniroute-host/api/settings/combo-defaults

This payload tells OmniRoute to apply the cost-optimized strategy only when the provider is openai, while all other providers retain the globally-configured default.

TypeScript Implementation

For programmatic updates, use the following TypeScript implementation:

import { fetch } from 'undici';

const API_KEY = process.env.OMNIRoute_API_KEY!;

async function setStrategy() {
  const res = await fetch('https://your-omniroute-host/api/settings/combo-defaults', {
    method: 'PATCH',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      providerOverrides: {
        anthropic: { routingStrategy: 'least-used' },
      },
    }),
  });

  if (!res.ok) throw new Error(`Failed: ${res.status}`);
  console.log('Strategy updated');
}

setStrategy();

How Routing Execution Works

When a request is routed, the combo service loads the effective configuration through resolveComboConfig in open-sse/services/comboConfig.ts. It passes the resolved routingStrategy value to the combo dispatcher in open-sse/services/combo.ts.

The dispatcher selects the appropriate algorithm (such as the weighted selector) based on the strategy value. You can verify the applied strategy by inspecting the logs, where log.info("COMBO", ...) outputs the routing decision in open-sse/services/combo.ts.

Summary

• Configure custom routing strategies by updating providerOverrides in the Settings API at src/app/api/settings/combo-defaults/route.ts.
• Available strategies are defined in src/shared/constants/routingStrategies.ts.
• The merge logic in open-sse/services/comboConfig.ts combines global defaults with provider-specific overrides.
• Changes persist to SQLite via src/lib/db/combo.ts and take effect immediately for matching provider combos.
• Verify execution by checking the combo dispatcher logs in open-sse/services/combo.ts.

Frequently Asked Questions

What routing strategies are available in OmniRoute?

Available strategies include priority, round-robin, cost-optimized, and least-used, as enumerated in src/shared/constants/routingStrategies.ts. You can reference these identifiers when setting the routingStrategy field in your provider overrides.

Do provider overrides affect all models from that provider?

Yes, the override applies to the provider level as configured in the providerOverrides object. When you set a strategy for a provider like openai or anthropic, it affects all requests routed to that provider combination unless you implement additional model-specific filtering in your client logic.

How do I verify that my custom strategy is active?

After applying a PATCH update, monitor the application logs for the COMBO log entries in open-sse/services/combo.ts. These logs output the routing decision and will reflect the strategy name (such as least-used or cost-optimized) being applied to requests matching your overridden provider.

Can I set different strategies for different API keys or users?

The current implementation stores combo defaults globally in the database via src/lib/db/combo.ts. To implement per-user or per-key strategies, you would need to extend the settings schema to include user-specific overrides and modify the resolveComboConfig logic to accept a user context parameter.

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