# OmniRoute Environment Variables for Provider Circuit Breaker and Cooldown Configuration

> Discover OmniRoute environment variables to configure provider circuit breaker and cooldown settings. Optimize failure thresholds and backoff escalation for OAuth, API key, and Local profiles. Learn more now.

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

---

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

```bash

# 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:

```typescript
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:

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