OmniRoute Environment Variables for Provider Circuit Breaker and Cooldown Configuration

OmniRoute uses 18 environment variables organized into three provider profile categories—OAuth, API key, and Local—to control failure thresholds, counting windows, cooldown durations, and backoff escalation for its provider-level circuit breaker system.

OmniRoute's three-layer resilience architecture depends on tunable circuit breaker parameters that operators can adjust without code changes. These settings determine when a provider enters an OPEN state, how long it remains isolated, and when it becomes eligible for health probes again. All configuration values are read at runtime from environment variables in open‑sse/config/constants.ts and wired into the PROVIDER_PROFILES object.

OAuth Provider Circuit Breaker Variables

OAuth-based providers use the most conservative defaults due to their complexity and rate-limit sensitivity. Six environment variables control this profile:

• OMNIROUTE_PROVIDER_BREAKER_OAUTH_FAILURE_THRESHOLD — Number of failures that trip the breaker (default: 10)
• OMNIROUTE_PROVIDER_BREAKER_OAUTH_FAILURE_WINDOW_MS — Rolling window for failure counting (default: 900000 ms / 15 minutes)
• OMNIROUTE_PROVIDER_BREAKER_OAUTH_COOLDOWN_MS — Isolation duration once threshold reached (default: 300000 ms / 5 minutes)
• OMNIROUTE_PROVIDER_BREAKER_OAUTH_DEGRADATION_THRESHOLD — Failures before marking provider DEGRADED (default: 5)
• OMNIROUTE_PROVIDER_BREAKER_OAUTH_MAX_BACKOFF_MULTIPLIER — Ceiling for exponential backoff (default: 8×)
• OMNIROUTE_PROVIDER_BREAKER_OAUTH_BACKOFF_ESCALATION_COUNT — Consecutive open cycles before max multiplier applies (default: 2)

API Key Provider Circuit Breaker Variables

API key providers tolerate higher failure rates with longer windows and more gradual backoff escalation:

• OMNIROUTE_PROVIDER_BREAKER_API_KEY_FAILURE_THRESHOLD — Failure count to open breaker (default: 15)
• OMNIROUTE_PROVIDER_BREAKER_API_KEY_FAILURE_WINDOW_MS — Counting window (default: 1800000 ms / 30 minutes)
• OMNIROUTE_PROVIDER_BREAKER_API_KEY_COOLDOWN_MS — Cooldown after threshold breach (default: 600000 ms / 10 minutes)
• OMNIROUTE_PROVIDER_BREAKER_API_KEY_DEGRADATION_THRESHOLD — Degradation trigger point (default: 7)
• OMNIROUTE_PROVIDER_BREAKER_API_KEY_MAX_BACKOFF_MULTIPLIER — Maximum backoff multiplier (default: 4×)
• OMNIROUTE_PROVIDER_BREAKER_API_KEY_BACKOFF_ESCALATION_COUNT — Escalations before ceiling (default: 3)

Local Provider Circuit Breaker Variables

Local providers use aggressive thresholds for rapid failure detection and recovery:

• OMNIROUTE_PROVIDER_BREAKER_LOCAL_FAILURE_THRESHOLD — Failures before cooldown (default: 2)
• OMNIROUTE_PROVIDER_BREAKER_LOCAL_FAILURE_WINDOW_MS — Counting window (default: 300000 ms / 5 minutes)
• OMNIROUTE_PROVIDER_BREAKER_LOCAL_COOLDOWN_MS — Recovery duration (default: 60000 ms / 1 minute)

How Variables Are Parsed and Applied

The envInt utility in open‑sse/config/constants.ts (lines 250‑284) parses these variables and constructs the three provider profiles. The circuit breaker logic evaluates HTTP status codes defined in src/sse/handlers/chatPredicates.ts (line 5) for single-model paths and open‑sse/services/combo/comboPredicates.ts (line 131) for combo routing.

When failures exceed the threshold within the specified window, the breaker transitions to OPEN and records a timestamp. The canExecute check compares elapsed time against the configured *_COOLDOWN_MS value to determine when the provider becomes HALF‑OPEN and eligible for probe requests.

Practical Configuration Examples

Override defaults in your environment or .env file:

# Extend API key provider tolerance for unreliable upstreams

OMNIROUTE_PROVIDER_BREAKER_API_KEY_FAILURE_THRESHOLD=20
OMNIROUTE_PROVIDER_BREAKER_API_KEY_COOLDOWN_MS=900000

# Aggressive OAuth recovery for development

OMNIROUTE_PROVIDER_BREAKER_OAUTH_COOLDOWN_MS=60000
OMNIROUTE_PROVIDER_BREAKER_OAUTH_MAX_BACKOFF_MULTIPLIER=2

Access configured values programmatically:

import { PROVIDER_PROFILES } from "@omniroute/open-sse/config/constants";

const profile = PROVIDER_PROFILES.OAUTH;
console.log(`Threshold: ${profile.providerFailureThreshold}`);
console.log(`Cooldown: ${profile.providerCooldownMs}ms`);

Force breaker state for testing:

import { setProviderBreakerOpen } from "@omniroute/open-sse/services/circuitBreaker";

setProviderBreakerOpen("openai", {
  openedAt: Date.now(),
  failureCount: 12,
});
// Provider remains excluded until OMNIROUTE_PROVIDER_BREAKER_OAUTH_COOLDOWN_MS expires

Variable Reference Summary

Variable Pattern	Default Range	Typical Use Case
*_OAUTH_*	5‑15 min windows, 5 min cooldown	Third-party OAuth services (OpenAI, Anthropic)
*_API_KEY_*	10‑30 min windows, 10 min cooldown	Direct API integrations with key authentication
*_LOCAL_*	1‑5 min windows, 1 min cooldown	Self-hosted or development models

Summary

• OmniRoute provider circuit breaker configuration uses 18 environment variables split across OAuth, API key, and Local provider profiles
• All variables follow the naming convention OMNIROUTE_PROVIDER_BREAKER_<TYPE>_<PARAMETER>
• Variables are parsed in open‑sse/config/constants.ts using the envInt helper and bound to PROVIDER_PROFILES
• Cooldown durations control how long providers remain in OPEN state before HALF‑OPEN probing
• Failure status codes are synchronized between single-model and combo routing paths via predicate definitions

Frequently Asked Questions

What happens if I don't set these environment variables?

OmniRoute applies sensible defaults for each provider type. OAuth uses the strictest settings (10 failures/15 min window), API key providers are more lenient (15/30 min), and local providers fail fast (2/5 min). All defaults are hardcoded in open‑sse/config/constants.ts lines 250‑284.

Can I disable the circuit breaker entirely?

No dedicated disable flag exists in the source. Setting OMNIROUTE_PROVIDER_BREAKER_*_FAILURE_THRESHOLD to an extremely high value (e.g., 10000) effectively prevents tripping, though this is not recommended for production.

How do I monitor which environment values are active?

Import PROVIDER_PROFILES from the constants module and log the resolved configuration at startup. The tests/unit/provider-breaker-env-overrides.test.ts file demonstrates assertion patterns for verifying override behavior.

Do cooldown values stack with exponential backoff?

Yes. The base cooldown is multiplied by an escalating factor up to the configured MAX_BACKOFF_MULTIPLIER after the specified number of consecutive open cycles. An OAuth provider with default 5-minute cooldown could see 40-minute isolation after 2+ escalations (5 min × 8× multiplier).

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