OmniRoute Auto Combo Budget Setup for Agents

A current OmniRoute Auto Combo configuration can apply three request-level controls: a mode override, a per-request budget cap, and a fallback policy. The important decision is not whether to use the cheapest route. It is whether the request must stop when every eligible model exceeds the cap. For production Agents, create a model allowlist first, then set the budget and use strict when overspending is unacceptable. Start with one non-production client and test blocking, routing explanations, provider failure, and an empty candidate pool before sharing the rule with a team. (Auto-Combo documentation)

This guide is for:

• Developers using OmniRoute as the shared model gateway for Claude Code, Cursor, or a self-hosted AI Agent.
• Platform engineers who need different budget routing rules for different clients or API keys.
• Remote teams preparing to move a local gateway into a continuously available environment.

Start by separating the three budget layers

“Budget” is not one control in OmniRoute. A reliable setup separates at least three layers:

• Per-request budget: the maximum estimated USD cost for one request entering Auto Combo.
• API key token limit: a token allowance applied to a model, provider, or the whole key over a reset window.
• Team or key spending budget: a daily, weekly, or monthly USD limit tracked against an API key.

The first layer decides whether a candidate may participate in one routing event. The second and third layers control accumulated usage. A request can pass the per-request cap and still fail because the key has reached a token limit. The opposite can also happen: the key may have plenty of remaining monthly budget, while the current request is too expensive for its local cap.

The current API reference describes token limits as separate from USD budgets. Token limits can be scoped globally, by provider, or by model, and the most restrictive matching limit wins. The same reference documents daily, weekly, and monthly USD budget fields for API keys. (OmniRoute API Reference)

Before creating a combo, write down these decisions:

• What is the maximum estimated cost for one request?
• Should an over-budget request be blocked, degraded, or merely logged?
• Which models are allowed for coding, tool use, long context, and routine text?
• Which model can replace each candidate if its provider is unavailable?
• Which API key belongs to which Agent, team, or environment?

A monthly spending limit is not a substitute for a request cap. A long-running Agent can remain below its monthly limit while one oversized tool loop still creates an unacceptable single-request charge.

Use a candidate allowlist instead of trusting cheapest routing

OmniRoute can build a virtual Auto Combo from connected providers and score candidates dynamically. The documented engine evaluates multiple routing factors, including cost, health, quota, latency, task fit, and stability. The auto/cheap profile favors cost, but cost preference does not automatically create a hard spending boundary. (Auto-Combo engine reference)

Build the smallest useful candidate set first. Do not place every connected model into the pool just because the gateway can reach it.

For each candidate, record:

• Model identifier and provider identifier.
• Intended workload, such as code generation, tool calling, summarization, or long-running planning.
• Known context or tool-use limitations.
• Authentication status and the date of the last successful basic request.
• Replacement candidate if the provider fails.
• Whether the model is permitted for production, staging, or local testing.

A useful first combination might contain one primary coding model, one lower-cost coding fallback, and one independent provider for outage testing. The exact model names should come from the models currently connected to the OmniRoute installation. Avoid copying old model lists into production rules because availability, pricing entries, and provider credentials can change.

