The Zenith Routing Engine

When you have multiple accounts across multiple providers, the router's most important job is picking the right one for each request — fast, and without wasting calls on accounts that are about to rate-limit you. kRouter's default answer is the Zenith Score Engine.

The problem with dumb failover

Older routers used a fill-first or random loop: hammer one account until it returns a 429, then fall back to the next. That wastes every rate-limited request, and worse, the fallback loop hit SQLite on every step. If five accounts were dead, the loop touched the disk ten times — roughly 50ms of overhead per failure, and a visible stall in your IDE.

kRouter replaced both problems.

Zenith: score, then pick

Instead of discovering dead accounts by hitting them, Zenith pre-ranks every account before choosing:

• Live health data — TTFB latency and success rate per connection
• Quota headroom — remaining percentage, with accounts under 30% heavily penalized

Zenith computes a score for every candidate account and picks the mathematically best one to fulfill the request. Because it avoids accounts that are likely to fail before sending, it eliminates wasted rate-limited requests rather than reacting to them. Zenith is the default routing strategy.

The sub-5ms RAM layer

Zenith's decisions run against an in-memory HealthCache, not the database. All active connections and their locks live in RAM:

• When an account hits a 429, the router locks it in memory and grabs the next one in under 1ms
• The SQLite write that persists the lock is fired asynchronously in the background

The hot path never blocks on disk. Failover that used to add ~50ms now happens in single-digit milliseconds — the difference between a stalling IDE and one that never notices a rate limit.

Zenith visibility

Routing decisions are logged. The Zenith decision log records why each account was chosen — its score, health, and headroom — so when routing does something surprising you can see the reasoning instead of guessing. This visibility landed alongside the engine so the "why did it pick that account" question always has an answer.

Multi-account fairness and ban recovery

Beyond per-request scoring, kRouter balances load across accounts over time:

• Fairness — traffic is distributed so one account is not silently exhausted while others sit idle
• Exponential ban recovery — when an account gets cooled down, it recovers on an exponential backoff rather than being retried aggressively (which would just re-trigger the ban)
• Input-size safety — kRouter stops burning accounts on input-size errors, which are the client's fault, not the account's

Together these keep a pool of accounts healthy instead of chewing through them.

The alternative strategies

Zenith is the default, but you can pick a simpler strategy per provider if you want deterministic behavior:

Zenith sits on top of 3-tier fallback

Routing strategy (which account within a tier) is separate from tier fallback (which provider tier). kRouter's combos define a 3-tier stack — subscription → cheap → free — and Zenith picks the healthiest account within whichever tier is active. When a whole tier is exhausted, the combo falls through to the next tier, and Zenith scores accounts there.

See /docs/combos for building fallback stacks, and the Zenith deep-dive for the engine's design story.

Get started

npm install -g @sifxprime/krouter
krouter -t

Zenith is on by default — you get intelligent routing the moment you connect a second account. See /install to get running and /providers to add accounts.