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

> Learn to create a custom combo route in OmniRoute. Dispatch requests to multiple providers using priority, weighted, round-robin, or auto strategies with this complete guide.

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

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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):

```bash

# 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/combos/route.ts) handles validation and storage:

```ts
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo/prefixWildcard.ts) expands at runtime:

```bash
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:**

```bash
omniroute combo switch my-fast-combo

```

**API activation:**

```ts
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts) | Core combo engine: resolution, candidates, dispatch, resilience |
| [`src/lib/db/combos.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/combos.ts) | Database layer: CRUD operations for combo definitions |
| [`src/app/api/v1/combos/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/combos/route.ts) | REST API: POST/GET/DELETE endpoints |
| [`open-sse/services/combo/prefixWildcard.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`.