mirror of
https://github.com/diegosouzapw/OmniRoute.git
synced 2026-08-14 19:22:32 +03:00
cadc3f10b7
* chore(release): open v3.8.35 development cycle
* fix db vacuum scheduler settings (#4726)
Scheduled VACUUM now follows Storage page settings (scheduledVacuum/vacuumHour) as single source of truth; env-flag control path removed. 11/11 vacuum-scheduler tests pass against release/v3.8.35 tip; no orphaned env refs. Integrated into release/v3.8.35.
* fix(tier): noAuth providers count as free; free filter returns empty … (#4753)
noAuth providers now classified free (union of legacy list + NOAUTH_PROVIDERS chat-tier derivation), -free arena_elo alias, and auto/<cat>:free returns an empty pool when no free candidate matches (opt-in legacy fallback via OMNIROUTE_AUTO_FREE_FALLBACK_TO_FULL_POOL). New env var documented in .env.example + ENVIRONMENT.md; CHANGELOG bullet added (maintainer co-author). 46/46 node + 56/56 vitest tests pass on release tip; env-doc-sync, docs-sync, typecheck:core, lint, file-size all green. Integrated into release/v3.8.35.
* refactor(chatCore): extrai 11 helpers de nível superior para 6 leaves puros (#3501) (#4571)
chatCore god-file decomposition (#3501): extract 6 pure leaves (cacheUsageMeta, executorClientHeaders, nonStreamingResponseBody, skillsFormat, streamErrorResult, streamFinalize) from chatCore.ts. Rebased onto release/v3.8.35 tip (resolved single chatCore.ts conflict — removed now-extracted inline buildExecutorClientHeaders). 265/265 chatcore tests, 26/26 new leaf tests, typecheck:core, cycles, file-size all green. Integrated into release/v3.8.35.
* refactor(chatCore): extrai resolveExecutorWithProxy + getExecutionCredentials para leaves (#3501) (#4646)
chatCore #3501: extract resolveExecutorWithProxy + getExecutionCredentials to leaves (executorProxy.ts, executionCredentials.ts). Clean cherry-pick onto release tip post-#4571. 12/12 new leaf tests, typecheck:core, cycles, file-size green. Integrated into release/v3.8.35.
* refactor(chatCore): extrai transforms de mensagens Claude p/ leaf (#3501) (#4708)
chatCore #3501: extract Claude upstream-message transforms to leaf (claudeUpstreamMessages.ts + claudeMessageTypes.ts). Clean cherry-pick post-#4646. 8/8 new leaf tests, typecheck/cycles/file-size green. Integrated into release/v3.8.35.
* refactor(chatCore): extrai persistAttemptLogs para leaf (#3501) (#4717)
chatCore #3501: extract persistAttemptLogs to leaf (attemptLogging.ts). Rebased onto release tip post-#4708 (resolved imports conflict: kept tip's resolveCompressionHeader from compression Phase 3, dropped now-unused logTruncation import moved into the leaf). 288/288 chatcore tests, typecheck/cycles/file-size green. Integrated into release/v3.8.35.
* refactor(chatCore): extrai stageTrace + compressionUsageReceipt para leaves (#3501) (#4721)
chatCore #3501: extract stageTrace + compressionUsageReceipt to leaves. Clean cherry-pick post-#4717. 6/6 new leaf tests, typecheck/cycles/file-size green. Integrated into release/v3.8.35.
* refactor(chatCore): extrai prepareUpstreamBody (1ª sub-fatia do executeProviderRequest, #3501) (#4730)
chatCore #3501: extract prepareUpstreamBody (first sub-slice of executeProviderRequest) to leaf (upstreamBody.ts). Clean cherry-pick post-#4721. 7/7 new leaf tests, full 301/301 chatcore suite, typecheck/cycles/file-size green. Completes the 6-PR chatCore decomposition stack into release/v3.8.35.
* fix(db): make db-backup import size cap configurable (#4719) (#4757)
Co-authored-by: Diego Rodrigues de Sa e Souza <souzamiriamrodrigues790@gmail.com>
* chore(quality): expand check:release-green to the FULL release-PR gate set (#4758)
The release-green pre-flight (Solution C) previously covered only a subset of the
gates that run exclusively on the release PR (PR→main), so reds still accrued
silently on release/** and surfaced in ~40-min layers at release time (v3.8.34:
3 CI rounds — CodeQL sanitization, then the fail-fast Quality Ratchet revealing
openapi then cyclomatic-complexity one push at a time, plus zizmor/integration).
Now check:release-green reproduces the COMPLETE release-PR gate set and reports
EVERY red in one pass (collected, not fail-fast):
- New DRIFT ratchets (report-only, rebaselined at release, never block):
cyclomatic complexity, dead-code, type-coverage, compression-budget,
openapi-coverage, workflow-lint (zizmor), codeql-ratchet.
- New HARD gates (real defects): docs-all (fabricated-docs strict + i18n mirror
sync) and the integration test suite (gated behind !--quick).
The only release-PR gates it still cannot reproduce locally are GitHub-side CodeQL
semantic analysis and SonarQube/SonarCloud (external services).
The nightly-release-green workflow and /green-prs inherit the expanded coverage
automatically (they invoke this script), so cycle drift is now surfaced
continuously and the release PR is green on its first CI run.
Co-authored-by: Diego Rodrigues de Sa e Souza <souzamiriamrodrigues790@gmail.com>
* fix(dashboard): add missing onboarding.tiers step title (#4698) (#4755)
Co-authored-by: Diego Rodrigues de Sa e Souza <souzamiriamrodrigues790@gmail.com>
* feat(compression): Output Styles registry + D0 telemetry (Phase 4A) (#4694)
Phase 4A: Output Styles registry + D0 telemetry. Integrated into release/v3.8.35.
* feat(compression): SLM tier for ultra (Phase 4B) [stacked on #4694] (#4707)
Phase 4B: SLM tier for ultra. Integrated into release/v3.8.35.
* feat(compression): context-budget adaptive compression (Phase 4C) [stacked on #4707] (#4716)
Phase 4C: adaptive context-budget compression. Integrated into release/v3.8.35.
* feat(compression): offline evaluation harness (Phase 4 D1) [stacked on #4716] (#4720)
Phase 4 D1: offline evaluation harness. Integrated into release/v3.8.35.
* fix(sse): deepseek-web folds role:tool results into prompt transcript (#4712) (#4756)
Co-authored-by: Diego Rodrigues de Sa e Souza <souzamiriamrodrigues790@gmail.com>
* fix(dashboard): remove dead unconditional useLiveRequests call in HomePageClient (#4759, #4745, #4596) (#4761)
Co-authored-by: Diego Rodrigues de Sa e Souza <souzamiriamrodrigues790@gmail.com>
* fix(dashboard): dedupe provider nodes by id on compatible-provider add (#4746) (#4768)
Co-authored-by: Diego Rodrigues de Sa e Souza <souzamiriamrodrigues790@gmail.com>
* chore(db): re-export compressionRunTelemetry from localDb to satisfy db-rules (#4775)
Co-authored-by: Diego Rodrigues de Sa e Souza <souzamiriamrodrigues790@gmail.com>
* docs(security): add canonical STRIDE-based threat model (#4783)
Canonical STRIDE threat model. Integrated into release/v3.8.35.
* test(dashboard): add smoke test for home client dashboard (#4793)
Smoke test guarding the dashboard home client render (regression #4745/#4759). Code fix already landed via #4761; this PR's jsdom smoke test is the net-new regression guard. Integrated into release/v3.8.35.
* fix(combos): auto-promote zeroLatencyOptimizationsEnabled so legacy configs (pre-3.8.33 fallbackCompressionMode="lite") round-trip on the first GUI edit (#4774)
Auto-promote zeroLatencyOptimizationsEnabled + strip v3.8.31-era removed keys so legacy combo configs round-trip through PUT /api/combos/{id} on first GUI edit (closes #4382 followup). Pre-merge: rewrote the now-stale reject test to assert auto-promotion + added passthrough/round-trip regression guards; reconciled combos/page.tsx file-size baseline. Integrated into release/v3.8.35.
* refactor(chatCore): extrai parse + usage-stats não-streaming do executeProviderRequest (#3501) (#4762)
chatCore #3501: extract parseNonStreamingResponseBody + recordNonStreamingUsageStats. Integrated into release/v3.8.35.
* refactor(chatCore): extrai recordContextEditingTelemetryHook (#3501) (#4779)
chatCore #3501: extract recordContextEditingTelemetryHook. Integrated into release/v3.8.35.
* refactor(chatCore): extrai recordCompressionCacheStats (#3501) (#4792)
chatCore #3501: extract recordCompressionCacheStats. Integrated into release/v3.8.35.
* refactor(chatCore): extrai writeCavemanOutputAnalytics (#3501) (#4794)
chatCore #3501: extract writeCavemanOutputAnalytics. Integrated into release/v3.8.35.
* refactor(chatCore): extrai scheduleQuotaShareConsumption (POST-hook não-streaming, #3501) (#4780)
chatCore #3501: extract scheduleQuotaShareConsumption (non-streaming POST-hook). Integrated into release/v3.8.35.
* refactor(chatCore): extrai emitRequestGamificationEvent (helper compartilhado DRY, #3501) (#4776)
chatCore #3501: extract emitRequestGamificationEvent (DRY streaming/non-streaming). Integrated into release/v3.8.35.
* refactor(chatCore): extrai runPluginOnResponseHook (#3501) (#4782)
chatCore #3501: extract runPluginOnResponseHook. Integrated into release/v3.8.35.
* refactor(chatCore): extrai scheduleStreamingQuotaShareConsumption (POST-hook streaming, #3501) (#4784)
chatCore #3501: extract scheduleStreamingQuotaShareConsumption (streaming POST-hook). Integrated into release/v3.8.35.
* refactor(chatCore): extrai recordStreamingUsageStats (analytics de usage streaming, #3501) (#4791)
chatCore #3501: extract recordStreamingUsageStats. Integrated into release/v3.8.35.
* refactor(chatCore): extrai recordStreamingCost (custo por-request streaming, #3501) (#4790)
chatCore #3501: extract recordStreamingCost (per-request streaming cost). Integrated into release/v3.8.35.
* docs(readme): credit ponytail + OmniCompress; restore env-doc-sync release-green (#4799)
README compression credits (ponytail/OmniCompress) + env-doc-sync ignore for eval-only OMNIROUTE_EVAL_CREDENTIALS (restores release-green after #4720). Integrated into release/v3.8.35.
* chore(quality): trim combo-config.test.ts comments under file-size cap (#4774 follow-up) (#4800)
Restore file-size release-green. Integrated into release/v3.8.35.
* feat(api-docs): Redoc-rendered /api/docs + consolidate OpenAPI spec to docs/openapi.yaml (#4781)
Redoc /api/docs + OpenAPI spec consolidated to docs/openapi.yaml (canonical 201-path complete spec; old path → legacy fallback). All refs/gates/tests/CI updated. Integrated into release/v3.8.35.
* docs(compression): declare Phase 4 layers — Output Styles, adaptive dial, per-request control (#4801)
The README compression section listed the 9 input engines but not the Phase 4
layers now in production:
- Output Styles (output-axis steering: terse-prose / less-code / terse-cjk, lite/full/ultra)
- adaptive context-budget dial (reserve-output|percentage|absolute · floor|replace-autotrigger|off)
- per-request x-omniroute-compression precedence + the offline eval harness
Also bumped the highlights range to v3.8.35, expanded the compression feature bullet,
and marked the GUIDE's Phase 4 row Shipped (was 'Planned' — it's merged on v3.8.35).
Co-authored-by: Diego Rodrigues de Sa e Souza <souzamiriamrodrigues790@gmail.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* chore(release): finalize v3.8.35 CHANGELOG + docs reconciliation
- CHANGELOG: complete 3.8.35 section (all 35 commits since v3.8.34,
contributor attribution: @rdself @megamen32 @KooshaPari @JxnLexn)
- docs(security): align THREAT_MODEL.md refs with real code
(routeGuard.ts, tokenLimits.ts, /api/monitoring/health) — fabricated-docs gate
- check:fabricated-docs: skip docs/superpowers/specs (dated research reports)
- i18n: sync 3.8.35 section into 41 CHANGELOG mirrors (docs-sync size gate)
- ratchet rebaseline: cyclomatic 1916->1920, eslintWarnings 3907->3912
(inherited cycle drift; release-finalize diff is docs-only)
* fix(release): resolve inherited base-reds surfaced by v3.8.35 release CI
Cycle base-reds that only run on PR→main (not the PR→release fast-path):
- test(autoCombo): suffixComposition-4517 used node:test in a vitest-only dir
(#4753) → vitest found no suite. Switch to the vitest API. (Vitest job)
- test(agentSkills): openapiParser fixture wrote docs/reference/openapi.yaml;
parser reads docs/openapi.yaml since #4781 → point fixture at the new path.
(Unit/Coverage/Node24/Node26 shard 4)
- test(integration): proxy-pipeline source-scan expected inline streaming-cost
code that #4790/#3501 extracted to the recordStreamingCost leaf → assert the
delegation instead. (Integration 1/2)
- fix(chatCore): derive the log trace id from crypto, not Math.random
(CodeQL js/insecure-randomness — log-correlation id, not a secret).
- test(resilience): circuit-breaker invalid-cooldown fallback asserted t>29000,
flaking on slow CI where ~1.6s elapsed gave t=28401 → tolerate wall-clock
drift (t>25000). (Unit 6/8)
* fix(usage): derive pending-request id from crypto, not Math.random
CodeQL js/insecure-randomness (#669): the pending-request id generated in
trackPendingRequest (usageHistory.ts) flows into attempt logging and was flagged
as insecure randomness in a security context. It's a log-correlation id, not a
secret — switch to crypto RNG to clear the alert. Pairs with the chatCore traceId
fix in 37c49781a (same sink).
---------
Co-authored-by: Diego Rodrigues de Sa e Souza <souzamiriamrodrigues790@gmail.com>
Co-authored-by: Randi <55005611+rdself@users.noreply.github.com>
Co-authored-by: Demiurge The Single <megamen932@gmail.com>
Co-authored-by: KooshaPari <42529354+KooshaPari@users.noreply.github.com>
Co-authored-by: Jan Leon <Jan.gaschler@gmail.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1173 lines
74 KiB
Markdown
1173 lines
74 KiB
Markdown
<div align="center">
|
||
|
||
<img src="./docs/screenshots/MainOmniRoute.png" alt="OmniRoute Dashboard" width="820"/>
|
||
|
||
<br/>
|
||
|
||
# 🚀 OmniRoute — The Free AI Gateway
|
||
|
||
### Never stop coding. Connect every AI tool to **231 providers** — **50+ free** — through one endpoint.
|
||
|
||
**Plug Claude Code, Codex, Cursor, Cline, Copilot & Antigravity into FREE Claude / GPT / Gemini. Auto-fallback.**
|
||
<br/>
|
||
|
||
**RTK + Caveman compression saves 15–95% tokens. Never hit limits.**
|
||
|
||
<br/>
|
||
|
||
**~1.6B documented free tokens/month** — up to **~2.1B in your first month** with signup credits — aggregated across the free tiers, plus a long tail of permanently-free, no-cap providers, and the compression above stretches every one further. ([how we count →](docs/reference/FREE_TIERS.md#tldr--how-much-free-inference-does-omniroute-actually-aggregate))
|
||
|
||
<br/>
|
||
|
||
[](#-231-ai-providers--50-free)
|
||
[](#-231-ai-providers--50-free)
|
||
[](docs/reference/FREE_TIERS.md)
|
||
[](#%EF%B8%8F-save-1595-tokens--automatically)
|
||
[](#-combos--the-flagship)
|
||
[](#-quick-start)
|
||
|
||
<br/>
|
||
|
||
### 💬 Join the community
|
||
|
||
[](https://discord.gg/EkzRkpzKYt)
|
||
[](https://t.me/omnirouteOficial)
|
||
[](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
|
||
[](https://chat.whatsapp.com/BTGJXIyjeNIIgExvTMGGhI)
|
||
|
||
**Questions, provider tips, roadmap & support → [Discord](https://discord.gg/EkzRkpzKYt) · [Telegram](https://t.me/omnirouteOficial) · WhatsApp [🌍 Global](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) / [🇧🇷 Brasil](https://chat.whatsapp.com/BTGJXIyjeNIIgExvTMGGhI)**
|
||
|
||
<br/>
|
||
|
||
<a href="https://trendshift.io/repositories/23589" target="_blank"><img src="https://trendshift.io/api/badge/repositories/23589" alt="diegosouzapw%2FOmniRoute | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
|
||
|
||
[](https://www.npmjs.com/package/omniroute)
|
||
[](LICENSE)
|
||
[](package.json)
|
||
[](https://github.com/diegosouzapw/OmniRoute)
|
||
|
||
<div align="center">
|
||
|
||
[](https://www.npmjs.com/package/omniroute)
|
||
|
||
[](https://hub.docker.com/r/diegosouzapw/omniroute)
|
||
|
||
|
||
[](https://omniroute.online)
|
||
|
||
</div>
|
||
|
||
<br/>
|
||
|
||
[**🚀 Quick Start**](#-quick-start) • [**🎯 Combos**](#-combos--the-flagship) • [**🌐 Providers**](#-231-ai-providers--50-free) • [**🔌 CLI & MCP**](#-full-cli--a2a--mcp) • [**🗜️ Compression**](#%EF%B8%8F-save-1595-tokens--automatically) • [**🌍 Website**](https://omniroute.online)
|
||
|
||
[💥 The Promise](#-the-promise) • [🤔 Why](#-why-omniroute) • [🏆 What Sets Apart](#-what-sets-omniroute-apart) • [🤖 Compatible CLIs](#-compatible-clis--coding-agents) • [🖥️ Where It Runs](#%EF%B8%8F-where-omniroute-runs--anywhere) • [🔒 Private](#-private--local-first) • [🎬 In Action](#-omniroute-in-action) • [📚 Explore More](#-explore-more) • [📧 Support](#-support--community)
|
||
|
||
</div>
|
||
|
||
<div align="center">
|
||
<b>🌐 Available in 40+ languages</b>
|
||
<table>
|
||
<tr>
|
||
<td align="center"><a href="README.md">🇺🇸</a></td>
|
||
<td align="center"><a href="docs/i18n/pt-BR/README.md">🇧🇷</a></td>
|
||
<td align="center"><a href="docs/i18n/es/README.md">🇪🇸</a></td>
|
||
<td align="center"><a href="docs/i18n/fr/README.md">🇫🇷</a></td>
|
||
<td align="center"><a href="docs/i18n/it/README.md">🇮🇹</a></td>
|
||
<td align="center"><a href="docs/i18n/ru/README.md">🇷🇺</a></td>
|
||
<td align="center"><a href="docs/i18n/zh-CN/README.md">🇨🇳</a></td>
|
||
<td align="center"><a href="docs/i18n/de/README.md">🇩🇪</a></td>
|
||
<td align="center"><a href="docs/i18n/ja/README.md">🇯🇵</a></td>
|
||
<td align="center"><a href="docs/i18n/ko/README.md">🇰🇷</a></td>
|
||
<td align="center"><a href="docs/i18n/in/README.md">🇮🇳</a></td>
|
||
</tr>
|
||
<tr>
|
||
<td align="center"><a href="docs/i18n/th/README.md">🇹🇭</a></td>
|
||
<td align="center"><a href="docs/i18n/vi/README.md">🇻🇳</a></td>
|
||
<td align="center"><a href="docs/i18n/id/README.md">🇮🇩</a></td>
|
||
<td align="center"><a href="docs/i18n/ms/README.md">🇲🇾</a></td>
|
||
<td align="center"><a href="docs/i18n/phi/README.md">🇵🇭</a></td>
|
||
<td align="center"><a href="docs/i18n/ar/README.md">🇸🇦</a></td>
|
||
<td align="center"><a href="docs/i18n/he/README.md">🇮🇱</a></td>
|
||
<td align="center"><a href="docs/i18n/az/README.md">🇦🇿</a></td>
|
||
<td align="center"><a href="docs/i18n/uk-UA/README.md">🇺🇦</a></td>
|
||
<td align="center"><a href="docs/i18n/pl/README.md">🇵🇱</a></td>
|
||
<td align="center"><a href="docs/i18n/cs/README.md">🇨🇿</a></td>
|
||
</tr>
|
||
<tr>
|
||
<td align="center"><a href="docs/i18n/nl/README.md">🇳🇱</a></td>
|
||
<td align="center"><a href="docs/i18n/bg/README.md">🇧🇬</a></td>
|
||
<td align="center"><a href="docs/i18n/da/README.md">🇩🇰</a></td>
|
||
<td align="center"><a href="docs/i18n/fi/README.md">🇫🇮</a></td>
|
||
<td align="center"><a href="docs/i18n/no/README.md">🇳🇴</a></td>
|
||
<td align="center"><a href="docs/i18n/sv/README.md">🇸🇪</a></td>
|
||
<td align="center"><a href="docs/i18n/hu/README.md">🇭🇺</a></td>
|
||
<td align="center"><a href="docs/i18n/ro/README.md">🇷🇴</a></td>
|
||
<td align="center"><a href="docs/i18n/sk/README.md">🇸🇰</a></td>
|
||
<td align="center"><a href="docs/i18n/pt/README.md">🇵🇹</a></td>
|
||
<td align="center"></td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
|
||
<br/>
|
||
|
||
<div align="center">
|
||
|
||
# 💰 ~1.6B Free Tokens / Month
|
||
|
||
</div>
|
||
|
||
> 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 **40+ provider pools / 500+ models** into one honest number and shows it live on the dashboard (`/dashboard/free-tiers`).
|
||
|
||
- **~1.6B free tokens / month** (steady) — and **up to ~2.1B in your first month** with signup credits.
|
||
- **Pool-deduped, honest** — we count each shared free pool **once**, so the headline isn't inflated by rate-limit ceilings the way multi-billion competitor claims are. (Counting every rate limit 24/7 would read ~10B; we don't publish that.)
|
||
- **Plus the un-countable** — permanently-free, no-token-cap providers (SiliconFlow, Z.AI GLM-Flash, Kilo, OpenCode Zen…) and a **$10 OpenRouter top-up** that unlocks **+24M/mo**, both surfaced separately so they never inflate the headline.
|
||
- **Per-model breakdown**, **live used / remaining** for the current month, and a transparent **terms flag** per provider.
|
||
|
||
|
||
|
||
> Preview mockup — a real screenshot lands once the `/dashboard/free-tiers` page is validated. Full methodology (pool dedupe, credit tiers, provider terms): **[docs/reference/FREE_TIERS.md](docs/reference/FREE_TIERS.md)**.
|
||
|
||
<br/>
|
||
|
||
<div align="center">
|
||
|
||
# 💥 The Promise
|
||
|
||
</div>
|
||
|
||
> One endpoint. **231 providers.** Never stop building — and let OmniRoute pick the cheapest one that works.
|
||
|
||
<table>
|
||
<tr>
|
||
<td width="33%" valign="top"><b>🚫 Never hit limits</b><br/><sub>Auto-fallback across 231 providers in milliseconds. Quota out? Next provider takes over — zero downtime.</sub></td>
|
||
<td width="33%" valign="top"><b>💸 Save up to 95% tokens</b><br/><sub>RTK + Caveman stacked compression cuts 15–95% of eligible tokens (~89% avg on tool-heavy sessions).</sub></td>
|
||
<td width="33%" valign="top"><b>🆓 $0 to start</b><br/><sub>50+ providers with a free tier, 11 free <i>forever</i> (Kiro, Qoder, Pollinations, LongCat…). No card needed.</sub></td>
|
||
</tr>
|
||
<tr>
|
||
<td width="33%" valign="top"><b>🔌 Every tool works</b><br/><sub>16+ coding agents — Claude Code, Codex, Cursor, Cline, Copilot, Antigravity — through one config.</sub></td>
|
||
<td width="33%" valign="top"><b>🧩 One endpoint</b><br/><sub>OpenAI ↔ Claude ↔ Gemini ↔ Responses API translation. Point any tool at <code>/v1</code> and it just works.</sub></td>
|
||
<td width="33%" valign="top"><b>🛡️ Production-grade</b><br/><sub>Circuit breakers, TLS stealth, MCP (87 tools), A2A, memory, guardrails, evals. 14,965 tests.</sub></td>
|
||
</tr>
|
||
</table>
|
||
|
||
<br/>
|
||
<br/>
|
||
|
||
<div align="center">
|
||
|
||
# 🤔 Why OmniRoute?
|
||
|
||
</div>
|
||
|
||
> Stop juggling 10 dashboards, dead API keys, and surprise bills.
|
||
|
||
| ❌ The daily pain | ✅ How OmniRoute fixes it |
|
||
| ------------------------------------------------------ | ----------------------------------------------------------------------------- |
|
||
| 📉 Subscription quota expires unused every month | **Maximize subscriptions** — track quota, use every token before reset |
|
||
| 🛑 Rate limits stop you mid-coding | **4-tier auto-fallback** — Subscription → API → Cheap → Free, in milliseconds |
|
||
| 🔥 Tool outputs (`git diff`, `grep`, logs) burn tokens | **RTK + Caveman compression** — save 15–95% eligible tokens per request |
|
||
| 💸 Expensive APIs ($20–50/mo per provider) | **Cost-optimized routing** — auto-route to the cheapest viable model |
|
||
| 🧰 Each AI tool wants its own setup | **One endpoint, every tool, one dashboard** |
|
||
| 🌍 AI blocked in your country | **3-level proxy** + TLS fingerprint stealth — use AI from anywhere |
|
||
|
||
<div align="center">
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────┐
|
||
│ Your IDE / CLI (Claude Code, Cursor, Cline…) │
|
||
└─────────────────────────┬──────────────────────────────────┘
|
||
│ http://localhost:20128/v1
|
||
▼
|
||
┌──────────────────────────────────────────────────────────┐
|
||
│ OmniRoute — Smart Router │
|
||
│ RTK + Caveman compression · 15 routing strategies │
|
||
│ Circuit breakers · TLS stealth · MCP · A2A · Guardrails │
|
||
└─────────────────────────┬──────────────────────────────────┘
|
||
┌─────────────┬────┴────────┬─────────────┐
|
||
▼ Tier 1 ▼ Tier 2 ▼ Tier 3 ▼ Tier 4
|
||
SUBSCRIPTION API KEY CHEAP FREE
|
||
Claude Code, DeepSeek, GLM $0.5, Kiro, Qoder,
|
||
Codex, Copilot Groq, xAI MiniMax $0.2 Pollinations
|
||
quota out? ───▶ budget hit? ─▶ budget hit? ─▶ always on
|
||
```
|
||
|
||
</div>
|
||
|
||
<br/>
|
||
|
||
<div align="center">
|
||
|
||
# 🎯 Combos — The Flagship
|
||
|
||
</div>
|
||
|
||
> 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 — 15 routing strategies
|
||
|
||
| Goal | Strategy / combo |
|
||
| --------------------------------------- | -------------------------------------------------- |
|
||
| 🥇 Drain my subscription before paying | `priority` / `fill-first` |
|
||
| ⚖️ Spread load across accounts | `round-robin` · `weighted` · `p2c` · `least-used` |
|
||
| 💸 Always cheapest viable model | `cost-optimized` · `auto/cheap` |
|
||
| 🧠 Hand off long context between models | `context-relay` · `context-optimized` |
|
||
| 🎲 Randomized / privacy routing | `random` · `strict-random` |
|
||
| 🤖 Just make it smart | `auto` (9-factor scoring) · `lkgp` · `reset-aware` |
|
||
|
||
<sub>The Auto-Combo engine scores every candidate on **9 factors** (health, quota, cost, latency, success rate, freshness…) — see [`docs/routing/AUTO-COMBO.md`](docs/routing/AUTO-COMBO.md).</sub>
|
||
|
||
##
|
||
|
||
### 🧱 Resilience is built in (3 independent layers)
|
||
|
||
| Layer | Scope | What it does |
|
||
| -------------------------- | ----------------- | -------------------------------------------------------------------------- |
|
||
| 🔌 **Circuit breaker** | whole provider | Stops hammering a provider that's failing upstream; auto-probes to recover |
|
||
| 💤 **Connection cooldown** | one account / key | Skips a rate-limited key while other keys keep serving |
|
||
| 🎯 **Model lockout** | provider + model | Quarantines just one quota-limited model, not the whole connection |
|
||
|
||
```
|
||
Combo: "always-on" Strategy: priority
|
||
1. cc/claude-opus-4-7 ← subscription (use it fully)
|
||
2. cx/gpt-5.5 ← second subscription
|
||
3. glm/glm-5.1 ← cheap backup ($0.5/1M)
|
||
4. kr/claude-sonnet-4.5 ← FREE, unlimited (never fails)
|
||
Result: 4 layers of fallback = zero downtime
|
||
```
|
||
|
||
<sub>📖 [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) · [Resilience Guide](docs/architecture/RESILIENCE_GUIDE.md)</sub>
|
||
|
||
<br/>
|
||
|
||
<div align="center">
|
||
|
||
# 🏆 What Sets OmniRoute Apart
|
||
|
||
</div>
|
||
|
||
| Feature | OmniRoute | Other routers |
|
||
| -------------------------------------- | ----------------------------------------------------------- | ------------- |
|
||
| 🌐 Providers | **231** | 20–100 |
|
||
| 🆓 Free providers | **50+ (11 free forever)** | 1–5 |
|
||
| 🔀 Routing strategies | **15** (priority, weighted, cost-optimized, context-relay…) | 1–3 |
|
||
| 🗜️ Token compression | **RTK + Caveman stacked (15–95%)** | None / 20–40% |
|
||
| 🧰 Built-in MCP server | **87 tools, 3 transports, 30 scopes** | Rare |
|
||
| 🤝 A2A agent protocol | **6 skills, JSON-RPC 2.0** | None |
|
||
| 🧠 Memory (FTS5 + vector) | **Yes** | Rare |
|
||
| 🛡️ Guardrails (PII, injection, vision) | **Yes** | Rare |
|
||
| ☁️ Cloud agents | **Codex, Devin, Jules** | None |
|
||
| 🥷 TLS fingerprint stealth | **JA3/JA4 via wreq-js** | None |
|
||
| 🖥️ Multi-platform | **Web · Desktop · Termux · PWA** | Web only |
|
||
| 🌍 i18n | **42 locales** | 0–4 |
|
||
|
||
<sub>📊 Detailed comparison vs LiteLLM, OpenRouter & Portkey → [`docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md`](docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md)</sub>
|
||
|
||
<br/>
|
||
|
||
<div align="center">
|
||
|
||
# ✨ What's New
|
||
|
||
</div>
|
||
|
||
> Recent highlights from **v3.8.20 → v3.8.35**. Full history in [`CHANGELOG.md`](CHANGELOG.md).
|
||
|
||
- **🤖 One-command CLI/agent setup** — a dedicated `setup-*` command configures each coding tool to route through OmniRoute (Claude Code, Codex, Cline, Continue, Cursor, Roo Code, Kilo Code, Crush, Goose, Qwen Code, Aider, OpenCode, Gemini CLI); `omniroute launch` / `omniroute launch-codex` are zero-config launchers. → [CLI Integrations](docs/guides/CLI-INTEGRATIONS.md)
|
||
- **🛰️ Remote mode** — drive a remote OmniRoute from any machine with scoped access tokens (`omniroute connect` / `omniroute contexts` / `omniroute tokens`). → [Remote Mode](docs/guides/REMOTE-MODE.md)
|
||
- **🧭 Smarter auto-routing** — OpenRouter-style `auto/<category>:<tier>` combos (e.g. `auto/coding:fast`, `auto/reasoning:pro`), live Arena-ELO + models.dev model intelligence, per-step account allowlists, provider-wildcard combo steps, nested combo-ref execution, sticky weighted selection, and `web_search`-aware routing to a configured model. → [Auto-Combo](docs/routing/AUTO-COMBO.md)
|
||
- **🗜️ Pluggable compression** — an async pipeline of **9 composable engines** with Compression Studios, an LLMLingua-2 ONNX engine and a heuristic/SLM two-tier **Ultra**, RTK, delegated Anthropic Context Editing, **Output Styles** (output-axis steering: terse-prose / less-code / terse-CJK), an **adaptive context-budget dial** (escalate only as far as needed to fit the context window), per-request `x-omniroute-compression` control, an opt-in offline eval harness, and a unified panel with named profiles + an active-profile selector. → [Compression](docs/compression/COMPRESSION_ENGINES.md)
|
||
- **🕵️ Transparent MITM decrypt (TPROXY)** — capture & translate traffic from CLIs that ignore proxy env vars, with a per-SNI certificate authority and a trust-store installer. → [MITM/TPROXY](docs/security/MITM-TPROXY-DECRYPT.md)
|
||
- **💸 Cost telemetry everywhere** — `X-OmniRoute-*` cost/usage headers on every endpoint (including media), a non-token cost engine, a cache-HIT `X-OmniRoute-Cost-Saved` header, and per-key USD spend quotas. → [API Reference](docs/reference/API_REFERENCE.md)
|
||
- **🧠 Memory you control** — opt-in int8 vector quantization (Qdrant + sqlite-vec), memory off by default, and a per-request `x-omniroute-no-memory` header. → [Memory](docs/frameworks/MEMORY.md)
|
||
- **🛡️ Security** — a prompt-injection guard across every LLM route (backed by a red-team suite), plus a free DuckDuckGo last-resort web search. → [Guardrails](docs/security/GUARDRAILS.md)
|
||
- **🤝 More providers & agents** — Cursor Cloud Agent (a 4th cloud agent), a refreshed 231-provider catalog (OrcaRouter, Wafer AI, OpenAdapter, dit.ai, TokenRouter, …), Vertex AI media generation (speech / transcription / music / video), and one-click account import from CLIProxyAPI (`~/.cli-proxy-api/`). → [Providers](docs/reference/PROVIDER_REFERENCE.md)
|
||
- **⚡ Local performance & infra** — a one-click local Redis launcher (`omniroute redis up`, plus a dashboard Redis panel) and an optional Bifrost Go sidecar that offloads the hottest relay path (`BIFROST_BASE_URL`, with automatic fallback to the TypeScript path on timeout). → [Environment](docs/reference/ENVIRONMENT.md)
|
||
|
||
<br/>
|
||
|
||
<div align="center">
|
||
|
||
# 🤖 Compatible CLIs & Coding Agents
|
||
|
||
> One config — `http://localhost:20128/v1` — and **every** AI IDE or CLI runs on free & low-cost models.
|
||
|
||
<div align="center">
|
||
<table>
|
||
<tr>
|
||
<td align="center" width="120"><a href="https://github.com/anthropics/claude-code"><img src="./public/providers/claude.svg" width="52" alt="Claude Code"/><br/><b>Claude Code</b></a></td>
|
||
<td align="center" width="120"><a href="https://github.com/openai/codex"><img src="./public/providers/codex.svg" width="52" alt="Codex CLI"/><br/><b>Codex CLI</b></a></td>
|
||
<td align="center" width="120"><a href="https://github.com/google-gemini/gemini-cli"><img src="./public/providers/gemini-cli.svg" width="52" alt="Gemini CLI"/><br/><b>Gemini CLI</b></a></td>
|
||
<td align="center" width="120"><img src="./public/providers/cursor.png" width="52" alt="Cursor"/><br/><b>Cursor</b></td>
|
||
<td align="center" width="120"><img src="./public/providers/copilot.png" width="52" alt="Copilot"/><br/><b>Copilot</b></td>
|
||
<td align="center" width="120"><img src="./public/providers/continue.png" width="52" alt="Continue"/><br/><b>Continue</b></td>
|
||
</tr>
|
||
<tr>
|
||
<td align="center" width="120"><a href="https://github.com/anomalyco/opencode"><img src="./public/providers/opencode.svg" width="52" alt="OpenCode"/><br/><b>OpenCode</b></a></td>
|
||
<td align="center" width="120"><a href="https://github.com/Kilo-Org/kilocode"><img src="./public/providers/kilocode.svg" width="52" alt="Kilo Code"/><br/><b>Kilo Code</b></a></td>
|
||
<td align="center" width="120"><img src="./public/providers/droid.svg" width="52" alt="Droid"/><br/><b>Droid</b></td>
|
||
<td align="center" width="120"><img src="./public/providers/openclaw.png" width="52" alt="OpenClaw"/><br/><b>OpenClaw</b></td>
|
||
<td align="center" width="120"><img src="./public/providers/kiro.svg" width="52" alt="Kiro"/><br/><b>Kiro</b></td>
|
||
<td align="center" width="120"><img src="./public/providers/command-code.svg" width="52" alt="Command Code"/><br/><b>Command</b></td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
|
||
<div align="center">
|
||
<b>＋ also works with</b> · Cline · Antigravity · Windsurf · AMP · Hermes · Qwen CLI · Roo · Continue · <b>any OpenAI-compatible tool</b>
|
||
</div>
|
||
|
||
<sub>📖 Per-tool setup for all 16+ tools → [`docs/reference/CLI-TOOLS.md`](docs/reference/CLI-TOOLS.md) · 🧩 OpenCode plugin → [`@omniroute/opencode-provider`](https://www.npmjs.com/package/@omniroute/opencode-provider)</sub>
|
||
|
||
</div>
|
||
|
||
<br/>
|
||
|
||
<div align="center">
|
||
|
||
# 🌐 231 AI Providers — 50+ Free
|
||
|
||
</div>
|
||
|
||
> The most complete catalog of any open-source router: **231 providers**, **50+ with a free tier**, **11 free forever**.
|
||
|
||
<div align="center">
|
||
|
||
### 🆓 Free Forever — $0, no card
|
||
|
||
<table>
|
||
<tr>
|
||
<td align="center" width="150"><img src="https://img.shields.io/badge/AgentRouter-FF6600?style=flat-square" alt="AgentRouter"/><br/><sub>GPT-5, Claude, Gemini<br/>$100 free credits</sub></td>
|
||
<td align="center" width="150"><img src="https://img.shields.io/badge/Qoder_AI-6366F1?style=flat-square" alt="Qoder AI"/><br/><sub>Kimi-K2, DeepSeek-R1<br/>Unlimited FREE</sub></td>
|
||
<td align="center" width="150"><img src="https://img.shields.io/badge/Pollinations-10B981?style=flat-square" alt="Pollinations"/><br/><sub>GPT-5, Claude, Llama 4<br/>No key needed</sub></td>
|
||
<td align="center" width="150"><img src="https://img.shields.io/badge/LongCat-FF7A00?style=flat-square" alt="LongCat"/><br/><sub>Flash-Lite<br/>50M tokens/day 🔥</sub></td>
|
||
</tr>
|
||
<tr>
|
||
<td align="center" width="150"><img src="https://img.shields.io/badge/Cloudflare_AI-F38020?style=flat-square&logo=cloudflare&logoColor=white" alt="Cloudflare AI"/><br/><sub>50+ models<br/>10K neurons/day</sub></td>
|
||
<td align="center" width="150"><img src="https://img.shields.io/badge/Gemini_CLI-8E75B2?style=flat-square&logo=googlegemini&logoColor=white" alt="Gemini CLI"/><br/><sub>gemini-3-flash<br/>180K/mo free</sub></td>
|
||
<td align="center" width="150"><img src="https://img.shields.io/badge/NVIDIA_NIM-76B900?style=flat-square&logo=nvidia&logoColor=white" alt="NVIDIA NIM"/><br/><sub>129 models<br/>~40 RPM free</sub></td>
|
||
<td align="center" width="150"><img src="https://img.shields.io/badge/Cerebras-F15A29?style=flat-square" alt="Cerebras"/><br/><sub>Qwen3 235B<br/>1M tokens/day</sub></td>
|
||
</tr>
|
||
</table>
|
||
|
||
📖 Full machine-readable catalog → [`docs/reference/PROVIDER_REFERENCE.md`](docs/reference/PROVIDER_REFERENCE.md)
|
||
|
||
<br/>
|
||
</div>
|
||
|
||
<div align="center">
|
||
|
||
# 🖥️ Where OmniRoute Runs — Anywhere
|
||
|
||
</div>
|
||
|
||
> 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-lts && 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 |
|
||
|
||
<sub>📖 [Docker Guide](docs/guides/DOCKER_GUIDE.md) · [Desktop](electron/README.md) · [Termux](docs/guides/TERMUX_GUIDE.md) · [PWA](docs/guides/PWA_GUIDE.md) · [OpenCode](docs/frameworks/OPENCODE.md)</sub>
|
||
|
||
<br/>
|
||
|
||
<div align="center">
|
||
|
||
# 🔒 Private & Local-First
|
||
|
||
</div>
|
||
|
||
> Your keys, your machine, your data. OmniRoute is a **local proxy** — it never phones home.
|
||
|
||
- 🏠 **Runs 100% on your hardware** — npm, Docker, desktop, or your phone. No OmniRoute cloud sits in the request path.
|
||
- 🔐 **Credentials encrypted at rest** — API keys & OAuth tokens sealed with **AES-256-GCM**.
|
||
- 🚫 **Zero telemetry by default** — your prompts go only to the providers _you_ choose, nowhere else.
|
||
- 🛡️ **Hardened gateway** — API-key scoping, IP filtering, rate limits, prompt-injection guard, loopback-only process routes.
|
||
- 📜 **MIT licensed & fully open-source** — audit every line, self-host forever.
|
||
|
||
<sub>📖 [Authorization](docs/architecture/AUTHZ_GUIDE.md) · [Guardrails](docs/security/GUARDRAILS.md) · [Compliance](docs/security/COMPLIANCE.md)</sub>
|
||
|
||
<br/>
|
||
|
||
<div align="center">
|
||
|
||
# 🔌 Full CLI + A2A & MCP
|
||
|
||
</div>
|
||
|
||
> OmniRoute isn't just a server — it's a **full command-line cockpit** with **60+ commands**, plus open agent protocols so an AI agent can drive OmniRoute **by itself**.
|
||
|
||
### ⌨️ A real CLI (not just `start`)
|
||
|
||
```bash
|
||
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.
|
||
|
||
```bash
|
||
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.
|
||
<sub>📖 [Remote Mode](docs/guides/REMOTE-MODE.md)</sub>
|
||
|
||
<div align="center">
|
||
|
||
`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` …
|
||
|
||
</div>
|
||
|
||
### 🤝 Connect an agent — and it controls OmniRoute itself
|
||
|
||
Expose OmniRoute over **MCP** or **A2A** and any capable agent gets the keys to the whole gateway — routing, providers, combos, cache, compression, memory — autonomously.
|
||
|
||
| Protocol | Endpoint | Use it for |
|
||
| ------------------ | ----------------------------------------------- | ------------------------------------------------------ |
|
||
| 🧰 **MCP (stdio)** | `omniroute --mcp` | Plug into Claude Desktop, Cursor, any MCP client |
|
||
| 🌊 **MCP (HTTP)** | `http://localhost:20128/api/mcp/stream` | Remote MCP — **87 tools**, 30 scopes, full audit trail |
|
||
| 📡 **MCP (SSE)** | `http://localhost:20128/api/mcp/sse` | Streaming MCP transport |
|
||
| 🤝 **A2A** | `http://localhost:20128/.well-known/agent.json` | Agent-to-agent, **JSON-RPC 2.0** + SSE, 6 skills |
|
||
|
||
```bash
|
||
# Give Claude Code the full OmniRoute toolset over MCP:
|
||
claude mcp add-server omniroute --type http --url http://localhost:20128/api/mcp/stream
|
||
```
|
||
|
||
<sub>📖 [MCP Server](docs/frameworks/MCP-SERVER.md) · [A2A Server](docs/frameworks/A2A-SERVER.md) · [Agent Protocols](docs/frameworks/AGENT_PROTOCOLS_GUIDE.md)</sub>
|
||
|
||
<br/>
|
||
|
||
<div align="center">
|
||
|
||
# 🗜️ Save 15–95% Tokens — Automatically
|
||
|
||
</div>
|
||
|
||
> **Why use many token when few token do trick?** Every request passes through OmniRoute's compression pipeline **transparently** — no client changes. It's now a **stack of 9 composable engines** that run in order and mix & match per routing combo — building on ideas from [RTK](https://github.com/rtk-ai/rtk), [Caveman](https://github.com/JuliusBrussee/caveman) (⭐ 51K+), [LLMLingua-2](https://github.com/microsoft/LLMLingua), and [Troglodita](https://github.com/leninejunior/troglodita) (PT-BR).
|
||
|
||
### 🧱 The 9-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 | **RTK** | Smart tool-result filtering, dedup & truncation (command-aware) |
|
||
| 4 | **Headroom** | Lossless tabular compaction of homogeneous JSON arrays (~30%+) |
|
||
| 5 | **Caveman** | Rule-based prose compression (~65–75% on output) |
|
||
| 6 | **LLMLingua-2** | ML semantic pruning via MobileBERT ONNX — code-safe, async |
|
||
| 7 | **Lite** | Whitespace + image-URL trimming (latency-light baseline) |
|
||
| 8 | **Aggressive** | Summarization + progressive aging of old turns |
|
||
| 9 | **Ultra** | Heuristic token pruning with an optional small-model (SLM) tier |
|
||
|
||
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](https://github.com/leninejunior/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.** ✅
|
||
|
||
<br/>
|
||
|
||
### 📖 How it works — pipeline, architecture & savings math
|
||
|
||
```
|
||
Client (10,000 tok) ──▶ OmniRoute Compression (9 engines) ──▶ Provider (~1,080 tok, up to 95% saved)
|
||
```
|
||
|
||
Default stacked combo runs `RTK → Caveman`. When both act on the same tool/context payload, savings compound:
|
||
|
||
```txt
|
||
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.
|
||
|
||
### 🎚️ Beyond the engines — output styles, the adaptive dial & per-request control
|
||
|
||
The 9 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`](docs/compression/COMPRESSION_GUIDE.md) · [`RTK_COMPRESSION.md`](docs/compression/RTK_COMPRESSION.md) · [`COMPRESSION_ENGINES.md`](docs/compression/COMPRESSION_ENGINES.md)
|
||
|
||
<br/>
|
||
|
||
<div align="center">
|
||
|
||
# ⚡ Quick Start
|
||
|
||
</div>
|
||
|
||
**1) Install & run**
|
||
|
||
```bash
|
||
npm install -g omniroute
|
||
omniroute
|
||
```
|
||
|
||
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 unlimited) or **OpenCode Free** (no auth) → done.
|
||
|
||
**3) Point your coding tool**
|
||
|
||
```txt
|
||
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**
|
||
|
||
```bash
|
||
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:
|
||
|
||
```txt
|
||
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.
|
||
|
||
<br/>
|
||
|
||
## 📦 More install methods — Docker, source, pnpm, Arch
|
||
|
||
**🐳 Docker**
|
||
|
||
```bash
|
||
docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \
|
||
-p 20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest
|
||
```
|
||
|
||
**🛠️ From source**
|
||
|
||
```bash
|
||
cp .env.example .env && npm install
|
||
PORT=20128 npm run dev
|
||
```
|
||
|
||
**📦 pnpm**
|
||
|
||
```bash
|
||
pnpm install -g omniroute && pnpm approve-builds -g && omniroute
|
||
```
|
||
|
||
**🐧 Arch Linux (AUR)**
|
||
|
||
```bash
|
||
yay -S omniroute-bin && systemctl --user enable --now omniroute.service
|
||
```
|
||
|
||
**🔧 Nix (Flake)**
|
||
|
||
```bash
|
||
# Using Nix flakes
|
||
nix develop
|
||
npm run dev
|
||
|
||
# Or using devbox
|
||
devbox run npm run dev
|
||
```
|
||
|
||
📖 [Docker Guide](docs/guides/DOCKER_GUIDE.md) — Compose profiles, Caddy HTTPS, Cloudflare tunnels.
|
||
|
||
**🦭 Podman**
|
||
|
||
```bash
|
||
# 1. Build the image
|
||
podman build --target runner-base -t omniroute:base .
|
||
|
||
# 2. Fix data directory permissions for rootless Podman
|
||
mkdir -p data && podman unshare chown 1000:1000 ./data
|
||
|
||
# 3. Set runtime in .env, then run (see contrib/podman/ for Quadlet)
|
||
echo "CONTAINER_HOST=podman" >> .env
|
||
podman compose --profile base up -d
|
||
```
|
||
|
||
📖 [Podman Guide](contrib/podman/README.md) — Quadlet setup, podman-compose, Quadlet.
|
||
|
||
<br/>
|
||
|
||
<div align="center">
|
||
|
||
# 🎬 OmniRoute in Action
|
||
|
||
</div>
|
||
|
||
<div align="center">
|
||
<table>
|
||
<tr>
|
||
<td align="center" width="280">
|
||
<a href="https://www.youtube.com/watch?v=Rxdc36yUyOQ"><img src="https://img.youtube.com/vi/Rxdc36yUyOQ/maxresdefault.jpg" alt="Guia em Português" width="260"/></a><br/>
|
||
<b>🇧🇷 Português</b><br/><sub>Guia completo</sub>
|
||
</td>
|
||
<td align="center" width="280">
|
||
<a href="https://www.youtube.com/watch?v=CMzyOiUyEVc"><img src="https://img.youtube.com/vi/CMzyOiUyEVc/maxresdefault.jpg" alt="English Guide" width="260"/></a><br/>
|
||
<b>🇺🇸 English</b><br/><sub>Complete walkthrough</sub>
|
||
</td>
|
||
<td align="center" width="280">
|
||
<a href="https://www.youtube.com/watch?v=il_5Ii6v4-Y"><img src="https://img.youtube.com/vi/il_5Ii6v4-Y/maxresdefault.jpg" alt="Руководство" width="260"/></a><br/>
|
||
<b>🇷🇺 Русский</b><br/><sub>Полное руководство</sub>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
|
||
<div align="center">
|
||
|
||
> 🎬 **Made a video about OmniRoute?** Open an [issue](https://github.com/diegosouzapw/OmniRoute/issues/new) or [discussion](https://github.com/diegosouzapw/OmniRoute/discussions) with the link — we'll feature it here.
|
||
|
||
<br/>
|
||
</div>
|
||
|
||
<div align="center">
|
||
|
||
# 📚 Explore More
|
||
|
||
</div>
|
||
|
||
<details>
|
||
<summary><b>💰 Pricing at a glance & the $0 Free Stack (11 providers)</b></summary>
|
||
|
||
<br/>
|
||
|
||
| Tier | Example | Cost |
|
||
| --------------------------- | ---------------------------------------- | ---------- |
|
||
| 💳 **Subscription** | Claude Code Pro / Codex / Copilot | $10–200/mo |
|
||
| 🔑 **API Key (free tiers)** | NVIDIA NIM, Cerebras, Groq | **FREE** |
|
||
| 💰 **Cheap** | GLM-5 $0.5/1M · MiniMax M2.5 $0.3/1M | pennies |
|
||
| 🆓 **Free Forever** | Kiro, Qoder, Qwen, Pollinations, LongCat | **$0** |
|
||
|
||
**The $0 Free Stack — combine into one unbreakable combo:**
|
||
|
||
| Provider | Prefix | Free models | Quota |
|
||
| ----------------- | ----------- | ----------------------------------------------- | ----------------- |
|
||
| **Kiro** | `kr/` | Claude Sonnet 4.5, Haiku 4.5, Opus 4.6 | 50 credits/mo |
|
||
| **Qoder** | `if/` | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 | ♾️ Unlimited |
|
||
| **Qwen** | `qw/` | qwen3-coder-plus/flash/next | ♾️ Unlimited |
|
||
| **Pollinations** | `pol/` | GPT-5, Claude, Gemini, DeepSeek, Llama 4 | No key needed |
|
||
| **LongCat** | `lc/` | LongCat-Flash-Lite | 50M tokens/day 🔥 |
|
||
| **Cloudflare AI** | `cf/` | 50+ models | 10K neurons/day |
|
||
| **NVIDIA NIM** | `nvidia/` | 129 models | ~40 RPM |
|
||
| **Cerebras** | `cerebras/` | Qwen3 235B, GPT-OSS 120B | 1M tok/day |
|
||
|
||
> 💡 The dashboard "cost" is a **savings tracker**, not a bill — OmniRoute never charges you. A "$290 total cost" using free models means **$290 saved**.
|
||
|
||
📖 Complete free directory → [`docs/reference/FREE_TIERS.md`](docs/reference/FREE_TIERS.md) — 25+ providers, quotas, base URLs.
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>🎯 Use Cases — ready-made combo playbooks</b></summary>
|
||
|
||
<br/>
|
||
|
||
**$0 forever:**
|
||
|
||
```
|
||
1. kr/claude-sonnet-4.5 (Kiro — unlimited)
|
||
2. if/kimi-k2-thinking (Qoder — unlimited)
|
||
3. pol/gpt-5 (Pollinations — no key)
|
||
4. lc/longcat-flash-lite (50M tok/day backup)
|
||
Compression: aggressive (~50%) → double your free quota · Cost: $0/mo
|
||
```
|
||
|
||
**24/7 no interruptions:** chain 2 subscriptions → cheap → free for 5 layers of fallback.
|
||
**Blocked region:** free providers + global/per-provider proxy → access AI from any country.
|
||
**Max savings:** subscription + cheap backup + `ultra` compression (~75%) → ~$150–300/mo saved for heavy users.
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>🌍 Bypass geo-blocks — 3-level proxy + stealth</b></summary>
|
||
|
||
<br/>
|
||
|
||
🇷🇺 🇨🇳 🇮🇷 🇨🇺 🇹🇷 In a blocked region? OmniRoute's **3-level proxy** (Global / Per-Provider / Per-Connection) proxies API requests, OAuth flows, connection tests, token refresh & model sync.
|
||
|
||
- **Protocols:** HTTP/HTTPS, SOCKS5, authenticated proxies
|
||
- **🆓 1proxy marketplace** — hundreds of free validated proxies, quality scores, auto-rotation
|
||
- **Anti-detection** — TLS fingerprint spoofing (`wreq-js`), CLI fingerprint matching, proxy IP preservation
|
||
|
||
📖 [`docs/ops/PROXY_GUIDE.md`](docs/ops/PROXY_GUIDE.md)
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>✨ Full feature list — 30+ capabilities (memory, evals, observability)</b></summary>
|
||
|
||
<br/>
|
||
|
||
**Routing:** 15 strategies · task-aware smart routing · thinking budget controls · wildcard routing · system prompt injection.
|
||
**Compatibility:** OpenAI ↔ Claude ↔ Gemini ↔ Responses API · auto OAuth refresh (PKCE, 8 providers) · multi-account round-robin · Batch + Files API · live OpenAPI 3.0.
|
||
**Protocols:** MCP (87 tools, 3 transports, 30 scopes) · A2A (JSON-RPC 2.0, SSE, 6 skills) · ACP · cloud agents (Codex, Devin, Jules).
|
||
**Plugins:** custom plugin marketplace (system-configured registry URL with SSRF-guarded fetch) · install / enable / disable · Notion + Obsidian knowledge-base integrations (WebDAV file server, vault search, note CRUD).
|
||
**Embedded services:** one-click install & lifecycle management of local sidecar services (CLIProxy, NineRouter).
|
||
**Quality & Ops:** built-in **Evals** (golden-set: exact/contains/regex/custom) · guardrails (PII, injection, vision) · health dashboard · p50/p95/p99 telemetry · webhooks · compliance audit.
|
||
**AI Agent Skills:** drop-in markdown manifests — point any agent at a `skills/*/SKILL.md` manifest. 43 skills available.
|
||
|
||
📖 [MCP Server](open-sse/mcp-server/README.md) · [A2A Server](src/lib/a2a/README.md) · [Resilience Guide](docs/architecture/RESILIENCE_GUIDE.md) · [Features Gallery](docs/guides/FEATURES.md)
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>📖 Setup, env vars & FAQ</b></summary>
|
||
|
||
<br/>
|
||
|
||
| Env var | Default | Purpose |
|
||
| ----------------- | -------------- | -------------------------------- |
|
||
| `PORT` | `20128` | API + dashboard port |
|
||
| `REQUIRE_API_KEY` | `false` | Require API key for all requests |
|
||
| `DATA_DIR` | `~/.omniroute` | Database & config storage |
|
||
|
||
**Will I be charged by OmniRoute?** No — it's free, open-source software on your machine. You only pay paid providers directly. OmniRoute has no billing system.
|
||
**Are FREE providers really unlimited?** Yes — Kiro, Qoder, Pollinations, LongCat, Cloudflare. No catch.
|
||
**Will compression hurt quality?** No — it only compresses the **input**; code, URLs, JSON are always protected.
|
||
**Does it work where AI is blocked?** Yes — 3-level proxy + 1proxy marketplace reach all 231 providers.
|
||
|
||
📖 [User Guide](docs/guides/USER_GUIDE.md) · [API Reference](docs/reference/API_REFERENCE.md) · [Environment Config](docs/reference/ENVIRONMENT.md)
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>🐛 Troubleshooting</b></summary>
|
||
|
||
<br/>
|
||
|
||
| Problem | Quick fix |
|
||
| ----------------------------------------- | ------------------------------------------------------------- |
|
||
| "Language model did not provide messages" | Provider quota exhausted → use a combo fallback |
|
||
| Rate limiting (429) | Add fallback: `cc/claude → glm/glm-4.7 → if/kimi-k2-thinking` |
|
||
| OAuth token expired | Auto-refreshed; if stuck, delete + re-auth in Providers |
|
||
| `unsupported_country_region_territory` | Configure proxy in Settings → Proxy |
|
||
| Docker SQLite locks | Use `--stop-timeout 40` for clean WAL checkpoint |
|
||
| Node runtime errors | Use Node `>=22.0.0 <23` or `>=24.0.0 <27` |
|
||
|
||
🐛 **Reporting a bug?** Run `npm run system-info` and attach `system-info.txt`. 📖 [`docs/guides/TROUBLESHOOTING.md`](docs/guides/TROUBLESHOOTING.md)
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>📸 Dashboard screenshots</b></summary>
|
||
|
||
<br/>
|
||
|
||
| Page | Screenshot | Page | Screenshot |
|
||
| ---------- | ------------------------------------------------- | ---------- | --------------------------------------------- |
|
||
| Providers |  | Combos |  |
|
||
| Analytics |  | Health |  |
|
||
| Translator |  | Settings |  |
|
||
| CLI Tools |  | Usage Logs |  |
|
||
|
||
</details>
|
||
|
||
<br/>
|
||
|
||
<div align="center">
|
||
|
||
# 📧 Support & Community
|
||
|
||
> 💬 **Chat with the community** — Discord, Telegram & WhatsApp (🌍 / 🇧🇷) links are at the [top of this README](#-join-the-community).
|
||
|
||
- 🌍 **Website**: [omniroute.online](https://omniroute.online)
|
||
- 🐙 **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
|
||
- 🐛 **Issues**: [report a bug](https://github.com/diegosouzapw/OmniRoute/issues) (attach `npm run system-info` output)
|
||
- 🤝 **Contributing**: see [CONTRIBUTING.md](CONTRIBUTING.md) or pick a `good first issue`
|
||
|
||
</div>
|
||
|
||
---
|
||
|
||
<br/>
|
||
<div align="center">
|
||
|
||
## 🛠️ Tech Stack
|
||
|
||
</div>
|
||
|
||
- **Runtime**: Node.js 22.x or 24.x LTS (24 LTS recommended) — `>=22.0.0 <23 || >=24.0.0 <27`
|
||
- **Language**: TypeScript 6.0 — **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0)
|
||
- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4
|
||
- **Database**: better-sqlite3 (SQLite) + LowDB (JSON legacy) — domain state, proxy logs, MCP audit, routing decisions, memory, skills
|
||
- **Schemas**: Zod (MCP tool I/O validation, API contracts)
|
||
- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)
|
||
- **Streaming**: Server-Sent Events (SSE) + WebSocket bridge (`/v1/ws`)
|
||
- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization
|
||
- **Testing**: Node.js test runner + Vitest (**14,965 test cases** across 517 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)
|
||
- **Website**: [omniroute.online](https://omniroute.online)
|
||
- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
|
||
- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
|
||
- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing
|
||
|
||
<div align="center">
|
||
|
||
<br/>
|
||
|
||
## 📖 Documentation
|
||
|
||
</div>
|
||
|
||
### 📘 Getting Started
|
||
|
||
| Document | Description |
|
||
| -------------------------------------------------------------- | -------------------------------------------------------------------------------- |
|
||
| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
|
||
| [Setup Guide](docs/guides/SETUP_GUIDE.md) | Full install methods, CLI tool configs, protocol setup, timeout tuning |
|
||
| [CLI Tools Guide](docs/reference/CLI-TOOLS.md) | Per-tool setup for Claude Code, Codex, Cursor, Cline, OpenClaw, Kilo, Copilot |
|
||
| [Remote Mode](docs/guides/REMOTE-MODE.md) | Drive a remote OmniRoute (VPS) from your laptop CLI via scoped access tokens |
|
||
| [Claude Code Config](docs/guides/CLAUDE-CODE-CONFIGURATION.md) | Point Claude Code at OmniRoute (local/remote) with `launch` + per-model profiles |
|
||
| [Quick Start](README.md#-quick-start) | 3-step install → connect → configure |
|
||
|
||
### 🔧 Operations & Deployment
|
||
|
||
| Document | Description |
|
||
| -------------------------------------------------------- | -------------------------------------------------------------- |
|
||
| [Docker Guide](docs/guides/DOCKER_GUIDE.md) | Docker run, Compose profiles, Caddy HTTPS, tunnels, image tags |
|
||
| [Podman Guide](contrib/podman/README.md) | Quadlet systemd integration, podman-compose, SELinux |
|
||
| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
|
||
| [Fly.io Deployment](docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) | Deploy to Fly.io with persistent storage |
|
||
| [Termux Guide](docs/guides/TERMUX_GUIDE.md) | Run OmniRoute on Android via Termux |
|
||
| [PWA Guide](docs/guides/PWA_GUIDE.md) | Progressive Web App install, caching, architecture |
|
||
| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods |
|
||
| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references |
|
||
|
||
### 🧠 Features & Architecture
|
||
|
||
| Document | Description |
|
||
| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
|
||
| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture, data flow, and internals |
|
||
| [Compression Guide](docs/compression/COMPRESSION_GUIDE.md) | 7-option pipeline: off / lite / standard / aggressive / ultra / RTK / stacked |
|
||
| [RTK Compression](docs/compression/RTK_COMPRESSION.md) | Command-output compression, filters, trust, verify, raw-output recovery |
|
||
| [Compression Engines](docs/compression/COMPRESSION_ENGINES.md) | Caveman, RTK, stacked pipelines, dashboard/API/MCP surfaces |
|
||
| [Compression Rules Format](docs/compression/COMPRESSION_RULES_FORMAT.md) | JSON rule-pack schemas for Caveman and RTK filters |
|
||
| [Compression Language Packs](docs/compression/COMPRESSION_LANGUAGE_PACKS.md) | Language detection and Caveman rule-pack authoring |
|
||
| [Resilience Guide](docs/architecture/RESILIENCE_GUIDE.md) | Circuit breakers, cooldowns, queue, anti-thundering herd, TLS spoofing |
|
||
| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 9-factor scoring, mode packs, self-healing |
|
||
| [Proxy Guide](docs/ops/PROXY_GUIDE.md) | 3-level proxy system, 1proxy marketplace, registry CRUD |
|
||
| [Free Tiers](docs/reference/FREE_TIERS.md) | 25+ free API providers consolidated directory |
|
||
| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots |
|
||
| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
|
||
|
||
### 🤖 Protocols & APIs
|
||
|
||
| Document | Description |
|
||
| ------------------------------------------------- | --------------------------------------------------- |
|
||
| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples |
|
||
| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
|
||
| [MCP Server](open-sse/mcp-server/README.md) | 87 MCP tools, IDE configs, Python/TS/Go clients |
|
||
| [MCP Server Guide](docs/frameworks/MCP-SERVER.md) | MCP installation, transports, and tool reference |
|
||
| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
|
||
| [A2A Server Guide](docs/frameworks/A2A-SERVER.md) | A2A agent card, tasks, skills, and streaming |
|
||
|
||
### 📋 Project & Quality
|
||
|
||
| Document | Description |
|
||
| -------------------------------------------------- | ----------------------------------------------- |
|
||
| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
|
||
| [Changelog](CHANGELOG.md) | Full per-version release history |
|
||
| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
|
||
| [i18n Guide](docs/guides/I18N.md) | 40+ language support, translation workflow, RTL |
|
||
| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps |
|
||
| [Coverage Plan](docs/ops/COVERAGE_PLAN.md) | Test coverage strategy and 14,965 test suite |
|
||
|
||
<br/>
|
||
|
||
<div align="center">
|
||
|
||
# ⭐ 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.**
|
||
|
||
<table>
|
||
<tr>
|
||
<td align="center" width="160">
|
||
<a href="https://github.com/oyi77">
|
||
<img src="https://github.com/oyi77.png" width="80" style="border-radius:50%" alt="oyi77"/><br/>
|
||
<b>oyi77</b>
|
||
</a><br/>
|
||
<sub>🥇 190 commits • +72K lines</sub><br/>
|
||
<sub>Analytics engine, SQL aggregations,<br/>proxy marketplace, test coverage</sub>
|
||
</td>
|
||
<td align="center" width="160">
|
||
<a href="https://github.com/christopher-s">
|
||
<img src="https://github.com/christopher-s.png" width="80" style="border-radius:50%" alt="Chris Staley"/><br/>
|
||
<b>Chris Staley</b>
|
||
</a><br/>
|
||
<sub>🥈 72 commits • +5.7K lines</sub><br/>
|
||
<sub>SSE stream hardening, Responses API,<br/>Gemini pagination, test regression fixes</sub>
|
||
</td>
|
||
<td align="center" width="160">
|
||
<a href="https://github.com/zenobit">
|
||
<img src="https://github.com/zenobit.png" width="80" style="border-radius:50%" alt="zenobit"/><br/>
|
||
<b>zenobit</b>
|
||
</a><br/>
|
||
<sub>🥉 62 commits • +24K lines</sub><br/>
|
||
<sub>CI/CD pipeline, i18n for 33 languages,<br/>Void Linux package, platform fixes</sub>
|
||
</td>
|
||
<td align="center" width="160">
|
||
<a href="https://github.com/rdself">
|
||
<img src="https://github.com/rdself.png" width="80" style="border-radius:50%" alt="R.D. & Randi"/><br/>
|
||
<b>R.D. & Randi</b>
|
||
</a><br/>
|
||
<sub>🏅 107 commits • +28K lines</sub><br/>
|
||
<sub>Endpoints page, tunnel integrations,<br/>Docker workflows, A2A status, compression UI</sub>
|
||
</td>
|
||
<td align="center" width="160">
|
||
<a href="https://github.com/benzntech">
|
||
<img src="https://github.com/benzntech.png" width="80" style="border-radius:50%" alt="benzntech"/><br/>
|
||
<b>benzntech</b>
|
||
</a><br/>
|
||
<sub>🏅 20 commits • +7.5K lines</sub><br/>
|
||
<sub>Electron desktop app, auto-updater,<br/>release build workflows, cross-platform CI</sub>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
|
||
> 🙏 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.
|
||
|
||
</div>
|
||
|
||
---
|
||
|
||
<br/>
|
||
|
||
<div align="center">
|
||
|
||
## 👥 Contributors
|
||
|
||
</div>
|
||
|
||
[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
|
||
|
||
### How to Contribute
|
||
|
||
1. Fork the repository
|
||
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
|
||
3. Commit your changes (`git commit -m 'Add amazing feature'`)
|
||
4. Push to the branch (`git push origin feature/amazing-feature`)
|
||
5. Open a Pull Request
|
||
|
||
See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
|
||
|
||
### Releasing a New Version
|
||
|
||
```bash
|
||
# Create a release — npm publish happens automatically
|
||
gh release create v3.8.2 --title "v3.8.2" --generate-notes
|
||
```
|
||
|
||
<br/>
|
||
|
||
<div align="center">
|
||
|
||
## 📊 Stars
|
||
|
||
<a href="https://www.star-history.com/?repos=diegosouzapw%2Fomniroute&type=date&legend=top-left">
|
||
<picture>
|
||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&theme=dark&legend=top-left" />
|
||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left" />
|
||
<img alt="Star History Chart" src="https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left" />
|
||
</picture>
|
||
</a>
|
||
</div>
|
||
|
||
<br/>
|
||
|
||
<div align="center">
|
||
|
||
## 🌍 StarMapper
|
||
|
||
<a href="https://starmapper.bruniaux.com/diegosouzapw/omniroute">
|
||
<picture>
|
||
<source media="(prefers-color-scheme: dark)" srcset="https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=dark" />
|
||
<source media="(prefers-color-scheme: light)" srcset="https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=light" />
|
||
<img alt="StarMapper" src="https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute" />
|
||
</picture>
|
||
</a>
|
||
</div>
|
||
|
||
<br/>
|
||
|
||
<div align="center">
|
||
|
||
## 🙏 Acknowledgments
|
||
|
||
</div>
|
||
|
||
OmniRoute stands on the shoulders of giants. It started as a fork of **[9router](https://github.com/decolua/9router)** and a TypeScript port of the Go project **[CLIProxyAPI](https://github.com/router-for-me/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 June 2026 — go give these projects a star.
|
||
|
||
### 🧬 Lineage & gateway
|
||
|
||
| Project | ⭐ | How it inspired OmniRoute |
|
||
| ------------------------------------------------------------------------------- | ----: | ------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| **[9router](https://github.com/decolua/9router)** · decolua | 17.9k | The original project this fork is built on — extended here with multi-modal APIs and a full TypeScript rewrite. |
|
||
| **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** · router-for-me | 37.8k | The Go implementation that inspired this JavaScript / TypeScript port. |
|
||
| **[LiteLLM](https://github.com/BerriAI/litellm)** · BerriAI | 50.8k | 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](https://github.com/JuliusBrussee/caveman)** · JuliusBrussee | 74.5k | 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](https://github.com/rtk-ai/rtk)** · rtk-ai | 63.6k | High-performance command-output compression — inspired our RTK engine, JSON filter DSL, raw-output recovery and the stacked RTK → Caveman pipeline. |
|
||
| **[headroom](https://github.com/chopratejas/headroom)** · chopratejas | 33.6k | Reversible context-compression (SmartCrusher) — inspired our `headroom` engine and the `ccr` retrieve-marker pattern. |
|
||
| **[LLMLingua](https://github.com/microsoft/LLMLingua)** · Microsoft | 6.3k | Prompt-compression research (LLMLingua / LLMLingua-2) — inspired our async, code-safe, fail-open `llmlingua` engine. |
|
||
| **[llmlingua-2-js](https://github.com/atjsh/llmlingua-2-js)** · atjsh | 27 | The JS/ONNX port (MobileBERT / XLM-RoBERTa) used as the worker-thread backend for our LLMLingua engine. |
|
||
| **[Troglodita](https://github.com/leninejunior/troglodita)** · Lenine Júnior | 15 | PT-BR token compression — powers our pt-BR language pack: pleonasm reduction and filler removal tuned for Brazilian-Portuguese grammar. |
|
||
| **[ponytail](https://github.com/DietrichGebert/ponytail)** · DietrichGebert | 51.4k | 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](https://github.com/toon-format/toon)** · toon-format | 24.6k | Token-Oriented Object Notation — its columnar, header-plus-rows model shaped our tabular compaction stage. |
|
||
| **[GCF – Graph Compact Format](https://github.com/blackwell-systems/gcf)** · Blackwell Systems | 11 | Schema-aware "JSON for LLMs" notation — co-inspired our lossless homogeneous-array compaction with `[N rows]` markers. |
|
||
| **[token-optimizer-mcp](https://github.com/ooples/token-optimizer-mcp)** · ooples | 409 | Brotli/SQLite cache + per-session context-delta — inspired our `session-dedup` engine. |
|
||
| **[token-savior](https://github.com/Mibayy/token-savior)** · Mibayy | 993 | Bash-output compaction + MCP profiles — inspired our compression bail-out discipline and MCP tool-manifest reduction. |
|
||
| **[token-saver](https://github.com/ppgranger/token-saver)** · ppgranger | 103 | Content-aware, per-file-type output compression with failure-aware bail-out — validated our per-type dispatch and minimum-gain skip. |
|
||
| **[token-optimizer](https://github.com/alexgreensh/token-optimizer)** · alexgreensh | 1.4k | "Find the ghost tokens" — its offload + recoverable-handle pattern informed our CCR offload thinking. |
|
||
| **[TokenMizer](https://github.com/Shweta-Mishra-ai/tokenmizer)** · Shweta-Mishra-ai | 1 | A session-graph + cross-turn line-dedup blueprint that informed our session-dedup design. |
|
||
| **[OmniCompress](https://github.com/jessefreitas/OmniCompress)** · jessefreitas | 2 | 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](https://github.com/atlassian-labs/mcp-compressor)** · Atlassian Labs | 80 | MCP tool-schema/description compression — informed our MCP tool-manifest cardinality reduction. |
|
||
| **[RepoMapper](https://github.com/pdavis68/RepoMapper)** · pdavis68 | 182 | Aider-style repo-map ranking — informed our repo-map / retrieval-ranking exploration. |
|
||
| **[quiet-shell-mcp](https://github.com/mrsimpson/quiet-shell-mcp)** · mrsimpson | 4 | Declarative shell-output reduction over MCP — validated our declarative bash-output compaction. |
|
||
| **[ts-morph](https://github.com/dsherret/ts-morph)** · David Sherret | 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](https://github.com/mem0ai/mem0)** · mem0ai | 58.9k | Universal memory layer — its proxy-as-write/read-boundary model shaped our memory architecture. |
|
||
| **[Letta (MemGPT)](https://github.com/letta-ai/letta)** · letta-ai | 23.4k | Stateful agents with tiered memory — inspired our Context Control & Recovery (CCR) tiered model. |
|
||
| **[WFGY](https://github.com/onestardao/WFGY)** · onestardao | 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](https://github.com/chouzz/llm-interceptor)** · chouzz | 46 | MITM interception/analysis of coding-assistant ↔ LLM traffic — our Traffic Inspector ports its SSE merge, conversation normalization, host passthrough and secret masking (MIT). |
|
||
| **[ProxyBridge](https://github.com/InterceptSuite/ProxyBridge)** · InterceptSuite | 5.1k | 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](https://github.com/anomalyco/models.dev)** · SST / OpenCode | 5.1k | Open database of AI model specs, pricing and capabilities — synced natively into our model catalog. |
|
||
| **[React Flow / xyflow](https://github.com/xyflow/xyflow)** · xyflow | 37.1k | The node-based graph library powering our real-time Compression Studio and Combo/Routing Studio. |
|
||
| **[LangGraph](https://github.com/langchain-ai/langgraph)** · LangChain | 35.1k | LangGraph Studio's live workflow-graph visualization inspired our Studios' real-time cascade view. |
|
||
| **[Langfuse](https://github.com/langfuse/langfuse)** · Langfuse | 29.3k | Its trace → span → generation observability model shaped our Compression Studio waterfall. |
|
||
| **[Kiali](https://github.com/kiali/kiali)** · Kiali | 3.6k | Istio service-mesh observability — inspired our circuit-breaker badges and error-edge visuals in the Routing/Combo Studio. |
|
||
| **[lobe-icons](https://github.com/lobehub/lobe-icons)** · LobeHub | 2.1k | AI/LLM brand logos that render the provider icons across our dashboard. |
|
||
|
||
### 🛡️ Security
|
||
|
||
| Project | ⭐ | How it inspired OmniRoute |
|
||
| ------------------------------------------------------------------------------------------- | --: | ------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||
| **[awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults)** · tldrsec | 708 | A curated list of secure-by-default libraries that guides our security choices (Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink). |
|
||
|
||
## ❤️ Support
|
||
|
||
OmniRoute is free and open source, built and maintained in the open. If it saves you time or money, consider supporting development:
|
||
|
||
- ⭐ **Star the repo** — it genuinely helps visibility
|
||
- 💖 **[GitHub Sponsors](https://github.com/sponsors/diegosouzapw)** — fund ongoing maintenance and new providers
|
||
- 🐛 **Report bugs and share feedback** in [Discussions](https://github.com/diegosouzapw/OmniRoute/discussions)
|
||
|
||
## 📄 License
|
||
|
||
MIT License - see [LICENSE](LICENSE) for details.
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
|
||
**[⬆ Back to top](#-omniroute)** · Built with ❤️ for the open-source AI community.
|
||
|
||
<sub>OmniRoute v3.8.24 · Node ≥22.0.0 · MIT License · <a href="https://omniroute.online">omniroute.online</a></sub>
|
||
|
||
</div>
|
||
<!-- GitHub Discussions enabled for community Q&A -->
|