What Is Combo Switching in OmniRoute? A Complete Guide to Activating and Deactivating Model Chains

Combo switching in OmniRoute is the mechanism for toggling a model chain's participation in the routing engine by setting its isActive flag to true (active) or false (inactive) via the omniroute_switch_combo MCP tool or direct API calls.

In OmniRoute, a combo is a configurable chain of AI models bundled with a routing strategy—such as priority-based, weighted, or round-robin selection. Combo switching gives operators fine-grained control over which chains are eligible to handle incoming requests without deleting their configuration. According to the OmniRoute source code, this is implemented through a simple boolean flag that the resolver checks before selecting a target combo.

How Combo Switching Works Internally

The combo switching flow involves three coordinated layers: the MCP tool interface, the REST API, and the database persistence layer.

MCP Tool: omniroute_switch_combo

The primary interface for combo switching is the MCP tool registered in open-sse/mcp-server/server.ts. This tool requires the write:combos scope and accepts two parameters:

• comboId: The unique identifier of the target combo
• active: Boolean indicating the desired state

When invoked, the tool handler (handleSwitchCombo at lines 75–89) constructs a PUT request to /api/combos/:id with the JSON body { "isActive": <true|false> }.

API Route and Database Update

The route handler in src/app/api/combos/[id]/route.ts (lines 101–119) validates the incoming request and delegates persistence to updateCombo in src/lib/db/combos.ts. This function executes a SQL update against the SQLite combos table:

// From src/lib/db/combos.ts, lines 99-106
export async function updateCombo(id: string, updates: Partial<Combo>) {
  const { isActive, ...otherFields } = updates;
  // SQLite update with parameterized query
  return db.prepare(`
    UPDATE combos 
    SET isActive = ?, updatedAt = datetime('now')
    WHERE id = ?
  `).run(isActive, id);
}

After the database update, the combo cache is invalidated and a log entry is recorded via logToolCall to maintain an audit trail of activation changes.

Router Resolution

The critical enforcement point occurs in open-sse/services/combo.ts, where the combo resolver filters candidates based on isActive. An inactive combo is excluded from consideration entirely, regardless of its routing strategy configuration or model availability.

Methods for Switching Combos

You can activate or deactivate combos through three interfaces depending on your operational context.

Method 1: MCP Client (JavaScript/TypeScript)

Direct API calls using standard fetch:

// Activate a combo
await fetch("/api/combos/123e4567-e89b-12d3-a456-426614174000", {
  method: "PUT",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ isActive: true })
});

// Deactivate a combo
await fetch("/api/combos/123e4567-e89b-12d3-a456-426614174000", {
  method: "PUT",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ isActive: false })
});

Method 2: CLI MCP Tool

Using the bundled CLI for scripted operations:

# Switch combo with ID `my-combo-id` on

omniroute mcp call omniroute_switch_combo '{"comboId":"my-combo-id","active":true}'

# Switch combo off

omniroute mcp call omniroute_switch_combo '{"comboId":"my-combo-id","active":false}'

Method 3: Direct HTTP (curl)

For automation or external integrations:

curl -X PUT https://your.omniroute.instance/api/combos/my-combo-id \
  -H "Content-Type: application/json" \
  -d '{"isActive":false}'

Key Source Files for Combo Switching

Component	File Path	Purpose
Tool schema definition	open-sse/mcp-server/schemas/tools.ts (lines 167–190)	Declares omniroute_switch_combo with input validation schema and write:combos scope requirement
Tool registration	open-sse/mcp-server/server.ts (lines 27–35)	Registers the tool and routes invocations to handleSwitchCombo
Switch handler implementation	open-sse/mcp-server/server.ts (lines 75–89)	Executes the PUT request, handles responses, and logs tool calls
Database persistence	src/lib/db/combos.ts (lines 99–106)	Provides updateCombo function for SQL operations
REST API endpoint	src/app/api/combos/[id]/route.ts (lines 101–119)	Validates and processes combo update requests
Resolver eligibility check	open-sse/services/combo.ts	Filters combos by isActive flag during routing decisions

Common Use Cases for Combo Switching

• A/B testing: Activate experimental model chains alongside stable ones, using weighted routing to control traffic distribution
• Maintenance windows: Degrade gracefully by deactivating combos that depend on downstream services under maintenance
• Cost optimization: Switch off expensive model chains during low-traffic periods without losing configuration
• Incident response: Immediately isolate problematic combos when errors are detected, then reactivate after fixes

Summary

• Combo switching toggles a model chain's eligibility in OmniRoute's routing engine via the isActive boolean flag
• The omniroute_switch_combo MCP tool (scope: write:combos) is the standard interface, translating calls to PUT /api/combos/:id
• The updateCombo function in src/lib/db/combos.ts persists changes to SQLite, with cache invalidation and audit logging
• The combo resolver in open-sse/services/combo.ts enforces the active filter at request time
• Three interfaces are available: JavaScript fetch, CLI MCP tool, and direct HTTP

Frequently Asked Questions

What happens to in-flight requests when a combo is deactivated?

In-flight requests already routed to a combo complete normally; the isActive check only affects new resolution decisions. There is no forced termination of active connections.

Can I schedule automatic combo activation and deactivation?

OmniRoute does not include built-in scheduling, but you can implement cron jobs or external orchestrators that call omniroute_switch_combo via the CLI or HTTP API at specified intervals.

Is there a way to see which combos are currently active?

Query the /api/combos endpoint or use the corresponding MCP tool; the response includes the isActive field for each combo. The resolver also logs eligible combos at debug verbosity in open-sse/services/combo.ts.

Does deactivating a combo affect its configuration data?

No. Deactivation only changes the isActive flag. All model definitions, routing strategy parameters, and metadata remain intact in the database and can be restored instantly by reactivating the combo.

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