mirror of
https://github.com/diegosouzapw/OmniRoute.git
synced 2026-08-06 15:22:12 +03:00
8180b49ce1
* fix(quality): resolve net-new lint errors and allowlist #9343 assert rewrite Two `no-explicit-any` errors landed with #9407 and #9320 after the suppressions inventory was generated. Project policy is to fix new violations rather than freeze them, so both are typed instead: - #9407: `executor as unknown as Record<string, unknown>` - #9320: `(k: { name?: string })` Also allowlists the net-assert reduction in web-tools-translation-2820 (39->35). #9343 inverted the contract — bare JSON must no longer be promoted to tool_calls without an explicit <tool> envelope — so the tests were rewritten to assert non-promotion, which costs fewer asserts than validating a promoted object. More restrictive, not weaker. * fix(quality): raise integration ceiling to 40min and unpin codex-cli version in test The integration gate's 20min ceiling killed a healthy run: measured 22m08s hermetic on an idle 16-core box (935 tests across 112 files, strictly serial at --test-concurrency=1 because ~16 of them bind a port or share a DB). The "~3-10min" estimate in the code was stale by ~3x. 40min keeps the ceiling's real purpose — turning a genuine hang into a visible failure — without failing a long-but-healthy suite. Also fixes a base-red in chat-pipeline:564c204efebumped DEFAULT_CODEX_CLIENT_VERSION to 0.146.0 but the User-Agent assertion still pinned 0.144.1. The line two above already read the constant via getCodexClientVersion(); this one duplicated the literal. Deriving it from the same source stops the next bump from breaking the test again. * fix(ratelimit): re-arm Bottleneck reservoir heartbeat after updateSettings Bottleneck 2.19.5 (frozen upstream dependency, no release since 2019) has a bug in LocalDatastore#_startHeartbeat() (node_modules/bottleneck/lib/ LocalDatastore.js:29,56): the guard `if (this.heartbeat == null && ...)` only (re)creates the periodic reservoir-refresh interval the first time it runs. Every later call -- including the one updateSettings() itself triggers internally -- falls into the else branch and does clearInterval(this.heartbeat) WITHOUT resetting the reference back to null. Because the stale reference sticks around, every future _startHeartbeat() call keeps taking the same dead else branch: the periodic reservoir refresh is gone forever after the first manual updateSettings() call on a limiter. Every limiter created by this file starts with a live heartbeat (buildLimiterDefaults() always sets reservoirRefreshInterval/ reservoirRefreshAmount), so the very first updateFromHeaders() / updateFromResponseBody() / applyRequestQueueSettings() call against a limiter permanently kills its refresh. In production this wedges the request queue once the reservoir hits 0: an auto-enrolled apikey connection accumulates its default 60 requests, the reservoir zeroes, the queue freezes for ~120s, the watchdog fires a synthetic 502 (RATE_LIMIT_QUEUE_WEDGED), the connection cools down and gets excluded from weighted combo pools -- turning a configured 70/30 split into ~50/50. Add applyLimiterSettings(), a module-local wrapper around limiter.updateSettings() that nulls the stale heartbeat reference and re-invokes _startHeartbeat() afterward so it takes the "start a fresh interval" branch again. Route all 5 updateSettings() call sites through it (updateAllLimiterSettings, both updateFromHeaders() branches, loadPersistedLimits(), and updateFromResponseBody()). updateAllLimiterSettings is now async and awaited by its two callers (initializeRateLimits, applyRequestQueueSettings); the sync call sites use the existing trackAsyncOperation() fire-and-forget tracking pattern. tests/integration/combo-matrix/weighted.test.ts is the E2E proof: the "weighted: 70/30" case now passes with zero WEDGED/RATE_LIMIT_QUEUE/502 log lines across 200 sequential requests (previously the wedge/recovery cycle inflated its runtime and skewed the distribution toward ~50/50). Refs #8213 * fix(tests): remove stray TDD probes committed by accident inf4e93f339dThree TDD repro/probe test files landed on the release tip viaf4e93f339d(docs: add management authentication terminology guide, files from a worktree. Each file is a pre-fix TDD probe that belongs to a *different*, still-in-flight fix branch/PR and duplicates a file path that PR already owns and will properly update on merge: - tests/unit/authz/probe-9033-repro.test.ts: probe for #9033 (IP blacklist direct-connection bypass). 3/4 asserts fail against this tree (D1, D2, Bonus — all assert the not-yet-implemented target behavior); D3 passes (pre-existing behavior). Owned by PR #9385 (open, unmerged), which modifies this exact path. - tests/unit/repro-8522.test.ts: probe for #8522 (absolute file-size baseline reds innocent PRs on inherited drift). First test fails against this tree's evaluateFileSizes (still absolute-only); second (sanity: real growth still flags) passes. #8522 is actually CLOSED upstream — PR #9355 merged the real fix into release/v3.8.50 today (2026-08-05T15:53Z) modifying this exact path — but this branch's merge-base with release/v3.8.50 (6b0e11e378) predates that merge, so the fix has not synced into this tree yet. - tests/unit/repro-8956.test.ts: probe for #8956 (resolveProjectRoot stops at synthetic Next.js standalone package.json). First test fails against this tree; second (sanity: named package.json still resolves) passes. Owned by PR #9354 (open, unmerged), which modifies this exact path. Each deleted file's real implementation + passing version already exists in its owning PR and will land normally through that PR's own merge — deleting the premature copy here does not lose any coverage. No config/quality/test-masking-allowlist.json entry was added: the _deletedWithReplacement schema only supports `replacement` (a test file that must already exist in this tree's HEAD — none does, the real versions live in the unmerged sibling PRs above) or `sourceRemoved` (production files that must be absent from HEAD — they are not, none of the three issues are implemented in this tree). Neither shape fits an "owned by an in-flight sibling PR" deletion, so the CI test-masking gate will flag these 3 deletions for mandatory human review on this branch's next PR diff against release/v3.8.50 — flagged for the owner rather than inventing a new allowlist shape. Refs #9033, #8522, #8956, #7786 * fix(tests): align 8189-classifier-compat with #9276 always-mode semantics tests/unit/8189-classifier-compat-auto-narrow.test.ts was a test-sibling forgotten when #9276 (commit6b531fbacd) removed the unconditional `if (mode === "always") return true` branch from shouldDefaultAllowClassifier(). tests/unit/claude-classifier-compat.test.ts was updated in that same commit; this file was not. Old contract: 'always' mode short-circuited every Claude-format request unconditionally (operator opt-in was treated as sufficient on its own). New contract: 'always' now requires the same SECURITY_MONITOR_MARKER system-prompt text as 'auto' — the marker-optional behavior let a normal chat request through /v1/messages be silently swallowed by an operator's 'always' opt-in. The single 'always' test (1 assert, no-marker body expecting true) is replaced by two tests mirroring the depth already used for 'auto' mode in the same file: no-marker/false and marker-present/true. Net effect is +1 assert, not a reduction — the new pair verifies both directions of the narrowed contract instead of only the now-incorrect unconditional case. Before: 3/4 pass (the 'always' test failed: expected true, got false). After: 5/5 pass. Refs #9276 * fix(tests): align deepseek-web-tools-execute with #9343 tool envelope contract tests/unit/deepseek-web-tools-execute-2820.test.ts (executor level) was a test-sibling forgotten when #9343 (commitd969555417) hardened tool-call parsing: bare JSON with no explicit <tool>/<tool_call> envelope is never promoted to tool_calls anymore (previously it was, whenever a tools[] set was requested — a security gap allowing prose/code-fenced JSON echoed back by the model, or a copy-attack, to trigger real tool execution). Three siblings were updated in the same commit: web-tools-translation.test.ts and web-tools-translation-2820.test.ts (parseToolCallsFromText, the shared translator), and deepseek-web-tools-variants.test.ts (parseDeepSeekToolCalls, deepseek-specific parser) — all inverted their bare-JSON assertions to `toolCalls === null` + `content === text` (preserved verbatim, not stripped). This file calls the executor's execute() (full HTTP round trip through buildToolAwareResult), so it was not touched by that diff and kept asserting the old contract (finish_reason: "tool_calls", content: null). Verified against source (open-sse/executors/deepseek-web.ts buildToolAwareResult): when parseDeepSeekToolCalls returns toolCalls=null, hasCalls is false, so finish_reason is "stop", message.tool_calls is never set, and message.content is the parser's returned content — which for text with no <tool>/<tool_call> tag at all is the original string, unchanged (parseToolCallsFromText's early-return branch). The test now asserts exactly that shape, at the same executor level as the rest of the file's tool_calls that make sense at that level as the rest of the file's tool_calls Refs #9343 * fix(tests): align visionBridge tests with #8430 contract (partial — see note) Two test-siblings were forgotten when #8430 (commit7e55abbc41) hardened Vision Bridge's vision-model selection: getBestVisionModel() now validates that a candidate has a usable active connection (hasUsableCredentialsForModel, DB-backed) before returning it, instead of unconditionally returning the fixedModel or a hardcoded "openai/gpt-4o-mini" default. Three siblings were updated in the same commit (visionBridgeRouter.test.ts, the new repro-8430.test.ts, vision-bridge-preserve-on-failure-4012.test.ts); these two were not. tests/unit/guardrails/visionBridgeHelpers.callVisionModel.test.ts (8 failures, all "No vision-capable provider connected"): callVisionModel()'s `routerConfig` param only merges into getBestVisionModel's CONFIG argument, never its `deps` argument, so there is no way to inject a credentials stub through this function's public signature (unlike the guardrail class and getBestVisionModel itself, which do accept an injectable `hasUsableCredentials`). These tests exercise callVisionModel's own request/response handling, not credential routing (already covered elsewhere), so the fix seeds one real usable `provider_connections` row per provider the file exercises (openai, anthropic) via createProviderConnection in a test.before() hook, with resetDbInstance() in test.after() per the DB-handle-cleanup convention. All 8 now pass. tests/unit/guardrails/visionBridge.test.ts (7 failures): 1 of the 7 (VB-S03) is a genuine forgotten-contract case, fixed here — same semantic flip already applied to vision-bridge-preserve-on-failure-4012.test.ts: in the combo describe path, when EVERY describe call fails, the raw image is now replaced with an "(unavailable)" stub instead of preserved, because that path is only reached for confirmed non-vision targets. Assertions inverted to match (imagePart undefined, unavailable-stub present), same assert count, no weakening. *** THE OTHER 6 (VB-S12, VB-S12b, VB-S01, VB-S13, VB-S07, VB-S10) ARE DELIBERATELY LEFT FAILING. *** These are NOT a #8430 contract change — root- caused to what looks like a separate, unintentional regression: the ONE call to getBestVisionModel() in visionBridge.ts's whole-request-reroute path (line 244, `getBestVisionModel({ fixedModel: configuredModel })`) does not pass a `deps` second argument, so it always uses the real DB-backed hasUsableCredentialsForModel instead of this.deps.hasUsableCredentials — even though the two adjacent checks in the very same function (`checkCreds(model)` at line 226, `checkCreds(bestModel)` at line 246) DO honor the injectable override. In this suite's empty-but-readable isolated test DB, that real check deterministically returns `false` (not the indeterminate `null` the file's own createGuardrail() comment says these tests rely on: "Fail-open (null) so classic VB-S01/S07/S10 reroute tests keep working without a live credential DB"), so getBestVisionModel silently returns null, the reroute branch's `if (bestModel && ...)` guard never fires, and every test that expects a reroute observes a silent no-op instead. Evidence this is a source gap, not a test that needs updating: - The file's own pre-existing comment names VB-S01/S07/S10 as tests the `null` fail-open default is SUPPOSED to keep green. - VB-CRED-01/02 (the file's only two tests that actually inject a non-default hasUsableCredentials mock) both pass today, but neither one's assertions distinguish "mock honored" from "mock ignored, real check also says no" — they don't prove the threading works, they just don't happen to notice it's missing. - visionBridgeRouter.test.ts, repro-8430.test.ts, and vision-bridge-preserve-on-failure-4012.test.ts (22 tests, all green) all either call getBestVisionModel directly with explicit deps, or mock callVisionModel wholesale (bypassing getBestVisionModel entirely) — none of them exercises this exact call site through the guardrail's own deps. Per instructions, this was intentionally NOT "fixed" by weakening these 6 tests' assertions (that would mask the gap) or by seeding fake DB credentials to route around it (that would hide a real production DI inconsistency behind a test-only workaround) or by touching src/lib/guardrails/visionBridge.ts (a production behavior change outside a test-alignment task's scope, and Hard Rule #18 requires its own TDD/validation cycle). Flagging for the owner: the likely one-line fix is threading `{ hasUsableCredentials: this.deps.hasUsableCredentials }` as getBestVisionModel's second argument at visionBridge.ts:244, mirroring the two adjacent call sites in the same function. Before: 15 failures (7 + 8). After: 9 pass added (1 + 8), 6 still fail (unchanged, by design). Refs #8430 * feat(quality): add strayFromCommit deletion allowlist form to test-masking gate The deletion allowlist supported two shapes: replacement (test rewritten elsewhere) and sourceRemoved (feature deleted). Neither fits a third legitimate case surfaced today: test files that entered the repo BY ACCIDENT — commitf4e93f339d(#7786 docs) swept another session's worktree artifacts into the release, including TDD probes owned by open fix PRs (probe-9033-repro -> PR #9385, repro-8956 -> PR #9354, repro-8522 -> PR #9355). Those probes fail by design until their owning PR merges, so every unit run on the release tip broke on them. The new strayFromCommit form is verified, not trusted: the gate asks git which commit actually ADDED the file (git log --diff-filter=A) and only exempts the deletion when it matches the declared hash; a non-empty reason naming the owning PR/issue is mandatory. Also allowlists the deepseek-web-tools-execute assert reduction (23->21) fromed661f2126— same #9343 contract-inversion class as the existing web-tools-translation entry. Gate unit tests: 55/55 pass. Full gate vs main: OK. * fix(guardrails): pass credential deps to getBestVisionModel at reroute call site The individual-model reroute path in VisionBridgeGuardrail.preCall() calls getBestVisionModel({ fixedModel: configuredModel }) without its second `deps` argument, so the router always falls back to the real DB-backed hasUsableCredentialsForModel instead of an injected `deps.hasUsableCredentials` override. The two adjacent credential checks in the same function (the original-model check and the best-model check, both via the local `checkCreds` binding) already thread deps correctly — only this middle call, added in #8430, was left out. Pass the same resolved `checkCreds` used by those two adjacent checks as `getBestVisionModel`'s deps argument so all three credential checks in this reroute path stay consistent. Fixes 6 tests in tests/unit/guardrails/visionBridge.test.ts that depended on the injected hasUsableCredentials mock being honored on this path: VB-S12, VB-S12b, VB-S01, VB-S13, VB-S07, VB-S10. Refs #8430 * fix(quality): raise unit ceiling to 100min and align 2 more forgotten sibling tests Unit ceiling 45->100min: a hermetic-env measurement on the loaded devbox (load 7-26) was still inside invocation 1 of 3 at 76min when killed; contention factor 2-3x measured, no idle measurement exists. The pre-flight's real condition is exactly that contended one (unit runs in Promise.all with integration+vitest), and there 45min provably killed a healthy suite and fabricated a false base-red. The 45min value came from v3.8.43 as an estimate never validated by measurement. TODO in-code: re-tighten after an idle run on the .113 box. Also aligns the 6th and 7th occurrences of the same systemic pattern (behavior change merged updating only part of the sibling tests): - issue-7859-gemini-web-redirect-valid: #9407 refined ServiceLogin redirects to mean expired session; the #7859 regression coverage is preserved via a non-ServiceLogin public redirect variant. - provider-validation-specialty claude-web 429: #9406 inverted the contract (rate-limited session is unhealthy); the dedicated repro file owns the full contract, this sibling now matches it. Also carries the file-size rebaseline for #9323's base.ts growth (1578->1623, WAF retry + burst guard) and the eslintWarnings baseline tightened 5000->0 (real measured value with the TS7 suppressions in place — 5000 left the ratchet inert). Refs #9407, #9406, #9323 * fix(tests): restore the 3 TDD probes now owned by merged fixes and drop their stray allowlist entries The base advanced while this PR was open: the real fixes for the three issues behind the stray probes all merged into release/v3.8.50 — #9385 (issue 9033), #9355 (issue 8522) and #9354 (issue 8956). - probe-9033-repro / repro-8522: the base rewrote both probes into the regression tests of their merged fixes, so the delete side of the rebase conflict was dropped and the base versions kept. - repro-8956: #9354 only realigned one fixture line in auto-update.test.ts (package.json marker now needs a name field) and added no test for the new skip-synthetic behavior — the probe is the ONLY regression coverage of that merged fix (2/2 green on the base), so deleting it would remove real coverage. Restored. With no test-file deletions left in the PR diff, the three strayFromCommit allowlist entries are stale and removed. The strayFromCommit form support in check-test-masking.mjs stays (covered by its own fixtures). * fix(quality): rebaseline file-size for PR #9529 own growth The base sits exactly at the old frozen values, so the base-relative mode (#8522) does not cover this growth — it is this PR's own: - open-sse/services/rateLimitManager.ts 1060->1105: the applyLimiterSettings() helper that re-arms the reservoir heartbeat after updateSettings (Bottleneck 2.19.5 fix, TDD in ratelimit-reservoir-refresh.test.ts). - tests/integration/chat-pipeline.test.ts 1592->1598: codex User-Agent derived from getCodexClientVersion() instead of a pinned literal. - tests/unit/provider-validation-specialty.test.ts 2980->2985: new claude-web 429 -> valid:false coverage (#9406). * fix(docs): sync provider count to 291 in README and CLAUDE The live catalog counts 291 providers but README.md/CLAUDE.md still said 290, so the STRICT 'Docs Gates (fast-path)' check reds EVERY open PR against release/v3.8.50 (verified on #9537/#9539 as well — inherited base-red, not introduced by this PR). Updated all provider-count mentions including the section anchor. * fix(tests): align launch-codex 6312 guard with the async #9454 spawn contract #9454 made resolveCodexSpawn async (PATH-probes a native codex.exe before the .cmd shim) and updated its own tests, but left this older sibling calling the function synchronously — destructuring the Promise yields undefined and reds Unit fast-path (1/4) for EVERY open PR against the release (verified on #9537/#9539; inherited base-red). Realigned to the async contract with an injected probe; keeps the original #6312 fallback guard plus the only non-Windows codex coverage (now also asserting the probe never runs off Windows). * fix(translator): move state-mutating reasoning summary helper out of the pure leaf #9500 added buildResponsesReasoningSummaryDelta(state, ...) to pureHelpers.ts, but the function reads AND mutates stream state (reasoningSummaryIndex map) — violating the leaf contract declared in the file header ('no host imports, no stream state') and guarded by response-openai-responses-purehelpers-split.test.ts, which reds Unit fast-path (4/4) for every open PR (inherited base-red, verified on #9537/#9539). Moved verbatim to the host next to the other stream-state helpers (markResponsesReasoningDeltaEmitted); the host was its only consumer. Behavior unchanged: repro-9500-reasoning-separator 3/3 green, leaf/host architecture tests green. * fix(quality): rebaseline openai-responses.ts for the leaf-state relocation The #9500 helper moved from pureHelpers.ts into the host (previous commit) grows the host file 1174->1204 while the leaf shrinks by the same amount — net-zero LOC across the pair, but the per-file frozen ratchet only sees the growing side. * fix(tests): let the 9442 cert-mode test see past the harness trust-store guard tests/_setup/isolateDataDir.ts sets OMNIROUTE_SKIP_SYSTEM_TRUST=1 globally, which makes installCert() return before issuing any command — so the #9442 install-gap test captured nothing and could NEVER pass under npm run test:unit (it only passed invoked directly, harness-less; inherited base-red on Unit fast-path 3/4, verified on #9537/#9539). Clear the flag for this file only (restored in test.after): safe because every spawned command is a logging stub on PATH and OMNIROUTE_NO_SUDO=1 strips sudo, so nothing touches the real trust store. 6/6 under the CI harness including system-trust-test-guard. --------- Co-authored-by: diegosouzapw <diegosouzapw@users.noreply.github.com>
🚀 OmniRoute — The Free AI Gateway
💰 ~1.53B Free Tokens / Month
Stacking free tiers by hand is painful — dozens of SDKs, dozens of rate limits, and no idea how much you actually have. OmniRoute aggregates the documented free tiers of 43 provider pools / 516 models into one honest number and shows it live on the dashboard (
/dashboard/free-tiers).
Animated summary of the live
/dashboard/free-tierspage. Full methodology (pool dedupe, credit tiers, provider terms): docs/reference/FREE_TIERS.md.These figures are re-audited every two weeks against the live catalog and move both ways — a provider ends a free tier and the number drops; a new one lands and it climbs. We publish what the catalog actually computes, never a rounded-up best case.
⭐ Star the repo if OMNIROUTE helped you save money and make your work easier.
💬 Join the community
👋 Follow the maintainer — get new providers, releases & tips first:
Questions, provider tips, roadmap & support → Discord · Telegram · WhatsApp 🌍 Global / 🇧🇷 Brasil
🧩 Available
| 🚀 Start | 🚀 Quick Start | 📦 Install | 🆓 Zero-config |
| 💡 Learn | 💥 The Promise | 🤔 Why OmniRoute | 🏆 What Sets Apart |
| ⚙️ Features | 🎯 Combos | 🌐 Providers | 🔌 CLI & MCP |
| 🗜️ Compression | 🖥️ Where It Runs | 🔒 Private | |
| 👀 See it | 🎬 In Action | ✨ What's New | 🤖 Compatible CLIs |
| 💚 Support | 💚 Support / Donate | 💬 Community | 💖 Sponsors |
| 📦 Project | 🛠️ Tech Stack | 📖 Docs | 👥 Contributors |
🌐 In 43 languages
🆓 Works the second you install it — no keys, no config
# Fresh install, zero credentials — `auto` already works:
curl http://localhost:20128/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"auto","messages":[{"role":"user","content":"Hello!"}]}'
Prefer a specific free backend? Call it directly, e.g. oc/… (OpenCode Free) or felo/… (Felo). Then graduate to auto and let OmniRoute pick.
💥 The Promise
🤔 Why OmniRoute?
🤝 Supported by our Open Source Friends
Want to join as an Open Source Friend? These are the companies that back open source and help keep OmniRoute moving — and we say publicly where every token they give us goes. Reach out: diegosouza.pw@outlook.com
Kimi Moonshot AI 
|
Thanks to Kimi (Moonshot AI), our founding Open Source Friend, for backing this project! Kimi is the AI lab behind the open-weight K2 and K3 model families — Kimi K3 delivers a 1M-token context window, native vision and frontier-level coding at a fraction of closed-model prices, and works out of the box with Claude Code, Codex and every coding tool OmniRoute serves.
What Kimi's support powers: Kimi's API credits power OmniRoute's AI-validated release pipeline — the merge validation powered by Kimi K3 stage that reviews every pull request before it ships — plus day-to-day feature development. First-class Kimi support ships on both rails: the direct Kimi API ( kimi-k3) and the Kimi Code coding plan (OAuth and API key). OmniRoute is also the first Brazilian open-source project in Kimi's support program. Get a Kimi API key →
|
Cheaper Inference cheaperinference.com 
|
Thanks to Cheaper Inference, an OmniRoute Open Source Friend, for backing this project! Cheaper Inference is a cost-ranked gateway that resells 42 frontier models — Claude, GPT-5.x, Gemini, Kimi K3, GLM, DeepSeek, Grok and MiniMax — behind one OpenAI-compatible endpoint, routing each request to the cheapest eligible provider without ever charging above the model maker's list price.
First-class support in OmniRoute: Chat Completions, the native /v1/responses endpoint, vision, tool calling and 3 image models (grok-imagine, nano-banana-pro, nano-banana-2, reachable as cheaperinference/<model>). Get an API key →
|
Links tagged aff=omniroute are partner links. They fund the project at no extra cost to you.
🎟️ Affiliates Promo — free signup coupons from providers we don't sponsor (click to expand)
This section is for referral/coupon codes only. Sponsored partnerships live in 🤝 Supported by our Open Source Friends above. OmniRoute has no sponsorship or partnership with the providers listed here — these are public coupons anyone can use.
AgentRouter agentrouter.org |
AgentRouter — affiliate signup · $100 free credits on signup (free server, expect higher latency — best for testing, not production). First-class support in OmniRoute since v3.8.50: Chat Completions, the Anthropic-compatible wire format and the OpenAI-compatible path. Available models include claude-opus-4-8, claude-opus-5, gpt-5.6-sol and more. Grab your $100 →
⚠️ Affiliate link — OmniRoute has no sponsorship or partnership with this provider. |
Know another provider with a generous free signup coupon that benefits OmniRoute users? Open an issue and we'll add it here.
🎯 Combos — The Flagship
A combo is a chain of models OmniRoute routes across automatically. Quota runs out, a provider fails, or costs spike — the combo silently slides to the next model. This is what makes OmniRoute unbreakable. 🛡️
⚡ Zero-config — just use auto
No combo to create. Set your model to auto (or a variant) and OmniRoute builds a virtual combo from your connected providers, scored live:
| Model ID | What it optimizes for |
|---|---|
auto | 🎯 Balanced default (LKGP — sticks to your last good provider) |
auto/coding | 🧑💻 Quality-first weights for code generation |
auto/fast | ⚡ Lowest latency first |
auto/cheap | 💰 Cheapest per token first |
auto/offline | 🔋 Most quota / rate-limit headroom first |
auto/smart | 🔭 Quality-first + 10% exploration to discover better models |
🔀 Or build your own — 19 routing strategies
All 19 strategies — mix & match per combo step:
| # | Strategy | What it does |
|---|---|---|
| 1 | priority |
First-target ordered list — drain each before the next 🥇 |
| 2 | fill-first |
Fill each target's quota fully before moving on |
| 3 | weighted |
Weighted random by per-target weight |
| 4 | round-robin |
Cycle through targets in order |
| 5 | p2c |
Power-of-two-choices random load balancing |
| 6 | least-used |
Pick the target with the lowest current load |
| 7 | random |
Uniform random pick (deduplicated) |
| 8 | strict-random |
Random without de-duplicating repeats 🎲 |
| 9 | cost-optimized |
Minimize $ per request from live catalog pricing 💸 |
| 10 | headroom |
Pick the target with the most remaining quota |
| 11 | reset-window |
Prefer the target whose quota window resets soonest |
| 12 | reset-aware |
Rank by quota reset time — short windows first 📊 |
| 13 | context-relay |
Hand off context across targets for long conversations 🧠 |
| 14 | context-optimized |
Pick the best fit for the current context size |
| 15 | cache-optimized |
Pin each reusable prompt prefix to the same account — maximize prompt-cache hits 🎯 |
| 16 | lkgp |
Last-Known-Good Path — sticky to the last successful target |
| 17 | auto |
12-factor live scoring across every connection 🤖 |
| 18 | fusion |
Fan out to a panel of models + a judge synthesizes one answer 🧬 |
| 19 | pipeline |
Chain steps — each target's output feeds the next one 🔗 |
The Auto-Combo engine scores every candidate on 12 factors (health, quota, cost, latency, success rate, freshness…) — see docs/routing/AUTO-COMBO.md.
🧱 Resilience is built in (3 independent layers)
📖 Auto-Combo Engine · Resilience Guide
🏆 What Sets OmniRoute Apart
📊 Full methodology & per-feature detail vs 9router, OpenRouter, CLIProxyAPI & LiteLLM → docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md
💚 Support OmniRoute
OmniRoute is MIT-licensed and maintained in the open. If it saves you time or money, here's how to keep it independent — pick whatever fits you. Sponsorship never affects routing priority; it buys visibility, not ranking.
| ⭐ Star the repo | Free — genuinely helps visibility | Star OmniRoute |
| 🐙 GitHub Sponsors | One-off or monthly · zero platform fee | github.com/sponsors/diegosouzapw |
| ☕ Ko-fi | Quick one-off tip, no signup for the donor | ko-fi.com/diegosouzapw |
| 🧋 Buy Me a Coffee | Small, informal gesture | buymeacoffee.com/diegosouzapw |
| 🖐 Liberapay | Recurring · non-profit · open source | liberapay.com/diegosouzapw |
| 🇧🇷 PIX (Brazil) | Instant, no fees | key & QR below |
| ₿ Crypto | BTC · ETH · USDT-TRC20 · USDC-Solana | addresses below |
🇧🇷 PIX — instant, no fees (Brazil)
Key (random): 5d865059-bc44-483a-962d-43ceb80126eb
Pix copia-e-cola:
00020101021126580014br.gov.bcb.pix01365d865059-bc44-483a-962d-43ceb80126eb5204000053039865802BR5922OMNIROUTE CONTRIBUICAO6006BRASIL62070503***630475DD
₿ Crypto — BTC · ETH · USDT-TRC20 · USDC-Solana (click to expand)
| ₿ BTC | Bitcoin (SegWit) | bc1qh00smz004sy85wyl28v77tenkt3ckl6eaep7fd |
| Ξ ETH | Ethereum (ERC20) | 0x64Cf6B68A6Ff34288e89172950a2d00102337a84 |
| ₮ USDT | Tron (TRC20) | TKAF41JpuQrHbKTnsQa9svJE2T192Hvsc2 |
| $ USDC | Solana | 2emNNZzVVWQc3FQ2wk9M6qXUQmW8AKdjjL174fXR28Tu |
⚠️ Send each coin only on the network shown — sending on the wrong network can lose the funds.
🐛 Found a bug or have feedback? Open a Discussion.
✨ What's New
Recent highlights from v3.8.20 → v3.8.49. Full history in
CHANGELOG.md.
- 🗜️ Compression hardening — default-on inflation guard, Caveman packs for DE / FR / JA + Chinese (wényán), RTK filters for Gradle & .NET. → Compression
- 💸 Honest flat-rate cost — subscription / coding-plan providers read $0 in cost analytics; budget, quota & routing keep estimating. → API Reference
- ⚖️ Quota-Share routing — split a shared account's quota fairly across pooled keys, work-conserving so idle slices are lent out. → Resilience Guide
- 🤖 One-command CLI/agent setup —
setup-*configures 12+ coding tools;omniroute launch/launch-codexare zero-config. → CLI Integrations - 🛰️ Remote mode — drive a remote OmniRoute with scoped tokens (
connect/contexts/tokens) + anantigravityOAuth helper for VPS installs. → Remote Mode - 🧭 Smarter auto-routing —
auto/<category>:<tier>combos, Fusion (model panel + judge), task-aware routing, per-request model / mode / USD-budget overrides. → Auto-Combo - 🗜️ Pluggable compression — 12 composable engines + Compression Studios: LLMLingua-2, two-tier Ultra, omniglyph, per-step fidelity gate, GCF v3.2, drag-reorder editor. → Compression
- 🕵️ Transparent MITM decrypt (TPROXY) — capture CLIs that ignore proxy env vars, with a per-SNI CA + trust-store installer. → MITM/TPROXY
- 💸 Cost telemetry everywhere —
X-OmniRoute-*cost/usage headers on every endpoint, cache-HIT savings header, per-key USD spend quotas. → API Reference - 🧠 Memory you control — off by default, opt-in int8 vector quantization + typed decay, per-request
x-omniroute-no-memory. → Memory - 🛡️ Security — prompt-injection guard on every LLM route (red-team suite), opt-in credential-masking guardrail (redacts leaked API keys/secrets in both directions), free DuckDuckGo last-resort web search, and an optional OIDC login gate for the dashboard (password login always stays available). → Guardrails
- 🖼️ New endpoints —
/v1/ocr(Mistral OCR) and/v1/audio/translations(Whisper-style) round out the media surface. → API Reference - 🎨 Image / video / audio generation — one API for media: xAI Grok Imagine & Novita AI video, ComfyUI, Freepik, Adobe Firefly, Microsoft Designer, Google Imagen, Segmind, EdgeTTS. → API Reference
- 🌍 Deployment & ops — reverse-proxy
basePath, browser-language auto-detect, per-key device tracking, root-less MITM trust, zh-TW localization. → Environment - 🤝 More providers & agents — Cursor Cloud Agent, Grok Build (xAI) with browser + OAuth login, Ollama first-class card, Claude Opus 5 & Sonnet 5, Kimi official partnership (Code/Web/Moonshot), Zed, Requesty, SenseNova, Yuanbao, Agnes AI… and a refreshed 291-provider catalog. → Providers
- 📡 Routing transparency — every response carries an
X-OmniRoute-Decisionheader naming the strategy/provider/latency that served it, a newcache-optimizedcombo strategy + Auto-CombocacheAffinityfactor route repeat requests back to the connection holding the cached prefix, and a read-only/v1/auto-combo/{channel}/candidatesendpoint exposes anauto/*channel's live candidate pool. → Auto-Combo - ⚡ Local performance & infra — one-click local Redis, Cloudflare Workers / Deno Deploy relay deployers, Bifrost & Mux as supervised embedded services. → Embedded Services
🤖 Compatible CLIs & Coding Agents
One config —
http://localhost:20128/v1— and every AI IDE or CLI runs on free & low-cost models.
 Claude Code |
 Codex CLI |
 Cline |
 Kilo Code |
 Zoo Code |
 Continue |
 Aider |
ForgeCode |
jcode |
 DeepSeek TUI |
CodeWhale |
 OpenCode |
 Factory Droid |
 Copilot CLI |
 Cursor CLI |
Smelt |
Pi |
 Grok Build |
 Hermes Agent |
 OpenClaw |
 Goose |
Open Interpreter |
Warp AI |
Agent Deck |
＋ also works with · Kiro · Command Code · Antigravity · Windsurf · AMP · any OpenAI-compatible tool
📖 Per-tool setup for all 33 tools (25 CLI Code's + 8 CLI Agents) → docs/reference/CLI-TOOLS.md · 🧩 OpenCode plugin → @omniroute/opencode-provider
🌐 291 AI Providers — 90+ Free
The most complete catalog of any open-source router: 291 providers, 90+ with a free tier, 40+ free forever.
🏢 Every major lab — through one endpoint
 OpenAI |
 Anthropic |
 Gemini |
 xAI Grok |
 DeepSeek |
 Mistral |
 Qwen |
 Meta Llama |
 Groq |
 NVIDIA |
 MiniMax |
 Cohere |
 Perplexity |
 HuggingFace |
 Together |
 Fireworks |
 Cloudflare |
 Baidu |
…and 220+ more — every icon resolves live from the dashboard's provider catalog. 📖 Provider Reference
🆓 Free Forever — $0, no card
 OpenCode Zen DeepSeek V4, Nemotron 3 No token cap |
 Kilo Code Auto-router, Tencent Hy3 Free forever |
 Requesty GPT-OSS 120B, Nemotron Free forever |
 SiliconFlow DeepSeek V3.2 / R1 Free tier |
 Z.AI GLM GLM-4.7 / 4.5-Flash Free forever |
 Baidu ERNIE ERNIE 4.0 Free forever |
 Qoder AI Qwen3-Max, Kimi-K2 Unlimited FREE |
 Pollinations GPT, Llama, Claude No key needed |
 Cloudflare AI 50+ models 10K neurons/day |
 NVIDIA NIM GLM, MiniMax ~40 RPM free |
 Cerebras GLM 4.7, GPT-OSS 1M tokens/day |
 OpenRouter :free models +$10 → higher RPM |
📖 Full machine-readable catalog → docs/reference/PROVIDER_REFERENCE.md
🖥️ Where OmniRoute Runs — Anywhere
Same app, your machine, your rules. From a global npm install to your phone via Termux.
| Platform | Install | Highlights |
|---|---|---|
| 📦 npm (global) | npm install -g omniroute | One command, any OS |
| 🐳 Docker | docker run … diegosouzapw/omniroute | Multi-arch AMD64 + ARM64 |
| 🖥️ Desktop (Electron) | npm run electron:build | Native window + system tray — Windows / macOS / Linux |
| 💪 ARM | native arm64 | Raspberry Pi, ARM servers, Apple Silicon |
| 📱 Android (Termux) | pkg install nodejs && npx -y omniroute | Runs on your phone, 24/7, no root |
| 📲 PWA | "Add to Home Screen" | Fullscreen, offline, installable from browser |
| 🧩 OpenCode plugin | @omniroute/opencode-provider | Native OpenCode integration |
| 🛠️ From source | npm install && npm run dev | Hack on it, contribute |
📖 Docker Guide · Desktop · Termux · PWA · OpenCode
🔒 Private & Local-First
📖 Authorization · Guardrails · Compliance
🔌 Full CLI + A2A & MCP
Beyond the server, OmniRoute is a full command-line cockpit with 80+ commands, plus open agent protocols so an AI agent can drive it on its own.
⌨️ A real CLI (not just start)
omniroute # serve gateway + dashboard (port 20128)
omniroute chat # interactive TUI chat client (slash: /model /combo /skill /memory)
omniroute setup # guided first-run wizard
omniroute doctor # diagnose providers, ports, native deps
🛰️ Remote mode — run the CLI here, OmniRoute on a VPS
OmniRoute on a server? Drive it from your laptop with the same CLI. Log in once with a scoped access token; every command then targets the remote.
omniroute connect 192.168.0.15 # password → scoped token, saved as a context
omniroute models list # ← runs against the REMOTE server
omniroute configure codex # ← picks a remote model, writes a local Codex profile
omniroute tokens create --name ci --scope read # mint narrower tokens for other machines
omniroute contexts use default # ← switch back to the local server
Tokens are scoped read / write / admin; process-spawning routes stay loopback-only.
📖 Remote Mode
🤝 Connect an agent — and it controls OmniRoute itself
Expose OmniRoute over MCP, A2A, a REST API, webhooks or a remote CLI — any capable agent (or your own code) gets the keys to the whole gateway: routing, providers, combos, cache, compression, memory — autonomously. HTTP endpoints below are served under http://localhost:20128.
| Interface | Endpoint / command | Use it for |
|---|---|---|
| 🧰 MCP (stdio) | omniroute --mcp | Plug into Claude Desktop, Cursor, any MCP client |
| 🌊 MCP (HTTP) | /api/mcp/stream | Remote MCP — 104 tools, 31 scopes, full audit trail |
| 📡 MCP (SSE) | /api/mcp/sse | Streaming MCP transport |
| 🤝 A2A | /.well-known/agent.json | Agent-to-agent, JSON-RPC 2.0 + SSE, 6 skills |
| 🌐 REST API | /v1/* | OpenAI-compatible — chat, embeddings, images, audio, OCR |
| 🔔 Webhooks | /api/webhooks | Push events (usage, quota, errors, routing) to your URL |
| 🛰️ Remote CLI | omniroute connect | Drive a remote instance with scoped access tokens |
# Give Claude Code the full OmniRoute toolset over MCP:
claude mcp add-server omniroute --type http --url http://localhost:20128/api/mcp/stream
📖 MCP Server · A2A Server · Agent Protocols
🗜️ Save 15–95% Tokens — Automatically
📖 How it works — pipeline, architecture & savings math
Default stacked combo runs RTK → Caveman. When both act on the same tool/context payload, savings compound:
combined = 1 − (1 − RTK) × (1 − Caveman_input)
average = 1 − (1 − 0.80) × (1 − 0.46) = 89.2%
range = 78.4 – 94.6%
Code blocks, URLs, JSON and structured data are always protected by the preservation engine.
Why use many tokens when few tokens do the trick? Every request passes through OmniRoute's compression pipeline transparently — no client changes. It's now a stack of 12 composable engines that run in order and mix & match per routing combo — building on ideas from RTK, Caveman (⭐ 90K+), LLMLingua-2, and Troglodita (PT-BR).
🧱 The 12-engine stack
Engines run in pipeline order; each is independently toggleable and configurable per combo:
| # | Engine | What it does |
|---|---|---|
| 1 | Session-Dedup | Drops content repeated across turns (content-addressed, cross-turn) |
| 2 | CCR | Archives large blocks behind retrieve markers, fetched on demand |
| 3 | Lite | Whitespace + image-URL trimming (latency-light baseline) |
| 4 | RTK | Smart tool-result filtering, dedup & truncation (command-aware) |
| 5 | Responses Tool Output | Lossless-first JSON + bounded diagnostic compression for shell/patch/search/build outputs (Responses API) |
| 6 | Headroom | Lossless tabular compaction of JSON arrays (~30%) via a vendored GCF codec |
| 7 | Relevance | Extractive sentence scoring against the last user query |
| 8 | Caveman | Rule-based prose compression (~65–75% on output) |
| 9 | Aggressive | Summarization + progressive aging of old turns |
| 10 | LLMLingua-2 | ML semantic pruning via MobileBERT ONNX — code-safe, async |
| 11 | Ultra | Heuristic token pruning with an optional small-model (SLM) tier |
| 12 | OmniGlyph | Experimental context-as-image encoding routed to Claude Fable 5 (most aggressive; opt-in) |
Code blocks, URLs and structured data are always preserved byte-perfect. One-click presets combine the engines:
| Mode | Savings | Best for |
|---|---|---|
| 🪶 Lite | ~15% | Always-on safe default |
| 🪨 Standard (Caveman) | ~30% | Daily coding |
| ⚡ Aggressive | ~50% | Long tool-heavy sessions |
| 🔥 Ultra | ~75% | Maximum savings |
| 🧰 RTK | 60–90% | Shell/test/build/git output |
| 🔗 Stacked (RTK → Caveman) | 78–95% | Mixed prompts + tool logs |
Real example — Standard mode:
Before (69 tokens): "The reason your React component is re-rendering is likely because you're creating a new object reference on each render cycle. When you pass an inline object as a prop, React's shallow comparison sees it as a different object every time, which triggers a re-render. I would recommend using useMemo to memoize the object."
After (19 tokens): "New object ref each render. Inline object prop = new ref = re-render. Wrap in useMemo."
Same answer. 72% fewer tokens. Zero accuracy loss. ✅
PT-BR example — Troglodita mode:
Antes (42 tokens): "O problema é que o componente está re-renderizando porque uma nova referência de objeto está sendo criada em cada ciclo de renderização. Eu recomendaria usar useMemo."
Depois (12 tokens): "Re-render: ref nova cada ciclo (objeto inline recriado). Usar
useMemo."Mesma resposta. ~70% menos tokens. Precisão técnica intacta. ✅
🎚️ Beyond the engines — output styles, the adaptive dial & per-request control
The 12 engines above shrink what goes in. Three more layers shape how, when, and what comes out:
- 🪄 Output Styles (output-axis steering) — inject deterministic, cache-safe response-shaping instructions; combinable, each at
lite/full/ultraintensity. Adding a style is a one-line registry entry:- Terse prose — drop filler / articles / hedging; keep technical substance exact.
- Less code — "lazy senior dev" YAGNI: smallest working change, no unrequested scaffolding.
- Terse CJK (文言) — classical-Chinese ultra-terse style (locale-gated to
zh).
- 🎯 Adaptive context-budget (the dial) — instead of one on/off token threshold, escalate the cheapest, most-lossless engines only as far as needed to fit the model's context window. Policy:
reserve-output(default, model-aware) ·percentage·absolute. Mode:floor(guarantee fit) ·replace-autotrigger(your explicit choice wins) ·off(legacy threshold). - 🎛️ Where compression is decided (precedence, high → low) — per-request
x-omniroute-compressionheader › routing-combo override › active named profile › adaptive / auto-trigger › panel default › off. The applied plan echoes back in theX-OmniRoute-Compression: <mode>; source=<source>response header.
Auto-trigger by token threshold, flip on the adaptive dial, pin a named profile, set a one-off per request, or assign a pipeline per routing combo — whichever fits the workload. An opt-in offline eval harness (npm run eval:compression) scores fidelity vs. savings on a pinned corpus before you promote a change.
📖 COMPRESSION_GUIDE.md · RTK_COMPRESSION.md · COMPRESSION_ENGINES.md
⚡ Quick Start
1) Install & run
npm install -g omniroute
omniroute
💡 See
npm warn ERESOLVEor peer-dep warnings? They're harmless.
Dashboard at http://localhost:20128 · API at http://localhost:20128/v1.
2) Connect a FREE provider (no signup)
Dashboard → Providers → connect Kiro AI (free Claude, ~50 credits/month per account) or OpenCode Free (no auth) → done.
3) Point your coding tool
Base URL: http://localhost:20128/v1
API Key: [copy from Dashboard → Endpoints]
Model: auto (zero-config smart routing — or any provider/model)
4) Verify it's working
curl http://localhost:20128/v1/models -H "Authorization: Bearer YOUR_KEY"
You should see your connected models listed. 🎉 That's it — start coding, and OmniRoute auto-routes & falls back for you.
If your client cannot send custom headers, OmniRoute also exposes tokenized compatibility aliases:
OpenAI catalog: http://localhost:20128/vscode/YOUR_KEY/
OpenAI models: http://localhost:20128/vscode/YOUR_KEY/models
OpenAI chat: http://localhost:20128/vscode/YOUR_KEY/chat/completions
OpenAI responses: http://localhost:20128/vscode/YOUR_KEY/responses
Ollama chat: http://localhost:20128/vscode/YOUR_KEY/api/chat
Ollama tags: http://localhost:20128/vscode/YOUR_KEY/api/tags
Use these only for clients that cannot attach Authorization: Bearer .... Header auth remains the preferred mode.
📦 More install methods — Docker, source, pnpm, Arch
🐳 Docker
docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \
-p 127.0.0.1:20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest
🛠️ From source
cp .env.example .env && npm install
PORT=20128 npm run dev
📦 pnpm
pnpm add -g omniroute@latest --allow-build=better-sqlite3 --allow-build=@swc/core && omniroute
🐧 Arch Linux (AUR)
yay -S omniroute-bin && systemctl --user enable --now omniroute.service
🔧 Nix (Flake)
# Using Nix flakes
nix develop
npm run dev
# Or using devbox
devbox run npm run dev
📖 Docker Guide — Compose profiles, Caddy HTTPS, Cloudflare tunnels.
🦭 Podman
# 1. Prepare the bind-mounted data directory
mkdir -p data
# 2. Linux + local rootless Podman only (never a remote Podman Machine client):
podman unshare chown 1000:1000 ./data
# 3. Set the runtime hint, build the local Compose image, and start
echo "CONTAINER_HOST=podman" >> .env
podman compose --profile base up -d --build
On macOS or Windows, Podman uses a remote Podman Machine: skip podman unshare and
follow the topology-specific data directory guidance.
📖 Podman Guide — Compose builds, Podman Machine, and Linux/systemd Quadlet setup.
⚡ Faster / leaner install (skip the native build)
The native SQLite engine (better-sqlite3) is an optional dependency, so a global
install never blocks on compiling from source: it uses a prebuilt binary when one matches
your platform/Node, and otherwise falls back transparently to a pure-JS engine
(node:sqlite on Node 22+, else the bundled sql.js WASM) — no build tools required.
To skip the post-install native warm-up entirely (CI, headless, or slow machines):
OMNIROUTE_SKIP_POSTINSTALL=1 npm install -g omniroute # CI=1 also skips it
For the fastest installs prefer pnpm (content-addressed store + hard links — see above).
For a dashboard-free, headless runtime use the Docker base profile (above) or the
Termux guide. The CLI and the web dashboard are served by the
same process on one port, so there is no separate CLI-only package today.
🎬 OmniRoute in Action
 🇧🇷 Português Guia completo |
 🇺🇸 English Complete walkthrough |
 🇷🇺 Русский Полное руководство |
🎬 Made a video about OmniRoute? Open an issue or discussion with the link — we'll feature it here.
📧 Community & Help
Everything in one place — follow the maintainer, chat with the community, or open an issue.
| Channel | Where / how |
|---|---|
| 💼 LinkedIn — follow the maintainer | linkedin.com/in/diegosouzapw |
| 🐙 GitHub — follow for releases & tips | @diegosouzapw |
| 💬 Discord | discord.gg/U47eFqAXCn |
| ✈️ Telegram | t.me/omnirouteOficial |
| 🟢 WhatsApp — 🌍 Global | join the group |
| 🟢 WhatsApp — 🇧🇷 Brasil | entrar no grupo |
| 🌍 Website | omniroute.online |
| 📦 Source code | github.com/diegosouzapw/OmniRoute |
| 🐛 Report a bug | open an issue — attach npm run system-info output |
| 🤝 Contribute | CONTRIBUTING.md · Branching & Release Model · pick a good first issue |
| 💚 Support the project | Ways to support ↑ · GitHub Sponsors |
🛠️ Tech Stack
| Layer | Technology |
|---|---|
| Runtime | Node.js 22.x / 24.x LTS — >=22.22.2 <23 || >=24.0.0 <27 |
| Language | TypeScript 6.0 — 100% TypeScript across src/ and open-sse/ (zero any in core since v2.0) |
| Framework | Next.js 16 + React 19 + Tailwind CSS 4 |
| Database | better-sqlite3 (SQLite, WAL journaling) + LowDB (JSON legacy) — 95 domain modules, 110 migrations |
| Memory | SQLite FTS5 full-text + int8-quantized vector embeddings, typed decay |
| Schemas | Zod 4 — MCP tool I/O validation + API contracts |
| Protocols | MCP (stdio / HTTP / SSE) + A2A v0.3 (JSON-RPC 2.0 + SSE) |
| Streaming | Server-Sent Events (SSE) + WebSocket bridge (/v1/ws) |
| Compression | 12-engine pipeline — RTK, Caveman, LLMLingua-2 (MobileBERT ONNX), GCF, OmniGlyph |
| Auth & security | OAuth 2.0 (PKCE) + JWT + API Keys + MCP scoped auth · AES-256-GCM at rest · DOMPurify |
| Stealth | wreq-js — JA3 / JA4 TLS fingerprint impersonation, 3-level proxy |
| Resilience | Circuit breaker, exponential backoff, anti-thundering-herd, auto-combo self-healing |
| Logging | pino — structured JSON logs with request context |
| Testing | Node.js test runner + Vitest — 25,000+ test cases across 3,300+ files (unit, integration, E2E, security, ecosystem) |
| Platforms | Desktop (Electron) · Android (Termux) · PWA (any browser) |
| CI/CD | GitHub Actions — auto npm publish + Docker Hub on release |
| Links | Website · npm · Docker Hub |
📖 Documentation
📘 Getting Started
| Document | Description |
|---|---|
| User Guide | Providers, combos, CLI integration, deployment |
| Setup Guide | Full install methods, CLI tool configs, protocol setup, timeout tuning |
| CLI Tools Guide | Per-tool setup for Claude Code, Codex, Cursor, Cline, OpenClaw, Kilo, Copilot |
| Remote Mode | Drive a remote OmniRoute (VPS) from your laptop CLI via scoped access tokens |
| Claude Code Config | Point Claude Code at OmniRoute (local/remote) with launch + per-model profiles |
| Quick Start | 3-step install → connect → configure |
🔧 Operations & Deployment
| Document | Description |
|---|---|
| Docker Guide | Docker run, Compose profiles, Caddy HTTPS, tunnels, image tags |
| Podman Guide | Quadlet systemd integration, podman-compose, SELinux |
| VM Deployment | Complete guide: VM + nginx + Cloudflare setup |
| Fly.io Deployment | Deploy to Fly.io with persistent storage |
| Termux Guide | Run OmniRoute on Android via Termux |
| PWA Guide | Progressive Web App install, caching, architecture |
| Uninstall Guide | Clean removal for all install methods |
| Environment Config | Complete .env variables and references |
🧠 Features & Architecture
| Document | Description |
|---|---|
| Architecture | System architecture, data flow, and internals |
| Compression Guide | 7-option pipeline: off / lite / standard / aggressive / ultra / RTK / stacked |
| RTK Compression | Command-output compression, filters, trust, verify, raw-output recovery |
| Compression Engines | Caveman, RTK, stacked pipelines, dashboard/API/MCP surfaces |
| Compression Rules Format | JSON rule-pack schemas for Caveman and RTK filters |
| Compression Language Packs | Language detection and Caveman rule-pack authoring |
| Resilience Guide | Circuit breakers, cooldowns, queue, anti-thundering herd, TLS spoofing |
| Auto-Combo Engine | 12-factor scoring, mode packs, self-healing |
| Proxy Guide | 3-level proxy system, 1proxy marketplace, registry CRUD |
| Free Tiers | 25+ free API providers consolidated directory |
| Features Gallery | Visual dashboard tour with screenshots |
| Codebase Documentation | Beginner-friendly codebase walkthrough |
🤖 Protocols & APIs
| Document | Description |
|---|---|
| API Reference | All endpoints with examples |
| OpenAPI Spec | OpenAPI 3.0 specification |
| MCP Server | 104 MCP tools, IDE configs, Python/TS/Go clients |
| MCP Server Guide | MCP installation, transports, and tool reference |
| A2A Server | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
| A2A Server Guide | A2A agent card, tasks, skills, and streaming |
📋 Project & Quality
| Document | Description |
|---|---|
| Contributing | Development setup and guidelines |
| Branching & Release Model | Where PRs target (release/*), what main and tags mean |
| Changelog | Full per-version release history |
| Security Policy | Vulnerability reporting and security practices |
| i18n Guide | 40+ language support, translation workflow, RTL |
| Release Checklist | Pre-release validation steps |
| Coverage Plan | Test coverage strategy and 25,000+ test suite |
⭐ Top Contributors
OmniRoute is shaped by a passionate open-source community. These individuals have made exceptional contributions that directly impact the quality, stability, and reach of the project. Thank you.
 oyi77 🥇 213 commits • +114K lines Analytics engine, SQL aggregations, proxy marketplace, test coverage |
 R.D. & Randi 🥈 108 commits • +38K lines Endpoints page, tunnel integrations, Docker workflows, A2A status, compression UI |
 Chris Staley 🥉 70 commits • +1.8K lines SSE stream hardening, Responses API, Gemini pagination, test regression fixes |
 zenobit 🏅 62 commits • +22K lines CI/CD pipeline, i18n for 33 languages, Void Linux package, platform fixes |
 Jan Leon 🏅 58 commits • +22K lines Reasoning-effort routing, proxy controls, quota visibility, Live Zone compression |
 backryun 🏅 53 commits • +70K lines Provider catalog curation — Perplexity, Kimi, Cerebras, Copilot, LMArena refreshes |
 Chirag Singhal 🏅 46 commits • +4.8K lines Error sanitization, MITM prefill fix, fusion judge, breaker/429 correctness |
 kfiramar 🏅 38 commits • +1.7K lines Codex websocket + passthrough, auth/onboarding, Electron hardening, DB migrations |
 Benson K B 🏅 28 commits • +9.2K lines Electron desktop app, auto-updater, release build workflows, cross-platform CI |
 Hernan J. Ardila 🏅 25 commits • +174K lines Zero-latency combos, vision-bridge auto-routing, catalog context-length, resilience 429 hints |
🙏 These contributors' features, bug fixes, and infrastructure improvements are a core part of what makes OmniRoute reliable and feature-rich. Every pull request, every test case, and every i18n translation file matters. Open source is built by people like them.
💖 Sponsors
A heartfelt thank-you to the people who fund OmniRoute out of their own pocket — every contribution keeps the project free, independent and moving.
 Prof. Igor Morais 💛 Sponsor |
 longtao 💛 Sponsor |
… and others who prefer to stay private 💛
💖 Become a sponsor → — every dollar keeps OmniRoute free and independent.
👥 500+ Contributors
How to Contribute
- Fork the repository
- Branch from the active
release/vX.Y.Ztip (notmain) — see Branching & Release Model - Create your feature branch (
git checkout -b feat/amazing-feature) - Commit your changes (
git commit -m 'feat: add amazing feature') - Push to the branch (
git push origin feat/amazing-feature) - Open a Pull Request with base = that
release/vX.Y.Zbranch
See CONTRIBUTING.md for detailed guidelines.
Releasing a New Version
# Create a release — npm publish happens automatically
gh release create v3.8.2 --title "v3.8.2" --generate-notes
📊 Stars
🌍 StarMapper
🙏 Acknowledgments
OmniRoute stands on the shoulders of giants. It started as a fork of 9router and a TypeScript port of the Go project CLIProxyAPI — and from there, every subsystem below was inspired by an open-source project that got there first. Each one shaped a concrete piece of OmniRoute. This is our thank-you to all of them. 🙏
⭐ star counts as of July 2026 — go give these projects a star.
🧬 Lineage & gateway
| Project | ⭐ | How it inspired OmniRoute |
|---|---|---|
| 9router | 22.7k | The original project this fork is built on — extended here with multi-modal APIs and a full TypeScript rewrite. |
| CLIProxyAPI | 43.6k | The Go implementation that inspired this JavaScript / TypeScript port. |
| LiteLLM | 54.0k | The AI gateway whose public pricing dataset feeds our cost-tracking sync and whose provider-normalization model informed our routing. |
🗜️ Context & token compression — engines
| Project | ⭐ | How it inspired OmniRoute |
|---|---|---|
| Caveman | 90.8k | The viral "why use many token when few token do trick" project — its caveman-speak philosophy powers our standard compression mode and 30+ filler/condensation rules. |
| RTK – Rust Token Killer | 71.8k | High-performance command-output compression — inspired our RTK engine, JSON filter DSL, raw-output recovery and the stacked RTK → Caveman pipeline. |
| headroom | 60.1k | Reversible context-compression (SmartCrusher) — inspired our headroom engine and the ccr retrieve-marker pattern. |
| LLMLingua | 6.5k | Prompt-compression research (LLMLingua / LLMLingua-2) — inspired our async, code-safe, fail-open llmlingua engine. |
| llmlingua-2-js | 30 | The JS/ONNX port (MobileBERT / XLM-RoBERTa) used as the worker-thread backend for our LLMLingua engine. |
| Troglodita | 26 | PT-BR token compression — powers our pt-BR language pack: pleonasm reduction and filler removal tuned for Brazilian-Portuguese grammar. |
| ponytail | 86.0k | The viral "lazy senior dev" YAGNI-coder skill — inspired our less-code Output Style: smallest-working-change steering that cuts _generated_ code (the output-axis sibling to Caveman's terse prose). |
🧩 Compact formats, token research & code-aware tooling
| Project | ⭐ | How it inspired OmniRoute |
|---|---|---|
| TOON | 24.9k | Token-Oriented Object Notation — its columnar, header-plus-rows model shaped our tabular compaction stage. |
| GCF – Graph Compact Format | 22 | First inspired our tabular compaction stage; now its zero-dependency, lossless generic-profile encoder is vendored directly as the Headroom codec (MIT, SPDX-marked), current with GCF spec v3.2. |
| token-optimizer-mcp | 444 | Brotli/SQLite cache + per-session context-delta — inspired our session-dedup engine. |
| token-savior | 1.1k | Bash-output compaction + MCP profiles — inspired our compression bail-out discipline and MCP tool-manifest reduction. |
| token-saver | 117 | Content-aware, per-file-type output compression with failure-aware bail-out — validated our per-type dispatch and minimum-gain skip. |
| token-optimizer | 1.7k | "Find the ghost tokens" — its offload + recoverable-handle pattern informed our CCR offload thinking. |
| TokenMizer | 16 | A session-graph + cross-turn line-dedup blueprint that informed our session-dedup design. |
| OmniCompress | 3 | Rust columnar-JSON + content-addressed retrieve + cross-message dedup — validated our headroom/ccr/session-dedup engine design and the cache-stable "compressed form is position-independent" invariant. |
| mcp-compressor | 98 | MCP tool-schema/description compression — informed our MCP tool-manifest cardinality reduction. |
| RepoMapper | 187 | Aider-style repo-map ranking — informed our repo-map / retrieval-ranking exploration. |
| quiet-shell-mcp | 4 | Declarative shell-output reduction over MCP — validated our declarative bash-output compaction. |
| ts-morph | 6.1k | TypeScript Compiler API toolkit — inspired our parser-based comment removal that preserves string, template and regex literals. |
🧠 Memory & RAG
| Project | ⭐ | How it inspired OmniRoute |
|---|---|---|
| Mem0 | 61.2k | Universal memory layer — its proxy-as-write/read-boundary model shaped our memory architecture. |
| Letta (MemGPT) | 23.9k | Stateful agents with tiered memory — inspired our Context Control & Recovery (CCR) tiered model. |
| WFGY | 1.8k | The ProblemMap taxonomy of 16 recurring RAG/LLM failure modes — the shared vocabulary in our troubleshooting guide. |
🛰️ Traffic inspection, MITM & transparent proxy
| Project | ⭐ | How it inspired OmniRoute |
|---|---|---|
| llm-interceptor | 49 | MITM interception/analysis of coding-assistant ↔ LLM traffic — our Traffic Inspector ports its SSE merge, conversation normalization, host passthrough and secret masking (MIT). |
| ProxyBridge | 5.5k | Transparent per-process proxy routing — inspired our crash-safe MITM teardown, socket idle-timeouts, /proc process attribution and TPROXY capture. |
📚 Model data, observability & UI
| Project | ⭐ | How it inspired OmniRoute |
|---|---|---|
| models.dev | 6.0k | Open database of AI model specs, pricing and capabilities — synced natively into our model catalog. |
| React Flow / xyflow | 37.7k | The node-based graph library powering our real-time Compression Studio and Combo/Routing Studio. |
| LangGraph | 37.6k | LangGraph Studio's live workflow-graph visualization inspired our Studios' real-time cascade view. |
| Langfuse | 31.4k | Its trace → span → generation observability model shaped our Compression Studio waterfall. |
| Kiali | 3.6k | Istio service-mesh observability — inspired our circuit-breaker badges and error-edge visuals in the Routing/Combo Studio. |
| lobe-icons | 2.2k | AI/LLM brand logos that render the provider icons across our dashboard. |
🛡️ Security
| Project | ⭐ | How it inspired OmniRoute |
|---|---|---|
| awesome-secure-defaults | 710 | A curated list of secure-by-default libraries that guides our security choices (Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink). |
🧭 Complementary tools
| Project | ⭐ | How it inspired OmniRoute |
|---|
📄 License
MIT License - see LICENSE for details.
⬆ Back to top · Built with ❤️ for the open-source AI community.
OmniRoute v3.8.49 · Node ≥22.22.2 · MIT License · omniroute.online