mirror of https://github.com/diegosouzapw/OmniRoute.git synced 2026-08-08 08:12:20 +03:00

Files

Diego Rodrigues de Sa e Souza c40d4b17ee fix(ci): clear the NEW base-reds from the 08-06 merge batch (migration collision #2 + broken import) (#9688 )

* test(base): realign six suites with contracts that #9100/#8990/#9009 deliberately changed

Continuing the base-red drain — every one of these reproduces on the pure tip.

- tests/snapshots/provider/translate-path.json: regenerated via UPDATE_GOLDEN=1.
  The diff is ADDITION-ONLY — the unorouter block from #9009; no existing
  provider entry changed. 3/3.
- tests/unit/provider-models-route.test.ts: ff012ff420 added onboardUser as a
  bootstrap fallback next to loadCodeAssist; the mock now excludes it from the
  discovery-URL ledger like it already excluded loadCodeAssist, otherwise it
  consumed the injected 503 and the retry assertion misfired. 59/59.
- tests/unit/responses-commentary-passthrough-6199.test.ts: #8990 (c996dc93c2)
  deliberately preserves `tools` on the TERMINAL response.completed snapshot
  (Codex CLI rebuilds its tool list from it); the assertion now pins the echoed
  tools instead of their absence. Still stripped on created/in_progress. 7/7.
- tests/unit/vision-compression-authoritative-capability-7237.test.ts:
  68cb678780 added the 'gpt-5' fragment, so the heuristic-vs-spec DRIFT this
  suite documented no longer exists; the cases now guard the agreement, keep a
  conservative-for-unknown-ids probe, and reproduce the strip-bug shape with an
  explicit false instead of deriving it. 4/4.
- tests/unit/provider-limits-proxy-fail-closed.test.ts +
  tests/unit/image-generation-route.test.ts: #9100 made the proxy reachability
  probe NON-BLOCKING (optimistic dispatch; the probe aborts only in-flight
  requests — its own t14 sibling was updated to this exact pattern). Instant
  mocks therefore won the race and the PROXY_UNREACHABLE 503 became unobservable
  (a success or a generic 502). The mocks now stay in flight (never-resolving,
  so the aborted continuation cannot reach the restored real fetch), and the
  fail-closed proof is the settled rejection itself plus zero egress AFTER the
  fast-fail. Production fail-closed semantics are unchanged — the proxy dispatch
  path still throws; only the mock timing was stale. 3/3 and 20/20.

Refs #9298

* fix(guardrails): forward the router deps seam through callVisionModel

tests/unit/guardrails/vision-bridge-sse-and-reasoning.test.ts was 7/7 red on any
clean box (CI shard 3/4): callVisionModel() called getBestVisionModel()/
getFallbackModels() WITHOUT the routers' existing VisionBridgeRouterDeps seam,
so the credential check always hit the live connections DB — no vision-capable
connection meant 'No vision-capable provider connected' before the mocked fetch
was ever reached, and on a dev box auto-selection could swap the fixed model
under the assertions.

The routers already accepted deps; only the forwarding was missing. Added the
optional 5th param (backward compatible — the sole production caller,
visionBridge.ts, injects its own callVisionModel and is unaffected) and the
suite now pins selection with hasUsableCredentials: async () => null
(indeterminate → the fixed model is honored, DB untouched). 7/7.

Sibling suites re-run green: vision-bridge-callmodel 2/2, visionBridge 25/25,
visionBridgeHelpers.callVisionModel 8/8, visionBridgeRouter 10/10,
vision-bridge-cc-no-reroute 8/8.

Refs #9298

* fix(db,combo): clear the NEW base-reds the 08-06 merge batch introduced

The tip moved while the first sweep PR (#9600) was in review, and three fresh
base-reds landed with it — same classes as before, all reproduced on the pure
tip 9995bc4893:

1. ANOTHER migration collision: #9061 shipped 134_ccr_blocks.sql onto the slot
   134_proxy_logs_egress_ip.sql (#9291) has held since 08-04. getMigrationFiles()
   throws on collision, so every DB-touching test died at bootstrap again.
   Renumbered to 139 (next free slot). No retroactive guard needed this time:
   both statements are IF NOT EXISTS, and no DB can have applied it as 134 —
   the runner refused to run at all while the collision existed.
2. BROKEN IMPORT killing the combo module graph: #8894 imported
   preferAntigravityConnectionsWithStoredProject from
   ../antigravityProjectPersistence.ts — a module that exists NOWHERE in the
   repo (it came from an unmerged sibling branch). Anything importing
   quotaStrategies.ts died with ERR_MODULE_NOT_FOUND. Implemented the helper in
   the real persistence module (antigravityProjectPersist.ts, #8491) with the
   semantics the call site needs — prefer connections that already carry a
   stored projectId, never emptying the pool — and pointed the import there.
   New regression suite tests/unit/antigravity-prefer-stored-project.test.ts
   (5/5), including an import-graph probe that reproduces the break shape.
3. Sibling-test drift from #9106 (gemini-3.1-pro-high now user-callable): its
   own suites were updated but provider-models-route.test.ts was not. Expected
   discovery list realigned; testFrozen 1784->1787 justified in the baseline
   (irreducible +2 after comment compression; gate counts split-newlines).

Also regenerated tests/snapshots/provider/translate-path.json — addition-only:
devin-cli-agentic, raycast, regolo (today's provider merges), zero removals.

image-generation-route 20/20 (was import-dead), provider-models-route 59/59,
antigravity-prefer-stored-project 5/5, provider-translate-path-golden 3/3.

Refs #9298

* fix(changelog): convert the #9415 fragment to the required bullet shape

Another base-red from the 08-06 batch: bd4407cb64 landed
changelog.d/features/9415-newapi-sub2api-aggregator-balance.md as YAML
frontmatter + a prose paragraph. Every other fragment in changelog.d/ is a
single markdown bullet, and both consumers enforce that —
scripts/check/check-changelog-integrity.mjs:97 and the release aggregator
(scripts/release/aggregate-changelog.mjs:57) reject anything that does not
start with '- ', so 'Merge integrity (changelog + generated skills)' was red
for every PR targeting the release branch.

Rewritten as a bullet with the standard issue link, preserving the feature
description (aggregator gateway toggle, /api/user/self balance read, dashboard
badge, quota-preflight skip, NEWAPI_AGGREGATOR_BALANCE flag default off,
quotaPerUnit override). Swept the rest of changelog.d/ — this was the only
malformed fragment.

check:changelog-integrity OK.

Refs #9298

* fix(types,docs): clear the 5 typecheck errors and the fabricated env vars on the base

Third pass over the base-reds, from the 2026-08-06T22:51Z verdict on #9298 —
it reported "Typecheck (core)" with only the FIRST error; there are five, all on
the pure tip 9995bc4893. Two are real production defects.

**Real bugs**

- open-sse/services/compression/engines/ccr/index.ts:295 called
  enforceGlobalBudget(entry.bytes) against an (owner, bytes) signature. The
  `bytes` argument arrived undefined, so `ccrTotalBytes + undefined` is NaN,
  `NaN > MAX` is false (the eviction loop exits immediately) and `NaN <= MAX` is
  false (the re-admit is refused). The #9061 durable tier therefore NEVER
  repopulated its in-memory map: every retrieve after a restart or an eviction
  re-read from SQLite forever, and evictions could not prefer the owning
  principal. Fixed and pinned by a new case in
  tests/unit/ccr-durable-store-9061.test.ts (11/11) — verified failing against
  the buggy call and passing against the fix.
- open-sse/services/combo/fusionPanel.ts:54 read `step.model` after #8894
  widened ComboStep with ComboProviderWildcardStep (which carries modelPattern,
  not model), so a wildcard step in a fusion panel pushed `undefined` onto the
  panel. Now resolved through getComboModelString(), which already handles every
  step shape and returns null for the ones without a concrete model id.

**Type-only**

- accountSemaphore.ts:203 — isBypassed() returns a plain boolean and cannot
  narrow `number | null` (an `x is null | undefined` predicate would be unsound:
  0 bypasses too). Added resolveActiveCap(), the narrowing companion isBypassed
  is now defined in terms of; the acquire path uses the narrowed value.
- comboStructure.ts:140 — same #8894 widening: `prompt` only exists on a model
  step, so it is now read under a kind check.
- firecrawlQuotaFetcher.ts:136 — the function returns full FirecrawlQuota
  objects but was annotated Promise<QuotaInfo | null>, which made the
  custom-base literal an excess-property error. Widened to the accurate type
  (FirecrawlQuota extends QuotaInfo, so callers are unaffected).

**Fabricated docs (the "Docs sync + fabricated-docs (strict)" HARD failure)**

docs/ops/VM_DEPLOYMENT_GUIDE.md recommended OMNIROUTE_MAX_POOL_SIZE and
OMNIROUTE_DB_POOL_SIZE (#9471). Neither is read anywhere in the codebase.
Replaced with the two knobs that do exist and are already documented in
ENVIRONMENT.md: OMNIROUTE_MEMORY_MB and OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT.

typecheck:core 5 errors -> 0. check:fabricated-docs + check:env-doc-sync OK.
accountSemaphore 6/6, ccr-durable-store 11/11, ccr-protocol 9/9,
combo-fusion-strategy 10/10, combo-fusion-comboref 5/5, combo-fusion-warn 4/4,
firecrawl-executor 7/7, executor-firecrawl-fetch 4/4.

Refs #9298

* fix(tests): type the #3440 vertex helpers instead of `any` (the 3 base ESLint errors)

The "ESLint errors: 3 error(s)" HARD failure in the #9298 verdict is
tests/unit/vertex-functioncall-id-3440.test.ts lines 32/41/50: the three
find*(result: any) walkers. `@typescript-eslint/no-explicit-any` is an ERROR in
tests/ (and open-sse/) since #6218, and this file landed on 2026-08-04 without a
suppressions entry, so every run of `lint:json --max-warnings 0` failed. That
step prints nothing on failure, which is why the gate looked like a silent
crash across the open PRs.

Replaced with a GeminiRequestLike interface describing exactly what the three
walkers traverse (contents[].parts[]), so the assertions keep their meaning and
nothing is cast away.

eslint on the file: clean. Suite: 6/6.

Refs #9298

* docs(proxy): use an RFC 5737 documentation IP in the proxy examples

The #9298 verdict headlines its docs failure with
`L810 [stale-version] 1.2.3: const removed = await failOneproxyProxy("1.2.3.4", 8080)`.
That is a false positive: check-deprecated-versions.mjs matches
`/\bv?[12]\.\d+\.\d+\b/`, and the example IP literal 1.2.3.4 contains "1.2.3".

Swapped both occurrences in PROXY_GUIDE.md (and its pl mirror) for 203.0.113.7,
from the RFC 5737 documentation range that exists precisely for examples — it
cannot collide with a version pattern and is the correct thing to print in docs
regardless. Drift count 64 -> 62; no gate threshold was touched.

The gate that actually FAILED under "Docs sync + fabricated-docs (strict)" was
check:fabricated-docs (the invented pool env vars), fixed in the previous
commit; this one removes the misleading line the verdict quotes.

* test(base): allowlist probeUtils and realign the #7849 suite to the replacement bound

Two more base-reds, both visible only after the migration collision stopped
killing the shards.

**check-db-rules — src/lib/db/probeUtils.ts not classified**

#9541 added probeUtils.ts (transient-error retry for the SQLite corruption
probe). It is imported ONLY by src/lib/db/core.ts, exactly like its siblings
schemaColumns / optimizationSettings / providerNodeSelect, so re-exporting it
through localDb.ts would push callers toward the barrel-import anti-pattern the
gate exists to prevent. Added to INTENTIONALLY_INTERNAL with that rationale.
check-db-rules 22/22, check:db-rules exit 0.

**session-dedup-memory-7849 — pinned a mechanism that was replaced**

7f36b192f0 (#7855 follow-up) swapped the shared "suffix work budget" for the
MAX_SUFFIX_STARTS / MAX_TOTAL_BLOCK_BYTES guards and deleted both the budget and
its SUFFIX_WORK_BUDGET_WARNING string. It updated session-dedup.test.ts but not
this sibling, so 3 of its 4 cases asserted a warning that can no longer be
emitted.

Realigned to the contract that actually survives — which is the invariant #7849
was opened for, not the mechanism:
- the pathological pair must stay BOUNDED (completes in <4s, body intact) —
  measured at ~280ms on the current guards;
- it must FAIL OPEN — original body returned by identity, compressed false,
  stats null (the explanatory zero-savings stats belonged to the removed
  budget path, which skipped before producing any);
- the 512 MiB child fixture must still exit 0 with the full engine chain
  (session-dedup, lite, rtk, headroom, caveman) — that IS the OOM guard — and
  session-dedup must still report its skip, now pinned by prefix since the
  reason string moved with the mechanism.

No threshold was loosened and no case was deleted: 4/4 here, 8/8 on the sibling
session-dedup.test.ts.

Refs #9298

* docs(mcp): bump the tool count to 105 and realign two vitest count pins

Three more base-reds from the same 08-06 batch, all count/contract drift that
the merged PRs left in sibling files.

**Docs Gates (fast-path) — 3 STRICT drifts**

check:docs-counts measures the MCP tool set from live code: it is 105 now
(#8925 added omniroute_create_combo), while README.md, AGENTS.md and
docs/frameworks/MCP-SERVER.md still claimed 104. Updated all five occurrences
(two of them inside SVG alt text). check:docs-all exits 0.

**Vitest (fast-path) — 2 failures**

- open-sse/mcp-server/__tests__/essentialTools.test.ts pinned 11 phase-1 tools;
  #8925 shipped omniroute_create_combo as phase 1, making it 12. Verified by
  enumerating MCP_ESSENTIAL_TOOLS directly.
- tests/unit/autoCombo/provider-family-combos.test.ts pinned the auto/glm
  provider set to [auggie, glm, zai]. #8914 (Devin ACP bridge) added
  devin-cli-agentic, whose catalog (registry/devin/catalog.ts:90-93) advertises
  the glm-5-2* line — so it belongs in the family pool for exactly the reason
  the test's own comment gives for auggie: a no-auth backend that genuinely
  serves a family model is a legitimate member. Expected set updated, invariant
  unchanged.

npm run test:vitest 36/36 files, 340/340 tests.

Refs #9298

* fix(combo,usage,oauth): drain the base-reds the shard fix exposed

With the migration collision and the broken import out of the way the four unit
shards actually run, and a further layer of base-reds became visible on the pure
tip 9995bc4893. Three are production defects.

**Production defects**

- open-sse/services/combo/runtimeUnitCapacity.ts:58 called resolveComboTargets()
  WITHOUT the hidden-model snapshot, so it fell back to the default
  getHiddenModelsByProvider() — a fresh full key_value read PER nested combo-ref
  unit, on every request. #8878 threaded the snapshot through the other call
  sites and missed this one. Threaded it from executeRuntimeUnitCombo (and from
  the dispatchPrelude call site), restoring the one-snapshot-per-request
  invariant combo-hidden-leaf-routing.test.ts pins. 9/9.
- open-sse/services/usage/firecrawl.ts silently ignored its own `apiKey`
  parameter: 91bb6aa619 moved the fetch to
  fetchFirecrawlQuota(connectionId, connection), which reads the key off the
  connection record, so any caller passing the key directly got "Firecrawl API
  key not available". The explicit key is now merged into the connection passed
  down. firecrawl-usage 8/8.
- src/lib/oauth/constants/oauth.ts was missing a RAYCAST entry in PROVIDERS
  while src/lib/oauth/providers/index.ts registers `raycast` (#8895), so every
  consumer reading PROVIDERS did not know Raycast Pro exists. Also added its
  OAUTH_TEST_CONFIG entry (checkExpiry only — it is an `import_token` provider
  with refreshToken always null), which #8408's guard explicitly requires rather
  than grandfathering. oauth-providers-config 25/25, oauth-test-config-8408 2/2.

**Count / contract drift from the same batch**

- feature flags 45 -> 46, APIKEY_PROVIDERS 197 -> 198 (Raycast Pro #8895),
  unique MCP tools 107 -> 108. Each re-derived from the source of truth.
- vi + pt-BR locales: translated the 8 keys #9415 added
  (providers.newApiAggregator* and providers.modelTestQuotaTooltip) instead of
  relaxing the parity guard. i18n-vi 5/5, i18n-pt-br 3/3.
- login-bootstrap-route: #9491 added `authenticated` to the require-login
  payload so /login can redirect an active session; the three deepEqual bodies
  now carry it. 10/10.

**Flaky-by-construction, made deterministic**

tests/unit/chat-combo-live-test.test.ts asserted the early-keepalive frame with
a 100ms mocked upstream while resolveKeepaliveThreshold() is 2000ms for
openai/*. It only ever passed while unrelated handler latency happened to push
the total past the threshold — incidental, not deterministic, and it stopped
holding once the handler got faster. The mock now sleeps 2400ms so the slow path
is guaranteed and the assertion means what it says. 5/5.

typecheck:core exit 0. check:file-size (base-relative) OK.

Refs #9298

* test(base): run the orphaned #8890 suite and realign three mechanism pins

**check:test-discovery — a suite that had NEVER executed**

#8890 landed open-sse/services/__tests__/fail-fast-concurrency-gate.test.ts into
a directory no runner collects (only one explicit file from that folder is in
vitest.mcp.config.ts), so it ran zero times since it merged. Wired it into the
runner AND into check-test-discovery.mjs's mirrored collector list, which the
gate keeps in sync deliberately. It passes 4/4 now that it actually runs —
test:vitest goes 36 -> 37 files, 340 -> 344 tests.

**check-db-rules-classification** — 37 -> 38 audited modules, adding probeUtils
alongside the INTENTIONALLY_INTERNAL entry from the previous commit.

**ratelimit-reservoir-refresh** — #9604 (rolling RPM leases) DELETED Bottleneck's
fixed-window reservoir, so currentReservoir() is null and the poll for
`reservoir === 2` could never settle. It updated several sibling suites but not
this one. The pin on the removed mechanism is gone; what remains is the
invariant the original Bottleneck heartbeat bug actually broke and that #9529
opened this test for — after a header-learned updateSettings() the limiter must
keep admitting work, proven by racing a post-exhaustion request against a 5s
timer. 1/1.

**translator-openai-to-gemini** — #9568 (c9a3361e5a) made
buildChangedToolNameMap emit IDENTITY entries too, because Gemini lowercases
tool names in functionCall responses and the response translator needs a key to
map them back. Any request carrying tools therefore carries `_toolNameMap` in
the Antigravity envelope now. Expected key list updated and the map's contents
asserted explicitly rather than left implicit. 45/45.

Refs #9298

* fix(db): restore node-backed synced catalogs and realign the #8944 context hints

**Production regression from #9294 (d69f521491)**

lookupModelMeta moved from getSyncedAvailableModels(providerId) to
getActiveSyncedCatalog(providerId). The new reader unions models only from rows
in `provider_connections` with isActive = 1 — but a provider NODE lives in
`provider_nodes` and NEVER has a connections row, so filtering by active
connection ids silently dropped every node's synced catalog.

The consequence was not just a missing list: lookupModelMeta reads that catalog
for RUNTIME METADATA, so for openai-compatible nodes it took out
- `supportedThinkingEfforts`, which is what splitSyncedEffortSuffix needs — so
  `<prefix>/<model>-high` stopped resolving to the base id and the effort was
  never derived (#7694), and
- `contextWindow` / `maxInputTokens`, used by the combo context-window filter.

getActiveSyncedCatalog now falls back to the provider-wide key_value set — the
exact pre-#9294 source — when no active connection carries a catalog, and marks
that fallback explicitly NON-authoritative. #9294's live-catalog gating is about
what an active connection actually serves, so a node-backed catalog informs
metadata while never being able to reject a model as unavailable. `available`
therefore stays fail-open for nodes, as it was before.

sync-reasoning-supported-efforts-7694 23/23 (was 21/2).
live-model-catalog-reconciliation-8926 11/11 and combo-provider-wildcard 23/23
confirm #9294's own coverage is untouched.

**#8944 sibling-test drift**

714a315a1a ("Treat context metadata as a routing hint") deliberately turned the
context-window check from a HARD filter into an ordering hint: a catalog-too-small
target is demoted, not removed, because a stale catalog entry must never delete
the only target that could accept the request at runtime. The PR updated one case
in this suite and left three asserting the old drop behaviour. Realigned to the
new contract — the too-small target must lose the ordering to the fitting one
while remaining present — and renamed them from "still rejects"/"still dropped"
to "is demoted"/"ordered last" so the names stop describing the removed
behaviour. 14/14.

**file-size**

tests/unit/translator-openai-to-gemini.test.ts testFrozen 1616 -> 1619: the
frozen value sat exactly at the base size, so the 3 lines the previous commit's
_toolNameMap alignment needs could not fit. Justified in the baseline.

typecheck:core exit 0.

Refs #9298

* chore(stryker): register the two covering suites missing from tap.testFiles

check:mutation-test-coverage flags any unit test that covers a mutated module but
is absent from stryker.conf.json tap.testFiles — without the entry its mutant
kills do not count toward the module's score.

- tests/unit/antigravity-prefer-stored-project.test.ts covers
  open-sse/services/combo/quotaStrategies.ts (added earlier in this PR).
- tests/unit/executor-devin-cli-agentic-acp.test.ts covers
  src/sse/services/auth.ts — pre-existing drift, same gate, same fix.

Inserted in alphabetical position only; the rest of the file is byte-identical
(it is not prettier-formatted upstream and reformatting it is out of scope here).

Refs #9298

* fix(db): drop the never-wired getSessionModelUsageCounts (knip regression)

The dead-code ratchet only ran once the earlier Fast Quality Gates steps stopped
failing, and it lands at 228 vs baseline 227.

The extra symbol is src/lib/db/contextHandoffs.ts::getSessionModelUsageCounts,
added by #8894 "for least-used strategy" and never wired: the least-used branch
in applyStrategyOrdering.ts uses the pre-existing sortTargetsByUsage(), and the
helper has no caller in src/, open-sse/ or tests/. It is the same incomplete-PR
shape as that PR's import of a module which does not exist in the repo (fixed
earlier in this branch).

Removed rather than baselined — bumping the ratchet would loosen the gate, and
removal is exactly the remedy the gate prescribes. Same treatment the Dario
installer's never-wired uninstall() got in #9600. The implementation is
recoverable from a598fbb090 whenever someone actually wires a session-aware
least-used strategy.

check:dead-code 228 -> 227 (baseline untouched). check:db-rules exit 0.
context-handoff 13/13, db-context-handoffs 7/7, service-context-handoff 11/11.

Refs #9298

* fix(security): embed the Raycast signature secret via resolvePublicCred (HR#11)

The secret-scan ratchet only ran once the earlier Fast Quality Gates steps
stopped failing, and it lands at 1 finding vs baseline 0.

The finding is open-sse/services/raycast.ts:19 —
RAYCAST_DEFAULT_SIG_SECRET, a 64-hex request-signature secret that #8895
committed as a bare string literal. It is genuinely public (community-extracted
from the Raycast macOS client; the SAME value ships to every install, it is not
a per-user credential), which is exactly the category Hard Rule #11 governs:
public upstream credentials MUST go through resolvePublicCred()
(open-sse/utils/publicCreds.ts), never a literal — see
docs/security/PUBLIC_CREDS.md.

So the fix is the mandated pattern, not a .gitleaks.toml allowlist entry: added
`raycast_sig_secret` to EMBEDDED_DEFAULTS as the XOR-masked byte sequence and
resolved it with the existing RAYCAST_SIG_SECRET env override. The
providerSpecificData.sigSecret override is untouched. Verified the decoded value
is byte-identical to the literal it replaces.

check:secrets secretFindings 1 -> 0. check:public-creds exit 0.
publicCreds 12/12, raycast-auth 6/6, raycast-local-extract 1/1,
trae-publiccred 3/3. typecheck:core exit 0.

Refs #9298

---------

Co-authored-by: diegosouzapw <diegosouzapw@users.noreply.github.com>

2026-08-07 11:13:20 -03:00

100 KiB

Raw Blame History

🚀 OmniRoute — The Free AI Gateway

OmniRoute — Never stop coding. Every AI tool → 291 providers — 90+ free — through one endpoint. Claude Code, Codex, Cursor, Cline, Copilot & Antigravity into FREE Claude / GPT / Gemini with auto-fallback. RTK + Caveman stacked compression saves 15–95% tokens (~89% avg) — never hit limits. 291 AI providers · 90+ free tiers · ~1.53B free tokens/mo · 19 routing strategies · $0 to start.

💰 ~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-tiers page. 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?

OmniRoute request flow: your IDE or CLI (Claude Code, Cursor, Cline…) calls one local endpoint (http://localhost:20128/v1); the OmniRoute Smart Router (RTK + Caveman compression, 19 routing strategies, circuit breakers, TLS stealth, MCP, A2A, guardrails) auto-falls back across 4 provider tiers — Tier 1 Subscription (Claude Code, Codex, Copilot), quota out? Tier 2 API Key (DeepSeek, Groq, xAI), budget hit? Tier 3 Cheap (GLM $0.5, MiniMax $0.2), budget hit? Tier 4 Free (Kiro, Qoder, Pollinations) — always on.

🤝 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

All 19 combo routing strategies animated — one tile per strategy: priority, fill-first, weighted, round-robin, p2c, least-used, random, strict-random, cost-optimized, headroom, reset-window, reset-aware, context-relay, context-optimized, cache-optimized, lkgp, auto, fusion, pipeline. See the table above for what each one does.

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)

OmniRoute resilience — 3 independent self-healing layers, the right layer for the right failure. Layer 1 provider circuit breaker (whole provider): trips only on 408/5xx, thresholds OAuth 3× / API-key 5× / local 2×, resets 60s/30s/15s into a HALF-OPEN probe, lazy recovery; while OPEN the combo reroutes to the next provider. Layer 2 connection cooldown (one key/account): base 5s OAuth / 3s API-key, exponential ×2 backoff with anti-thundering-herd guard, 429 honors Retry-After, success clears all error state; one cooling key is skipped while sibling keys keep serving. Layer 3 model lockout (one model): per-model 429, local 404 or mode denials lock just that model — never the whole connection. Terminal states (banned, expired, credits exhausted) are for the operator, not cooldowns.

_{📖 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-codex are zero-config. → CLI Integrations
🛰️ Remote mode — drive a remote OmniRoute with scoped tokens (connect / contexts / tokens) + an antigravity OAuth 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-Decision header naming the strategy/provider/latency that served it, a new cache-optimized combo strategy + Auto-Combo cacheAffinity factor route repeat requests back to the connection holding the cached prefix, and a read-only /v1/auto-combo/{channel}/candidates endpoint exposes an auto/* 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}

Animated terminal demoing the OmniRoute CLI — omniroute providers list, omniroute combo list, omniroute health — cycling over the 80+ command surface: providers · oauth · keys · combo · nodes · models · cache · compression · cost · usage · quota · health · resilience · telemetry · logs · audit · mcp · a2a · cloud · memory · skills · eval · tunnel · backup · sync · webhooks · policy · pricing · translator · simulate …

🤝 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 — 105 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

OmniRoute compression pipeline: a client request of 10,000 tokens passes through 12 stacked engines — Session-Dedup, CCR, Lite, RTK, Responses Tool Output, Headroom, Relevance, Caveman, Aggressive, LLMLingua-2, Ultra, OmniGlyph — and reaches the provider at about 1,080 tokens, up to 95% saved. Code, URLs and JSON are always preserved byte-perfect.

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 / ultra intensity. 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-compression header › routing-combo override › active named profile › adaptive / auto-trigger › panel default › off. The applied plan echoes back in the X-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 ERESOLVE or 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

Pre-release Docker channel: diegosouzapw/omniroute:next and diegosouzapw/omniroute:next-web follow the current default release/v* branch. These mutable tags are intended only for testing unreleased fixes and are not supported for production. See Docker Release Channels.

🛠️ 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.Z tip (not main) — 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.Z branch

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}

100 KiB Raw Blame History Unescape Escape