The Fire Hydrant — OpenBurnBar's routed client gateway at 127.0.0.1:8317 — receives OpenAI-shape requests on /v1/chat/completions from Cursor, Factory, Forge, OpenCode and Codex, and Anthropic-shape requests on /v1/messages from Claude Code. Each request is only ever served by accounts in the same format pool, then ranked by live quota health and least-recently-used. When an account hits its quota, rate-limits, or sees an auth failure, the router shifts traffic within the same pool — before your IDE notices. Routing is deterministic, auditable, and entirely on-device.
Tool-call schemas, prompt-cache markers, and streaming-event types differ enough between OpenAI Chat Completions and Anthropic Messages that "translating" between them quietly breaks things — citations go missing, tool calls misfire, cache markers drop. The Hydrant refuses that game. A request on one endpoint can only be served by accounts in that pool. Same-format failover. Provable in tests.
OpenAI Chat Completions · SSE stream pass-through
Anthropic Messages · sk-ant via x-api-key · Bearer for OAuth
ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN.x-api-key; OAuth bearer → Authorization.2023-06-01 on every request.
Source · OpenBurnBarDaemon/.../OpenBurnBarHTTPGatewayServer.swift · OpenBurnBarAnthropicProviderExecutor.swift
The diagram below mirrors what the macOS app shows on the Router tab. Active routes glow ember, next-fallback candidates wait in amber, cooled-down accounts recover quietly, and exhausted accounts are visibly out of play until their cooldown elapses.
Six client targets — Cursor, Factory, Forge, OpenCode, Codex CLI, and Claude Code — point at one local gateway running on 127.0.0.1:8317. The gateway exposes two independent routing pools: OpenAI-compatible served at /v1/chat/completions and Anthropic-compatible served at /v1/messages. A request to one pool can only be served by accounts in that pool — format families never cross. Inside each pool the router ranks healthy accounts by preferred pin, then local credential, then quota health, then a stable sort key, then least-recently-used. Six OpenAI-family provider lanes are shown (Z.ai active, MiniMax next-fallback, Kimi and OpenAI healthy, Ollama Cloud cooling-down, Ollama Local exhausted by auth failure) plus two Anthropic-family lanes (Claude Pro active, Anthropic Console next-fallback).
Some providers are routed through the Hydrant — your request lands at OpenBurnBar's local gateway and gets forwarded. Others are tracked for cost and quota only — we read the dashboard, we don't proxy the inference. Both are useful. Only the routed ones benefit from automatic failover today.
Source · catalog.json · ProviderAccountTypes.swift:403-599
Source · docs/PROVIDERS.md · AgentLens/Services/ProviderQuota/
Codex CLI in ChatGPT-auth mode stays tracked-only. In OPENAI_BASE_URL / API-key mode it flows through the Hydrant like any OpenAI-family client.
When a request arrives, the router runs every candidate account through a filter, then ranks the survivors with a stable, deterministic comparator. The winner serves the request; the runner-up is held in reserve for instant failover.
| # | Rule | What it does | Tiebreaker on equal |
|---|---|---|---|
| 0 | Format pool | Drop every candidate whose formatFamily doesn't match the inbound endpoint. /v1/chat/completions keeps only openai_compat accounts; /v1/messages keeps only anthropic accounts. If the pool is empty: 503 with a structured "missing pool" error. | — |
| F | Filter | Drop deleted, disabled, exhausted, rate-limited, cooling-down (until elapsed), auth-failed, model-incompatible, routing-disabled, missing-credential accounts. | — |
| 1 | Preferred pin | If you've pinned an account as preferred and it's healthy, it wins. Period. | Fall through to #2 |
| 2 | Local credential | An account with a credential available locally outranks one whose secret would have to be fetched. | Fall through to #3 |
| 3 | Quota health | healthy › pressure › unknown › cooling-down › rate-limited › exhausted › auth-failed › disabled › deleted. | Fall through to #4 |
| 4 | Sort key | The user-controlled sortKey field — drag-to-reorder in the Mac app. | Fall through to #5 |
| 5 | Least-recently-used | The account whose last request is oldest wins — round-robins evenly across equally-healthy peers. | Fall through to #6 |
| 6 | Stable IDs | Provider ID, then account ID. Guarantees the same ranking from the same inputs — every time. | — |
Implementation · ProviderRoutingPolicy.decide(...) in ProviderAccountTypes.swift:403–599
Vendor quota API reports headroom. Recent requests have succeeded. Eligible to serve.
Less than 20% of the active quota bucket remains. Still eligible, but ranked below truly-healthy peers.
Recent transient failure, 401, or rate-limit. Parked for five minutes — then automatically retried.
Provider returned 429. Cool-down ticks while traffic shifts to the next healthy peer.
Daily / weekly / monthly cap hit on a quota bucket. Held until the window rolls or you swap keys.
Token expired or revoked. Cool-down + UI flag so you re-auth at a moment that's convenient.
Routing turned off for this account by the user. Quota is still tracked; traffic is not sent.
Quota probe stale or never run. Eligible, but ranked below known-healthy peers.
Claude Code hits the 5-hour limit on your primary Pro plan. The hydrant marks that slot exhausted, parks it for the rolling window, and the next /v1/messages call lands on your second Pro plan — or your Anthropic Console key — all in the Anthropic pool.
· OpenBurnBarHTTPGatewayServer.swift · /v1/messages handler · testGatewayFailsOverAnthropicAccountOnQuotaExhausted
Set OPENAI_BASE_URL to the hydrant. Pin your ChatGPT API key as preferred for cost. When it runs out, the router shifts to the OpenAI pay-as-you-go account, and if that's also pressured, to your Z.ai plan. Same OpenAI shape end to end.
· ROUTED_CLIENT_GATEWAY.md · preferred-provider + LRU within OpenAI-family pool
Z.ai, MiniMax, and Kimi all speak OpenAI-shape JSON. When all three are healthy on a fungible model, the router round-robins by least-recently-used — fair share across your accounts instead of hammering one until it goes red.
· ProviderRoutingPolicy.decide · ranks by quota-health, then sortKey, then LRU
A Claude Code request hitting /v1/messages can only be served by accounts in the Anthropic pool. If you have no Anthropic accounts configured, the hydrant returns a structured 503 telling you exactly which pool you're missing — not a corrupted response, not a tool-call schema mismatch.
· ProviderAccountTypes.swift · formatFamily filter · testGatewayMessagesReturns503WhenOnlyOpenAICompatProvidersConfigured
kSecAttrAccessibleWhenUnlockedThisDeviceOnly. The Hydrant
fetches them on-demand for outbound requests; they never reach
OpenBurnBar's cloud unless you opted into hosted quota refresh.
ProviderRoutingDecisionEvent stream you can inspect.
Source · docs/ROUTED_CLIENT_GATEWAY.md · docs/THREAT_MODEL.md · ProviderRoutingStateBuilder.swift
Add a second key, pin a preferred provider, and let the Fire Hydrant keep the inference flowing.