How to Create a Custom Combo Route in OmniRoute: A Complete Guide

Use OmniRoute's combo feature to define a named routing rule that dispatches requests to multiple provider-model pairs using strategies like priority, weighted, round-robin, or auto.

OmniRoute's combo route system lets you build resilient, multi-provider LLM routing without custom code. A combo is a persistent configuration that tells the router how to distribute traffic across different AI providers based on your chosen strategy. This guide walks you through creating, activating, and managing custom combos using the CLI, API, and dashboard.

What Is an OmniRoute Combo Route?

A combo route is a named collection of provider-model pairs with a dispatch strategy. When a request hits the /v1/chat/completions endpoint, the combo engine (open-sse/services/combo.ts) resolves the active combo, builds a candidate list, applies resilience filters, and executes the routing logic.

The combo engine handles the complexity for you: circuit-breakers, cooldown periods, quota tracking, and strategy-specific dispatch loops. You define what to route and how; OmniRoute handles when and where.

Step 1: Define Your Combo Configuration

Before creating a combo, decide on three elements:

1. Name – A unique identifier used in API calls and the UI (e.g., my-fast-combo)
2. Strategy – One of the VALID_STRATEGIES: priority, weighted, round-robin, auto, etc.
3. Models – Provider-model pairs in providerId/modelId format (e.g., openai/gpt-4o, anthropic/claude-3-opus)

The strategy determines how the combo engine selects targets:

• priority – Try models in order until one succeeds
• weighted – Distribute traffic by configured weights
• round-robin – Rotate through models evenly
• auto – Dynamically select based on latency, cost, and availability

Step 2: Create Your Custom Combo Route

Using the CLI (Recommended)

The fastest way to create a combo is through the OmniRoute CLI. The command is defined in bin/cli/commands/combo.mjs (lines 14–33 for argument parsing):

# Create a priority combo with two high-performance models

omniroute combo create my-fast-combo \
  --strategy priority \
  --models "openai/gpt-4o,anthropic/claude-3-opus"

The CLI parses your input with resolveComboModels and calls runComboCreateCommand to persist the definition via src/lib/db/combos.ts.

Using the HTTP API

Create combos programmatically by POSTing to the combos endpoint. The API route at src/app/api/v1/combos/route.ts handles validation and storage:

import { apiFetch } from "@/cli/api.mjs";

await apiFetch("/api/combos", {
  method: "POST",
  body: {
    name: "my-fast-combo",
    strategy: "priority",
    models: [
      { providerId: "openai", model: "gpt-4o" },
      { providerId: "anthropic", model: "claude-3-opus" }
    ]
  }
});

Response includes the persisted combo ID and confirmation of the strategy validation.

Wildcard Model Selection

For dynamic provider coverage, use wildcards that open-sse/services/combo/prefixWildcard.ts expands at runtime:

omniroute combo create my-openai-tier \
  --strategy auto \
  --models "openai/*"

The wildcard helper resolves openai/* to all available OpenAI models with current pricing and quota data.

Step 3: Activate Your Combo Route

Creating a combo does not automatically route traffic to it.Activate with the switch command or API:

CLI activation:

omniroute combo switch my-fast-combo

API activation:

await apiFetch("/api/combos/switch", {
  method: "POST",
  body: { name: "my-fast-combo" }
});

This updates the activeCombo value in the settings table. Subsequent requests to /v1/chat/completions are processed by the combo engine using your new configuration.

Step 4: Monitor and Debug Your Combo Route

The combo engine annotates every response with routing metadata. Check the X-OmniRoute-Combo-Trace header to see which provider handled the request and which candidates were filtered.

View all combos in the dashboard at /dashboard/combos. The ComboDetails.tsx component displays:

• Strategy configuration
• Model list with provider status
• Circuit-breaker and cooldown states
• Recent request traces

How the Combo Engine Processes Requests

Understanding the internal flow helps you debug and optimize your combo routes. The engine in open-sse/services/combo.ts executes these steps on each request:

Step	Function	Purpose
Resolve config	resolveComboConfig	Loads combo record, applies defaults, validates strategy
Build candidates	buildAutoCandidates	Gathers connections, fetches pricing, latency, quota data
Filter by resilience	recordProviderFailure, isProviderInCooldown, getCircuitBreaker	Skips unhealthy or exhausted providers
Execute strategy	tryPinnedModelDispatch, tryFusionDispatch, handleRoundRobinCombo	Dispatches according to strategy rules
Return response	handleComboChat	Sends provider response with trace header

The resilience layer is automatic—no configuration needed. If a provider fails, the engine records via recordProviderFailure, checks isProviderInCooldown, and routes to the next eligible candidate.

Key Source Files for Combo Routes

File	Purpose
bin/cli/commands/combo.mjs	CLI commands: list, create, switch, delete, suggest
open-sse/services/combo.ts	Core combo engine: resolution, candidates, dispatch, resilience
src/lib/db/combos.ts	Database layer: CRUD operations for combo definitions
src/app/api/v1/combos/route.ts	REST API: POST/GET/DELETE endpoints
open-sse/services/combo/prefixWildcard.ts	Wildcard expansion for provider-model patterns

Summary

• Combo routes in OmniRoute bundle provider-model pairs with routing strategies for resilient multi-provider LLM access
• Create combos via omniroute combo create (CLI) or POST to /api/combos (API), specifying name, strategy, and models
• Activate with omniroute combo switch to begin routing traffic through your configuration
• The combo engine automatically applies circuit-breakers, cooldowns, and quota filters without additional code
• Monitor routing decisions through the X-OmniRoute-Combo-Trace header and /dashboard/combos UI

Frequently Asked Questions

What strategies can I use for an OmniRoute combo route?

OmniRoute supports VALID_STRATEGIES including priority, weighted, round-robin, and auto. Priority tries models in order; weighted distributes by configured weights; round-robin rotates evenly; auto selects dynamically based on latency, cost, and availability signals.

How does OmniRoute handle provider failures in a combo route?

The combo engine automatically tracks failures via recordProviderFailure and checks isProviderInCooldown and getCircuitBreaker before each dispatch. Failed providers are skipped until their cooldown expires or circuit breaker resets, ensuring requests route to healthy alternatives.

Can I use wildcards when specifying models in a combo route?

Yes. The prefixWildcard.ts helper expands patterns like openai/* to all available models from that provider at runtime. This keeps your combo current as providers add new models without manual updates.

Where is combo configuration stored in OmniRoute?

Combo definitions persist in the combos table via src/lib/db/combos.ts. The active combo reference is stored in the settings table, updated when you run omniroute combo switch or POST to /api/combos/switch.

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