If the installation supports per-key candidate controls, inspect the candidate endpoint before enabling the client. The Auto Combo documentation describes GET /v1/auto-combo/{channel}/candidates, which reports candidate reachability and per-key exclusions for an auto/* channel. (Candidate control documentation)

This gives the operator a better starting point than guessing from a saved configuration. A candidate that exists in a configuration file but has a failed credential, cooldown, breaker state, or model lockout should not be treated as a healthy fallback.

Decide whether cheapest fallback is acceptable

The most important OmniRoute Auto Combo setting is the behavior after all candidates exceed the request cap.

The documented choices are:

• cheapest: select the globally cheapest candidate even if it still exceeds the cap.
• strict: refuse to select a candidate and fail fast with HTTP 402.
• Aliases such as soft, cheapest-viable, hard, and block are documented, but production rules should use the canonical values unless the installed version confirms alias support.

This distinction answers several common routing questions:

• If Auto Combo exceeds the budget: cheapest continues with the least expensive candidate, while strict blocks the request.
• To stop an over-budget request: send X-OmniRoute-Budget-Fallback: strict or save the equivalent persistent combo policy.
• To prevent a more expensive automatic fallback: combine a candidate allowlist with strict; do not rely on cheap mode alone.
• To use different budgets for different Agents: issue separate API keys or route clients through separate saved combos, then apply request-level headers only where a temporary override is justified.

The documented request controls are:

• X-OmniRoute-Mode
• X-OmniRoute-Budget
• X-OmniRoute-Budget-Fallback

These headers affect the current request without mutating the saved combo configuration. When the headers are absent, OmniRoute uses the saved mode, budget cap, and fallback policy. (Per-request control reference)

Apply a request-level budget with an explicit failure policy

Use placeholders for the gateway address, API key, and budget. The following pattern keeps the test isolated from real credentials:

curl -sS "${OMNIROUTE_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${OMNIROUTE_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "X-OmniRoute-Mode: cost-saver" \
  -H "X-OmniRoute-Budget: ${REQUEST_BUDGET_USD}" \
  -H "X-OmniRoute-Budget-Fallback: strict" \
  -d '{
    "model": "auto",
    "messages": [
      {
        "role": "user",
        "content": "Return a short health-check response."
      }
    ]
  }'

Expected result:

• At least one eligible candidate is estimated below the cap: the request proceeds through Auto Combo.
• Every candidate is estimated above the cap: the request fails before model selection with the documented strict behavior.
• The mode header is unknown: the current documentation says the unknown value is ignored and the saved configuration is preserved.
• The fallback header is unknown: the documented behavior is also to ignore the unknown value, so configuration validation should catch mistakes before production rollout.

Do not treat the example budget as a recommended production amount. The correct value depends on the model pricing entries, expected input size, output ceiling, tool-loop behavior, and whether the Agent retries failed requests.

The current user guide also documents a separate Dashboard → Costs area for API-key spending limits and pricing entries. However, the current API reference notes that the older {keyId, limit, period} budget shape returns 400 Bad Request, while the newer schema uses apiKeyId and fields such as dailyLimitUsd, weeklyLimitUsd, or monthlyLimitUsd. Pin the installed version and validate the schema before copying an older command. (Current budget schema)

Use this decision path before enabling production traffic

Choose the branch that matches the actual risk:

• If every eligible model must stay under the request cap, choose strict. A request that cannot meet the cap should fail visibly so the Agent or operator can decide what to do next.
• If availability matters more than a hard per-request ceiling, choose cheapest. Add an alert and accept that the selected model may exceed the cap.
• If a model is unsuitable for tools or coding, exclude it even when it is cheaper. Cost cannot compensate for an incompatible response format or unreliable tool behavior.
• If a client has its own retry loop, keep the gateway strict and inspect total attempts. One blocked request can become several blocked requests if the client retries without backoff.
• If the same team runs different workloads, use separate API keys or combos. A coding Agent, a summarization worker, and an experimental client should not silently share one broad candidate pool.
• If no candidate remains after health and budget filters, return the failure to the caller. Do not add an expensive emergency model unless that exception is part of the approved policy.

This is the central budget routing rule: first constrain eligibility, then choose a model. Reversing the order lets the scoring system decide among models that should never have been eligible.

Simulate four failure conditions before connecting an Agent

A configuration is not ready because one normal request succeeded. Run four controlled tests and save the response body, status code, route explanation, and final model record.

1. Every candidate exceeds the cap

Set a deliberately low placeholder budget in a non-production key. With strict, the expected result is a fast rejection rather than a request sent to the cheapest model. With cheapest, the expected result is a fallback to the globally cheapest candidate, even though it exceeds the cap.

Failure handling:

• If strict mode still sends an upstream request, stop the rollout.
• Confirm the request carried the correct header.
• Confirm the client did not rewrite or remove custom headers.
• Check that the request used an Auto Combo model such as auto, not a direct provider model.

2. The preferred provider is unavailable

Disable the credential, place the provider into a test failure state, or use a controlled outage simulation. The expected result is a move to another eligible candidate if the remaining candidate satisfies the budget and capability rules.

Failure handling:

• Confirm the replacement model belongs to the allowlist.
• Confirm the route explanation records the failed provider or health reason.
• Confirm the final model is not more expensive than the request policy permits.
• Restore the credential and rerun the test because recovery behavior can differ from initial failure behavior.

3. The credential is invalid

Use a dedicated test connection rather than editing a production secret. The gateway may report an authentication failure, remove the candidate from the usable pool, or trigger a retry path depending on the provider adapter and installed version.

Failure handling:

• Record whether the error came from OmniRoute or the upstream provider.
• Check whether the client retries with the same key.
• Rotate or restore the credential only after the test log is saved.
• Do not expose raw credentials in route logs, shell history, or screenshots.

4. The provider is rate-limited

Trigger the condition with a controlled low-quota test account or a provider-side limit that the team can safely reset. The expected result is either a healthy candidate switch or a clear failure when no eligible alternative remains.

Failure handling:

• Verify that the replacement respects the budget.
• Check whether the provider entered a cooldown or breaker state.
• Confirm that repeated client retries do not create a request storm.
• Clear or wait for the documented cooldown before declaring the provider permanently unavailable.

Connect one non-production Agent first

After the four simulations pass, connect only one client. Claude Code, Cursor, and a self-hosted Agent may all use an OpenAI-compatible or provider-compatible gateway path, but their handling of streaming, tool calls, timeouts, and retries can differ.

Use placeholders in the client configuration:

export OMNIROUTE_BASE_URL="https://gateway.example.invalid"
export OMNIROUTE_API_KEY="REPLACE_WITH_TEST_KEY"
export OMNIROUTE_MODEL="auto"

Validate the following sequence:

1. A short non-streaming request completes.
2. A streaming request returns incremental output.
3. A tool call is emitted and completed correctly.
4. A longer task does not bypass the gateway with a direct provider URL.
5. The client does not replace auto with a hard-coded model after an error.
6. Client retries do not remove the budget and strict headers.
7. The gateway log identifies the selected model and the reason for selection.

The OmniRoute user guide shows different base URL conventions for clients. For example, its Claude Code example uses the Claude-compatible root endpoint without appending /v1, while OpenAI-style clients use the gateway base URL according to their client implementation. Confirm the correct path for the installed client instead of copying one integration format into another. (Client configuration guide)

To confirm why a request used a particular model, correlate three records:

• The incoming request identifier.
• The route explanation or candidate decision.
• The final provider, model, and usage record.

A final model name alone is not enough. It tells the operator what happened, not whether the route respected health, budget, quota, or task-fit rules.

Roll out by key, client, or team

Use a staged rollout rather than changing the shared gateway rule for every user at once.

A sensible sequence is:

• Test key only.
• One developer or one non-production Agent.
• One team with a known workload.
• Remaining clients after the first review window.
• Production workloads after the route distribution and failure rate are acceptable.

During the first rollout period, monitor:

• Actual cost per request.
• Requests rejected by strict policy.
• Number of fallback attempts.
• Provider and model distribution.
• Tool-call failures.
• Streaming interruptions.
• Client retry counts.
• Requests with missing or invalid routing headers.

Create an alert when the request budget is reached repeatedly, when one fallback model receives an unexpected share of traffic, or when a provider begins failing authentication checks. The API reference documents webhook events for request completion, quota exhaustion, and key rotation, which can support an operational alert path if the deployed version exposes those events as documented. (Webhook API reference)

Keep a configuration change record containing:

• The previous candidate list.
• The new candidate list.
• The old and new fallback policy.
• The affected API keys or clients.
• The test request identifiers.
• The operator who approved the change.
• The rollback command or saved configuration.

Only after this process should a local gateway move into a continuously online environment. Teams evaluating that move can compare the operational tradeoffs in Zilmac's Mac VPS plans and cloud Mac rental options, especially when remote members need a shared macOS-based workspace rather than separate local machines.

Recheck prices, credentials, and candidate health

Auto Combo rules age faster than most application configuration. A model can become cheaper, more expensive, unavailable, rate-limited, or unsuitable for a workload without any change to the Agent code.

Schedule a review when:

• An upstream pricing entry changes.
• A provider changes authentication requirements.
• A model is renamed or removed.
• The team adds a new coding or tool-use model.
• The gateway version changes.
• A fallback or retry incident occurs.
• The route distribution shifts without an intentional configuration change.

Repeat the four failure simulations after each material routing change. Also compare the saved pricing table with the current provider billing documentation. OmniRoute calculates usage from its pricing entries, so an outdated internal price can make a route appear compliant while the provider invoice tells a different story. (OmniRoute cost tracking guide)

For long-running teams, the strongest pattern is not “always choose the cheapest model.” It is “choose the cheapest model inside a reviewed capability and budget boundary.” That boundary should have a fast rollback path, separate keys for separate Agents, and a visible failure mode when no acceptable candidate remains.

A local OmniRoute setup is often the best place to validate these rules because it gives the operator direct access to credentials, logs, and test clients. It becomes a weaker long-term arrangement when remote members depend on one workstation, credentials remain tied to one machine, provider outages require manual access, or the host cannot stay online reliably. In those cases, renting a managed Mac environment from Zilmac can provide a cleaner shared workspace for the gateway and Agent clients, while teams with stable heavy workloads or a need for direct physical interfaces should still compare the economics of owning dedicated hardware.

Start with one test Agent, enforce strict where the cost ceiling is real, and keep cheapest only for workloads that explicitly accept over-cap fallback. That sequence gives the team a visible failure instead of a silent bill.

• Compare model pricing and routing strategies for budget-conscious Agent workloads
• Compare predictable subscriptions with usage-based API budgets for Agents