diff --git a/docs/i18n/pl/README.md b/docs/i18n/pl/README.md index a58a00d9b8..e126dd7204 100644 --- a/docs/i18n/pl/README.md +++ b/docs/i18n/pl/README.md @@ -1,2208 +1,993 @@ -# 🚀 OmniRoute — The Free AI Gateway (Polski) +
-🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇸🇦 [ar](../ar/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇧🇩 [bn](../bn/README.md) · 🇨🇿 [cs](../cs/README.md) · 🇩🇰 [da](../da/README.md) · 🇩🇪 [de](../de/README.md) · 🇪🇸 [es](../es/README.md) · 🇮🇷 [fa](../fa/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇮🇳 [gu](../gu/README.md) · 🇮🇱 [he](../he/README.md) · 🇮🇳 [hi](../hi/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇮🇩 [id](../id/README.md) · 🇮🇹 [it](../it/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇮🇳 [mr](../mr/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇳🇴 [no](../no/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇰🇪 [sw](../sw/README.md) · 🇮🇳 [ta](../ta/README.md) · 🇮🇳 [te](../te/README.md) · 🇹🇭 [th](../th/README.md) · 🇹🇷 [tr](../tr/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇵🇰 [ur](../ur/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) +OmniRoute Dashboard ---- +
-### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback. +# 🚀 OmniRoute — Darmowa bramka AI -_Your universal API proxy — one endpoint, 100+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._ +OmniRoute — Nigdy nie przestawaj kodować. Każde narzędzie AI → 268 dostawców — ponad 90 darmowych — przez jeden punkt końcowy. Claude Code, Codex, Cursor, Cline, Copilot i Antigravity w DARMOWE Claude / GPT / Gemini z automatycznym przekierowaniem (auto-fallback). Kaskadowa kompresja RTK + Caveman oszczędza 15–95% tokenów (średnio ~89%) — nigdy nie przekraczaj limitów. 268 dostawców AI · ponad 90 darmowych pakietów · ~1,4 mld darmowych tokenów/mies. · 18 strategii routingu · 0 USD na start. -**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript** - ---- +
+# 💰 ~1,4 mld darmowych tokenów / miesiąc + +
+ +> Ręczne łączenie darmowych pakietów jest uciążliwe — dziesiątki SDK, dziesiątki limitów zapytań (rate limits) i brak wiedzy, ile tak naprawdę Ci pozostało. OmniRoute agreguje **udokumentowane** darmowe pakiety z **39 pul dostawców / ponad 460 modeli** w jedną rzetelną liczbę i wyświetla ją na żywo w panelu (`/dashboard/free-tiers`). + +Karta budżetu darmowych pakietów OmniRoute: stabilne ~1,4 mld darmowych tokenów miesięcznie, do ~2,0 mld w pierwszym miesiącu dzięki kredytom na start, z udokumentowanych darmowych poziomów 39 pul dostawców / ponad 460 modeli za jednym punktem końcowym. Rzetelne wyliczenia z deduplikacją puli — każda współdzielona pula liczona raz (liczenie każdego limitu zapytań 24/7 dałoby ~10 mld; niepublikowane), 15 dostawców oflagowanych ze względu na Warunki Świadczenia Usług (ToS), więc decyzja należy do Ciebie. Pasek budżetu 19 mierzalnych darmowych pul z siatką modeli (Mistral Large 3 1B, GPT-4o mini 150M, Gemini 2.5 Flash 60M … Claude Sonnet 4.5 25K), ~626M jednorazowych kredytów startowych w pierwszym miesiącu (vertex 300M, agentrouter 200M, predibase 25M, together 25M, glm-cn 20M, doubao 15M, ai21 10M, longcat 10M, deepseek 5M, hyperbolic 5M, nscale 5M), plus stale darmowi dostawcy bez limitu tokenów (SiliconFlow, Z.AI GLM-Flash, Kilo, OpenCode Zen, baidu …) oraz doładowanie OpenRouter za 10 USD odblokowujące +24M/mies. — przedstawione osobno, aby nie sztucznie zawyżać głównego nagłówka. Zużycie/pozostało na żywo na /dashboard/free-tiers. + +> Animowane podsumowanie strony `/dashboard/free-tiers` na żywo. Pełna metodologia (deduplikacja pul, pakiety kredytów, warunki dostawców): **[docs/reference/FREE_TIERS.md](../../../docs/reference/FREE_TIERS.md)**. +> +> Liczby te są ponownie weryfikowane co dwa tygodnie na podstawie aktualnego katalogu i **mogą się zmieniać w obie strony** — gdy dostawca kończy darmowy pakiet, liczba spada; gdy pojawia się nowy, rośnie. Publikujemy to, co faktycznie oblicza katalog, nigdy zaokrąglony w górę, optymistyczny wariant. Bramka CI (`check:docs-counts`) powoduje błąd budowania projektu, jeśli nagłówek rozbiega się z kodem. + +
+ +

+ +⭐ Dodaj gwiazdkę do repozytorium, jeśli OMNIROUTE pomógł Ci zaoszczędzić pieniądze i ułatwił pracę. + +

+ +[![Stars](https://img.shields.io/github/stars/diegosouzapw/OmniRoute?style=social)](https://github.com/diegosouzapw/OmniRoute) +diegosouzapw%2FOmniRoute | Trendshift +[![Star History Rank](https://api.star-history.com/badge?repo=diegosouzapw/OmniRoute&theme=dark)](https://www.star-history.com/diegosouzapw/omniroute) + +
+ +### 💬 Dołącz do społeczności + +[![Discord](https://img.shields.io/badge/Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/U47eFqAXCn) +[![Telegram](https://img.shields.io/badge/Telegram-26A5E4?style=for-the-badge&logo=telegram&logoColor=white)](https://t.me/omnirouteOficial) +[![WhatsApp Global](https://img.shields.io/badge/WhatsApp_Global-25D366?style=for-the-badge&logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) +[![WhatsApp Brasil](https://img.shields.io/badge/WhatsApp_Brasil-25D366?style=for-the-badge&logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/LTSpdFhXTxjH4R6CCNiKWz) +[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online) + +**Pytania, wskazówki dotyczące dostawców, plany rozwoju (roadmap) i wsparcie → [Discord](https://discord.gg/U47eFqAXCn) · [Telegram](https://t.me/omnirouteOficial) · WhatsApp [🌍 Global](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) / [🇧🇷 Brasil](https://chat.whatsapp.com/LTSpdFhXTxjH4R6CCNiKWz)** + +
+ +### 🧩 Dostępne + [![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute) +![NPM Monthly](https://img.shields.io/npm/dm/omniroute?label=npm/month&color=cb3837&logo=npm) [![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](../../../LICENSE) +![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute?label=docker%20pulls&logo=docker&color=2496ED) +![Electron Downloads](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=electron%20downloads&logo=electron&color=47848F) -![NPM Downloads](https://img.shields.io/npm/dw/omniroute?label=npm%20down%20week&color=red) -![NPM Downloads](https://img.shields.io/npm/dm/omniroute?label=npm%20down%20month&color=red) +[**🚀 Szybki start**](#-szybki-start) • [**🎯 Komba**](#-komba-combos--flagowa-funkcja) • [**🌐 Dostawcy**](#-268-dostawc%C3%B3w-ai--ponad-90-darmowych) • [**🔌 CLI & MCP**](#-pe%C5%82ne-cli--a2a-i-mcp) • [**🗜️ Kompresja**](#%EF%B8%8F-oszcz%C4%99dzaj-1595-token%C3%B3w--automatycznie) • [**🌍 Strona WWW**](https://omniroute.online) -![NPM Downloads](https://img.shields.io/npm/d18m/omniroute?label=npm%20down%20year&color=red) -![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute) -![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=eletron%20donwloads&color=blue) - -[![stars](https://custom-icon-badges.demolab.com/github/stars/diegosouzapw/OmniRoute?logo=star&style=flat)](https://github.com/diegosouzapw/OmniRoute/stargazers) -[![open issues](https://custom-icon-badges.demolab.com/github/issues-raw/diegosouzapw/OmniRoute?logo=issue)](https://github.com/diegosouzapw/OmniRoute/issues) -[![license](https://custom-icon-badges.demolab.com/github/license/diegosouzapw/OmniRoute?logo=law)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE) -[![last commit](https://custom-icon-badges.demolab.com/github/last-commit/diegosouzapw/OmniRoute?logo=history&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/commits/main) -[![total contributions](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=graph&logoColor=fff&color=blue&label=total%20contributions&query=%24.totalContributions&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw) -[![code size](https://custom-icon-badges.demolab.com/github/languages/code-size/diegosouzapw/OmniRoute?logo=file-code&logoColor=white)](https://github.com/diegosouzapw/OmniRoute) -[![pr closed](https://custom-icon-badges.demolab.com/github/issues-pr-closed/diegosouzapw/OmniRoute?color=purple&logo=git-pull-request&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/pulls?q=is%3Apr+is%3Aclosed) -[![tag](https://custom-icon-badges.demolab.com/github/v/tag/diegosouzapw/OmniRoute?logo=tag&logoColor=white)](https://github.com/diegosouzapw/OmniRoute/tags) -[![github streak](https://custom-icon-badges.demolab.com/badge/dynamic/json?logo=fire&logoColor=fff&color=orange&label=github%20streak&query=%24.currentStreak.length&suffix=%20days&url=https%3A%2F%2Fstreak-stats.demolab.com%2F%3Fuser%3Ddiegosouzapw%26type%3Djson)](https://github.com/diegosouzapw) -[![followers](https://custom-icon-badges.demolab.com/github/followers/diegosouzapw?logo=person-add)](https://github.com/diegosouzapw?tab=followers) -[![fork](https://custom-icon-badges.demolab.com/github/forks/diegosouzapw/OmniRoute?logo=fork)](https://github.com/diegosouzapw/OmniRoute/network/members) -[![watch](https://custom-icon-badges.demolab.com/github/watchers/diegosouzapw/OmniRoute?logo=eye)](https://github.com/diegosouzapw/OmniRoute/watchers) - -[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE) -[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online) -[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) - -[🌐 Website](https://omniroute.online) • [🚀 Quick Start](#-quick-start) • [💡 Features](#-key-features) • [📖 Docs](#-documentation) • [💰 Pricing](#-pricing-at-a-glance) • [💬 WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) +[💥 Obietnica](#-obietnica) • [🤔 Dlaczego](#-dlaczego-omniroute) • [🏆 Co wyróżnia OmniRoute](#-co-wyr%C3%B3%C5%BCnia-omniroute) • [🤖 Zgodne CLI](#-zgodne-cli-i-agenci-koduj%C4%85cy) • [🖥️ Gdzie to działa](#%EF%B8%8F-gdzie-dzia%C5%82a-omniroute--wsz%C4%99dzie) • [🔒 Prywatność](#-prywatno%C5%9B%C4%87-i-lokalne-dzia%C5%82anie-local-first) • [🎬 W akcji](#-omniroute-w-akcji) • [📸 Zrzuty ekranu](#-zrzuty-ekranu-z-panelu) • [📧 Wsparcie](#-wsparcie-i-spo%C5%82eczno%C5%9B%C4%87)
-🌐 **Available in:** 🇺🇸 [English](README.md) | 🇧🇷 [Português (Brasil)](docs/i18n/pt-BR/README.md) | 🇪🇸 [Español](docs/i18n/es/README.md) | 🇫🇷 [Français](docs/i18n/fr/README.md) | 🇮🇹 [Italiano](docs/i18n/it/README.md) | 🇷🇺 [Русский](docs/i18n/ru/README.md) | 🇨🇳 [中文 (简体)](docs/i18n/zh-CN/README.md) | 🇩🇪 [Deutsch](docs/i18n/de/README.md) | 🇮🇳 [हिन्दी](docs/i18n/in/README.md) | 🇹🇭 [ไทย](docs/i18n/th/README.md) | 🇺🇦 [Українська](docs/i18n/uk-UA/README.md) | 🇸🇦 [العربية](docs/i18n/ar/README.md) | 🇯🇵 [日本語](docs/i18n/ja/README.md) | 🇻🇳 [Tiếng Việt](docs/i18n/vi/README.md) | 🇧🇬 [Български](docs/i18n/bg/README.md) | 🇩🇰 [Dansk](docs/i18n/da/README.md) | 🇫🇮 [Suomi](docs/i18n/fi/README.md) | 🇮🇱 [עברית](docs/i18n/he/README.md) | 🇭🇺 [Magyar](docs/i18n/hu/README.md) | 🇮🇩 [Bahasa Indonesia](docs/i18n/id/README.md) | 🇰🇷 [한국어](docs/i18n/ko/README.md) | 🇲🇾 [Bahasa Melayu](docs/i18n/ms/README.md) | 🇳🇱 [Nederlands](docs/i18n/nl/README.md) | 🇳🇴 [Norsk](docs/i18n/no/README.md) | 🇵🇹 [Português (Portugal)](docs/i18n/pt/README.md) | 🇷🇴 [Română](docs/i18n/ro/README.md) | 🇵🇱 [Polski](docs/i18n/pl/README.md) | 🇸🇰 [Slovenčina](docs/i18n/sk/README.md) | 🇸🇪 [Svenska](docs/i18n/sv/README.md) | 🇵🇭 [Filipino](docs/i18n/phi/README.md) | 🇨🇿 [Čeština](docs/i18n/cs/README.md) - ---- - -## 🖼️ Main Dashboard -
- OmniRoute Dashboard + 🌐 W 43 językach + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
🇺🇸🇧🇷🇵🇹🇪🇸🇫🇷🇮🇹🇩🇪🇳🇱🇷🇺🇺🇦🇵🇱🇨🇿🇸🇰🇷🇴🇭🇺
🇧🇬🇩🇰🇫🇮🇳🇴🇸🇪🇨🇳🇹🇼🇯🇵🇰🇷🇹🇭🇻🇳🇮🇩🇲🇾🇵🇭
🇮🇳🇮🇳🇮🇳🇮🇳🇮🇳🇮🇳🇧🇩🇵🇰🇮🇷🇸🇦🇮🇱🇹🇷🇦🇿🇹🇿
---- +
-## 📸 Dashboard Preview +# 💥 Obietnica -
-Click to see dashboard screenshots +
-| Page | Screenshot | -| -------------- | ------------------------------------------------- | -| **Providers** | ![Providers](docs/screenshots/01-providers.png) | -| **Combos** | ![Combos](docs/screenshots/02-combos.png) | -| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) | -| **Health** | ![Health](docs/screenshots/04-health.png) | -| **Translator** | ![Translator](docs/screenshots/05-translator.png) | -| **Settings** | ![Settings](docs/screenshots/06-settings.png) | -| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) | -| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) | -| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) | +Obietnica — Jeden punkt końcowy. 268 dostawców. Nigdy nie przestawaj tworzyć — OmniRoute wybiera najtańsze działające rozwiązanie. Sześć filarów: Nigdy nie napotykaj limitów (automatyczne przełączanie między 268 dostawcami w milisekundy, zero przestojów) · Oszczędzaj do 95% tokenów (kaskadowa kompresja RTK + Caveman zmniejsza zużycie o 15–95%, średnio ~89% w sesjach z intensywnym użyciem narzędzi) · 0 USD na start (90+ darmowych pakietów, 40+ darmowych na zawsze — bez karty) · Każde narzędzie działa (26 agentów kodujących przez jedną konfigurację) · Jeden punkt końcowy (OpenAI ↔ Claude ↔ Gemini ↔ API Responses na /v1) · Klasa produkcyjna (wyłączniki awaryjne [circuit breakers], maskowanie TLS [TLS stealth], 104 narzędzia MCP, A2A, pamięć, barierki ochronne [guardrails], ewaluacje — ponad 25 000 testów). - +
+
---- +
-### 🤖 Free AI Provider for your favorite coding agents +# 🤔 Dlaczego OmniRoute? -_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._ +
- - - - - - - - - - - - - - -
- - OpenClaw
- OpenClaw -
- ⭐ 205K - 		- - NanoBot
- NanoBot -
- ⭐ 20.9K - 		- - PicoClaw
- PicoClaw -
- ⭐ 14.6K - 		- - ZeroClaw
- ZeroClaw -
- ⭐ 9.9K - 		- - IronClaw
- IronClaw -
- ⭐ 2.1K -
- - OpenCode
- OpenCode -
- ⭐ 106K - 		- - Codex CLI
- Codex CLI -
- ⭐ 60.8K - 		- - Claude Code
- Claude Code -
- ⭐ 67.3K - 		- - Kilo Code
- Kilo Code -
- ⭐ 15.5K -
+Dlaczego OmniRoute — koniec z żonglowaniem 10 panelami, niedziałającymi kluczami API i niespodziewanymi rachunkami. Dziesięć codziennych problemów vs rozwiązania: wygasające niewykorzystane limity → maksymalizacja subskrypcji; limity zapytań w trakcie kodowania → 4-poziomowe automatyczne przełączanie (Subskrypcja → API → Tanie → Darmowe); wyniki narzędzi marnujące tokeny → kompresja RTK + Caveman (15–95%); drogie API → routing zoptymalizowany pod kątem kosztów; każde narzędzie z osobną konfiguracją → jeden punkt końcowy, jeden panel; blokowanie AI → 3-poziomowe proxy + maskowanie TLS; niedziałające klucze → 3-warstwowa odporność (wyłączniki awaryjne, schładzanie kluczy, blokada modelu); zespół dzielący jedną subskrypcję → pule kluczy z limitami sprawiedliwego podziału (fair-share); prompty przesyłane przez zewnętrzną chmurę → lokalne uruchomienie z kluczami szyfrowanymi AES-256-GCM; brak widoczności wydatków → analityka na żywo (użycie, limit, oszczędności, opóźnienie p95). -📡 All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 — one config, unlimited models and quota +
---- +Przepływ żądań OmniRoute: Twoje IDE lub CLI (Claude Code, Cursor, Cline…) wywołuje jeden lokalny punkt końcowy (http://localhost:20128/v1); inteligentny router OmniRoute (kompresja RTK + Caveman, 18 strategii routingu, wyłączniki awaryjne, maskowanie TLS, MCP, A2A, barierki ochronne) automatycznie przełącza się między 4 poziomami dostawców — Poziom 1 Subskrypcja (Claude Code, Codex, Copilot), brak limitu? Poziom 2 Klucz API (DeepSeek, Groq, xAI), przekroczony budżet? Poziom 3 Tanie (GLM $0.5, MiniMax $0.2), przekroczony budżet? Poziom 4 Darmowe (Kiro, Qoder, Pollinations) — zawsze włączone. -## 🤔 Why OmniRoute? +
-**Stop wasting money and hitting limits:** +
-- Subscription quota expires unused every month -- Rate limits stop you mid-coding -- Expensive APIs ($20-50/month per provider) -- Manual switching between providers +
-**OmniRoute solves this:** +# 🎯 Komba (Combos) — Flagowa funkcja -- ✅ **Maximize subscriptions** - Track quota, use every bit before reset -- ✅ **Auto fallback** - Subscription → API Key → Cheap → Free, zero downtime -- ✅ **Multi-account** - Round-robin between accounts per provider +
---- +> **Kombo** to łańcuch modeli, po których OmniRoute nawiguje **automatycznie**. Wybucha limit, dostawca ulega awarii lub koszty gwałtownie rosną — kombo bezgłośnie przełącza się na kolejny model. **To właśnie sprawia, że OmniRoute jest niezawodny.** 🛡️ -## 📧 Support +### ⚡ Zero konfiguracji — po prostu użyj `auto` -> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated. +Nie musisz tworzyć żadnego komba. Ustaw swój model na `auto` (lub jego wariant), a OmniRoute zbuduje wirtualne kombo z Twoich połączonych dostawców, oceniane na żywo: -- **Website**: [omniroute.online](https://omniroute.online) -- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute) -- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) -- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue` +| Identyfikator modelu | Pod kątem czego optymalizuje | +| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | +| `auto` | 🎯 Zbalansowana wartość domyślna (LKGP — trzyma się ostatniego dobrego dostawcy) | +| `auto/coding` | 🧑‍💻 Wagi zorientowane na jakość przy generowaniu kodu | +| `auto/fast` | ⚡ W pierwszej kolejności najniższe opóźnienia | +| `auto/cheap` | 💰 W pierwszej kolejności najtańsze za token | +| `auto/offline` | 🔋 W pierwszej kolejności największy zapas limitu (quota / rate-limit) | +| `auto/smart` | 🔭 Najpierw jakość + 10% eksploracji w celu odkrycia lepszych modeli | -### 🐛 Reporting a Bug? -When opening an issue, please run the system-info command and attach the generated file: +### 🔀 Albo zbuduj własne — 18 strategii routingu + +Wszystkie **18** strategii — łącz i dopasowuj na każdym kroku komba: + +| # | Strategia | Co robi | +| --- | ------------------- | ------------------------------------------------------------------------------------------------------------------------ | +| 1 | `priority` | Uporządkowana lista według priorytetu — zużyj każdy cel przed przejściem do kolejnego 🥇 | +| 2 | `fill-first` | Wypełnij całkowicie limit każdego celu przed pójściem dalej | +| 3 | `weighted` | Wybór losowy ważony według wagi przypisanej do celu | +| 4 | `round-robin` | Przechodzenie przez cele po kolei (Round-Robin) | +| 5 | `p2c` | Losowe równoważenie obciążenia metodą "wybierz dwa, weź lepszy" (P2C) | +| 6 | `least-used` | Wybierz cel o najniższym aktualnym obciążeniu | +| 7 | `random` | Jednolity losowy wybór (ze skreśleniem powtórzeń) | +| 8 | `strict-random` | Losowo bez usuwania duplikatów 🎲 | +| 9 | `cost-optimized` | Minimalizuj koszt w USD za zapytanie na podstawie cennika w katalogu na żywo 💸 | +| 10 | `headroom` | Wybierz cel z największym pozostałym limitem | +| 11 | `reset-window` | Preferuj cel, którego okno limitu resetuje się najszybciej | +| 12 | `reset-aware` | Klasyfikuj według czasu resetu limitu — najpierw krótkie okna 📊 | +| 13 | `context-relay` | Przekazuj kontekst między celami przy długich rozmowach 🧠 | +| 14 | `context-optimized` | Wybierz cel najlepiej dopasowany do bieżącego rozmiaru kontekstu | +| 15 | `lkgp` | Ostatnia znana dobra ścieżka (LKGP) — trzyma się ostatniego udanego celu | +| 16 | `auto` | Ocenianie na żywo na podstawie 12 czynników dla każdego połączenia 🤖 | +| 17 | `fusion` | Rozesłanie zapytania do panelu modeli + sędzia syntetyzuje jedną odpowiedź (Fusion) 🧬 | +| 18 | `pipeline` | Łączenie kroków — wyjście każdego celu zasila kolejny 🔗 | + +Wszystkie 18 strategii routingu komba w formie animowanej, po jednym kafelku na strategię pokazującym realizowany przepływ: priority (zużyj pierwszy, potem kolejny), fill-first (wypełnij limit celu, potem idź dalej), weighted (losowy ważony), round-robin (cyklicznie w kolejności), p2c (wybierz dwa, weź lżejszy), least-used (wygrywa najniższe obciążenie), random (jednolity, bez powtórzeń), strict-random (powtórzenia dozwolone), cost-optimized (najtańszy $ za zapytanie), headroom (najwięcej pozostałego limitu), reset-window (resetuje się najszybciej → użyj go), reset-aware (klasyfikacja wg resetu, krótkie najpierw), context-relay (przekazywanie długiego kontekstu), context-optimized (dopasowanie do rozmiaru kontekstu), lkgp (trzymaj się ostatniego sukcesu), auto (ocenianie na żywo na bazie 12 czynników), fusion (panel + sędzia → jedna odpowiedź), pipeline (każde wyjście zasila kolejne). + +Silnik Auto-Combo ocenia każdego kandydata na podstawie **12 czynników** (stan techniczny, limit, koszt, opóźnienie, wskaźnik sukcesu, aktualność…) — zobacz [`docs/routing/AUTO-COMBO.md`](docs/routing/AUTO-COMBO.md). + + +### ⚖️ Quota-Share — podziel jedną subskrypcję w zespole ✨ NOWOŚĆ + +> Uruchamiasz kilka kluczy na tym **samym koncie nadrzędnym** (jeden plan Codex Pro, jeden klucz Kimi, jedno stanowisko GLM Coding)? Nagły skok zużycia na jednym kluczu może wyczerpać cały 5-godzinny / godzinny limit i zablokować wszystkich innych. **Quota-Share** rozdziela limit czasowy dostawcy **sprawiedliwie** pomiędzy klucze w puli — a dzięki zasadzie _oszczędzania pracy (work-conserving)_, nieużywana część limitu bezczynnego członka jest wypożyczana innym, zamiast się marnować. + +| Suwak / Opcja | Co kontroluje | +| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| ⚖️ **Waga alokacji** | udział każdego klucza w puli — np. `50 / 30 / 20` | +| 📐 **Wymiary** | śledzenie `%` · zapytań · tokenów · `$`, w oknie **5h / 7d / na model** | +| 🚦 **Polityka** | `hard` (blokuj po przekroczeniu) · `soft` (obniż priorytet) · `burst` (użyj wolnego zapasu) | +| 🧱 **Limit max (Cap)** | bezwzględny limit na klucz, niezależny od trybu | + +Pula kluczy OmniRoute 'team-codex': jedno konto Codex Pro dzielone przez 3 klucze w 5-godzinnym oknie. alice waga 50 (do 50% współdzielonego limitu 5h), bob waga 30, ci-bot waga 20. W trybie łagodnym (poniżej 50% zużycia puli) wolne udziały są wypożyczane; gdy pula przekroczy 50%, tryb rygorystyczny ogranicza każdy klucz do jego sprawiedliwego udziału. + +Wymuszane na "gorącej ścieżce" **zanim** żądanie opuści OmniRoute, z limitami na parę (klucz, model) + zachowaniem sesyjności (session stickiness) dla spójności pamięci podręcznej promptów (teraz z przełącznikiem wyłączania dla komba / globalnie). 📖 [Silnik Quota Sharing](../../../docs/routing/QUOTA_SHARE.md) + + +### 🧱 Odporność jest wbudowana (3 niezależne warstwy) + +Odporność OmniRoute — 3 niezależne, samonaprawiające się warstwy, właściwa warstwa dla właściwego rodzaju awarii. Warstwa 1: wyłącznik awaryjny dostawcy (cały dostawca): aktywuje się tylko przy błędach 408/5xx, progi OAuth 3× / klucz API 5× / lokalny 2×, resetuje się po 60s/30s/15s przechodząc w próbny stan HALF-OPEN, powolne przywracanie; w stanie OPEN kombo przekierowuje ruch do kolejnego dostawcy. Warstwa 2: czas schładzania połączenia (jeden klucz/konto): bazowo 5s dla OAuth / 3s dla klucza API, wykładnicze opóźnienie ×2 z zabezpieczeniem przed kumulacją zapytań (anti-thundering-herd), błąd 429 respektuje nagłówek Retry-After, sukces resetuje stan błędów; schładzany klucz jest pomijany, podczas gdy sąsiednie klucze nadal obsługują ruch. Warstwa 3: blokada modelu (jeden model): błąd 429 dla konkretnego modelu, lokalny błąd 404 lub odmowy dostępu blokują tylko ten model — nigdy całe połączenie. Stany terminalne (zablokowany, wygasły, wyczerpane środki) są przeznaczone dla operatora, nie dla mechanizmów schładzania. + +📖 [Silnik Auto-Combo](docs/routing/AUTO-COMBO.md) · [Podręcznik odporności](../../../docs/architecture/RESILIENCE_GUIDE.md) + +
+ +
+ +# 🏆 Co wyróżnia OmniRoute + +
+ +| Funkcja | OmniRoute | Inne routery | +| -------------------------------------- | ------------------------------------------------------------------- | ------------- | +| 🌐 Dostawcy | **268** | 20–100 | +| 🆓 Darmowi dostawcy | **90+ (40+ darmowych na zawsze)** | 1–5 | +| 🔀 Strategie routingu | **18** (priorytetowa, ważona, zoptymalizowana pod kątem kosztów, przekazywanie kontekstu, fusion…) | 1–3 | +| 🗜️ Kompresja tokenów | **Kaskadowa RTK + Caveman (15–95%)** | Brak / 20–40% | +| 🧰 Wbudowany serwer MCP | **104 narzędzia, 3 protokoły transportowe, 31 zakresów** | Rzadkość | +| 🤝 Protokół agenta A2A | **6 umiejętności, JSON-RPC 2.0** | Brak | +| 🧠 Pamięć (FTS5 + wektorowa) | **Tak** | Rzadkość | +| 🛡️ Barierki ochronne (PII, wstrzykiwanie promptów, wizja) | **Tak** | Rzadkość | +| ☁️ Agenci chmurowi | **Codex, Cursor, Devin, Jules** | Brak | +| 🥷 Maskowanie sygnatury TLS | **JA3/JA4 przez wreq-js** | Brak | +| 🖥️ Wieloplatformowość | **Web · Desktop · Termux · PWA** | Tylko Web | +| 🌍 i18n (lokalizacja) | **43 języki** | 0–4 | + +📊 Szczegółowe porównanie z LiteLLM, OpenRouter i Portkey → [`docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md`](../../../docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md) + +
+ +
+ +# ✨ Co nowego + +
+ +> Najważniejsze nowości z wersji **v3.8.20 → v3.8.49**. Pełna historia w [`CHANGELOG.md`](CHANGELOG.md). + +- **🗜️ Wzmocnienie kompresji** — domyślnie włączone zabezpieczenie przed nadmiernym rozrostem (inflation guard), pakiety Caveman dla DE / FR / JA + chińskiego (wényán), filtry RTK dla Gradle i .NET. → [Kompresja](../../../docs/compression/COMPRESSION_ENGINES.md) +- **💸 Rzetelny koszt ryczałtowy** — dostawcy subskrypcyjni / planów kodowania wykazują koszt **0 USD** w analityce; budżet, limit i routing nadal działają szacunkowo. → [Referencja API](docs/reference/API_REFERENCE.md) +- **⚖️ Routing Quota-Share** — podział obciążenia kont według _dostępnego limitu_: harmonogramowanie DRR, współbieżność na połączenie, wielookienkowe pule, zachowanie sesyjności (session stickiness). → [Podręcznik odporności](../../../docs/architecture/RESILIENCE_GUIDE.md) +- **🤖 Konfiguracja CLI/agenta jednym poleceniem** — `setup-*` konfiguruje ponad 12 narzędzi programistycznych; `omniroute launch` / `launch-codex` działają bez konfiguracji. → [Integracje CLI](../../../docs/guides/CLI-INTEGRATIONS.md) +- **🛰️ Tryb zdalny** — steruj zdalną instancją OmniRoute za pomocą tokenów o ograniczonym zakresie (`connect` / `contexts` / `tokens`) + pomocnika OAuth `antigravity` dla instalacji na VPS. → [Tryb zdalny](../../../docs/guides/REMOTE-MODE.md) +- **🧭 Inteligentniejszy auto-routing** — komba `auto/:`, **Fusion** (panel modeli + sędzia), routing uwzględniający specyfikę zadania, nadpisywanie modelu / trybu / budżetu USD per żądanie. → [Auto-Combo](docs/routing/AUTO-COMBO.md) +- **🗜️ Wtyczkowa kompresja** — 11 modułowych silników + Studia Kompresji: LLMLingua-2, dwupoziomowy Ultra, omniglyph, weryfikacja dokładności (fidelity gate) na każdym kroku, GCF v3.2, edytor z przeciąganiem elementów. → [Kompresja](../../../docs/compression/COMPRESSION_ENGINES.md) +- **🕵️ Przezroczyste dekodowanie MITM (TPROXY)** — przechwytywanie CLI ignorujących zmienne środowiskowe proxy, z instalatorem CA per-SNI i bazy zaufanych certyfikatów. → [MITM/TPROXY](../../../docs/security/MITM-TPROXY-DECRYPT.md) +- **💸 Telemetria kosztów wszędzie** — nagłówki kosztu/użycia `X-OmniRoute-*` w każdym punkcie końcowym, nagłówek oszczędności z trafień w cache (cache-HIT), limity wydatków USD na klucz. → [Referencja API](docs/reference/API_REFERENCE.md) +- **🧠 Pamięć pod Twoją kontrolą** — domyślnie wyłączona, opcjonalna kwantyzacja wektorowa int8 + stopniowe wygaszanie (typed decay), nagłówek `x-omniroute-no-memory` na żądanie. → [Pamięć](../../../docs/frameworks/MEMORY.md) +- **🛡️ Bezpieczeństwo** — ochrona przed wstrzykiwaniem promptów (prompt-injection guard) na każdej trasie LLM (zestaw testów red-team) + darmowe wyszukiwanie w sieci DuckDuckGo jako ostatnia deska ratunku. → [Barierki ochronne](../../../docs/security/GUARDRAILS.md) +- **🖼️ Nowe punkty końcowe** — `/v1/ocr` (Mistral OCR) i `/v1/audio/translations` (w stylu Whisper) uzupełniają obsługę multimediów. → [Referencja API](docs/reference/API_REFERENCE.md) +- **🌍 Wdrożenie i administracja** — `basePath` dla reverse-proxy, automatyczne wykrywanie języka przeglądarki, śledzenie urządzeń na klucz, zaufanie MITM bez uprawnień roota, lokalizacja zh-TW. → [Środowisko](docs/reference/ENVIRONMENT.md) +- **🤝 Więcej dostawców i agentów** — Cursor Cloud Agent, Grok Build (xAI), pełnoprawna karta Ollama, Claude Sonnet 5, Zed, Requesty, SenseNova, Yuanbao… oraz odświeżony katalog 250 dostawców. → [Dostawcy](../../../docs/reference/PROVIDER_REFERENCE.md) +- **⚡ Lokalna wydajność i infrastruktura** — uruchamianie lokalnego Redis jednym kliknięciem, instalatory przekaźników dla Cloudflare Workers / Deno Deploy, Bifrost i Mux jako nadzorowane usługi wbudowane. → [Usługi wbudowane](../../../docs/frameworks/EMBEDDED-SERVICES.md) + +
+ +
+ +# 🤖 Zgodne CLI i agenci kodujący + +> Jedna konfiguracja — `http://localhost:20128/v1` — i **każde** IDE lub CLI AI działa na darmowych i tanich modelach. + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Claude Code
Claude Code
                           		Codex CLI
Codex CLI
                           		Cline
Cline
                           		Kilo Code
Kilo Code
                           		Roo CodeRoo Code
Roo Code
                           		Continue
Continue
                           		Qwen Code
Qwen Code
                           		Aider
Aider
                           		ForgeCode
ForgeCode
                           
jcode
jcode
                           		DeepSeek TUI
DeepSeek TUI
                           		CodeWhale
CodeWhale
                           		OpenCode
OpenCode
                           		Factory Droid
Factory Droid
                           		GitHub Copilot CLI
Copilot CLI
                           		Cursor CLI
Cursor CLI
                           		Smelt
Smelt
                           
Pi (pi-coding-agent)
Pi
                           		Grok Build (xAI)
Grok Build
                           		Hermes Agent (Nous Research)
Hermes Agent
                           		OpenClaw
OpenClaw
                           		Goose
Goose
                           		Open Interpreter
Open Interpreter
                           		Warp AI
Warp AI
                           		Agent Deck
Agent Deck
                           
+
+ +
+＋ działa również z · Kiro · Command Code · Antigravity · Windsurf · AMP · dowolnym narzędziem kompatybilnym z OpenAI +
+ +📖 Konfiguracja per narzędzie dla wszystkich 33 narzędzi (25 z CLI Code + 8 z CLI Agents) → [`docs/reference/CLI-TOOLS.md`](docs/reference/CLI-TOOLS.md) · 🧩 Wtyczka OpenCode → [`@omniroute/opencode-provider`](https://www.npmjs.com/package/@omniroute/opencode-provider) + +
+ +
+ +
+ +# 🌐 268 dostawców AI — ponad 90 darmowych + +
+ +> Najbardziej kompletny katalog spośród wszystkich routerów open-source: **268 dostawców**, **ponad 90 z darmowym pakietem**, **ponad 40 darmowych na zawsze**. + +
+ +### 🏢 Każde główne laboratorium — przez jeden punkt końcowy + + + + + + + + + + + + + + + + + + + + + + + + +
OpenAI
OpenAI
                           		Anthropic
Anthropic
                           		Gemini
Gemini
                           		xAI Grok
xAI Grok
                           		DeepSeek
DeepSeek
                           		Mistral
Mistral
                           		Qwen
Qwen
                           		Meta Llama
Meta Llama
                           		Groq
Groq
                           
NVIDIA
NVIDIA
                           		MiniMax
MiniMax
                           		Cohere
Cohere
                           		Perplexity
Perplexity
                           		Hugging Face
HuggingFace
                           		Together
Together
                           		Fireworks
Fireworks
                           		Cloudflare
Cloudflare
                           		Baidu
Baidu
                           
+ +…oraz ponad 220 innych — każda ikona ładuje się na żywo z katalogu dostawców w panelu. 📖 [Referencja dostawców](../../../docs/reference/PROVIDER_REFERENCE.md) + +
+ +### 🆓 Darmowe na zawsze — 0 USD, bez karty + + + + + + + + + + + +
AgentRouter
AgentRouter
GPT-5, Claude, Gemini
100 USD darmowych kredytów
                                     		Qoder AI
Qoder AI
Kimi-K2, DeepSeek-R1
Nielimitowane DARMOWE
                                     		Pollinations
Pollinations
GPT-5, Claude, Llama 4
Klucz nie jest wymagany
                                     		LongCat
LongCat
LongCat-2.0
10M tokenów jednorazowo (KYC) 🔑
                                     		Cloudflare AI
Cloudflare AI
Ponad 50 modeli
10K neuronów/dzień
                                     		NVIDIA NIM
NVIDIA NIM
129 modeli
~40 RPM darmowo
                                     		Cerebras
Cerebras
Qwen3 235B
1M tokenów/dzień
                                     
+ +📖 Pełny katalog w formacie czytelnym dla maszyn → [`docs/reference/PROVIDER_REFERENCE.md`](../../../docs/reference/PROVIDER_REFERENCE.md) + +
+
+ +
+ +# 🖥️ Gdzie działa OmniRoute — wszędzie + +
+ +> Ta sama aplikacja, Twoja maszyna, Twoje zasady. Od globalnej instalacji przez npm po Twój telefon za pomocą Termux. + +| Platforma | Instalacja | Najważniejsze cechy | +| ------------------------- | ---------------------------------------- | --------------------------------------------------------- | +| 📦 **npm (globalnie)** | `npm install -g omniroute` | Jedno polecenie, dowolny system operacyjny | +| 🐳 **Docker** | `docker run … diegosouzapw/omniroute` | Wielonatywność architektur **AMD64 + ARM64** | +| 🖥️ **Desktop (Electron)** | `npm run electron:build` | Natywne okno + zasobnik systemowy (system tray) — **Windows / macOS / Linux** | +| 💪 **ARM** | natywnie `arm64` | Raspberry Pi, serwery ARM, Apple Silicon | +| 📱 **Android (Termux)** | `pkg install nodejs && npx -y omniroute` | Działa **na Twoim telefonie**, 24/7, bez roota | +| 📲 **PWA** | "Dodaj do ekranu głównego" | Pełny ekran, offline, instalacja z poziomu przeglądarki | +| 🧩 **Wtyczka OpenCode** | `@omniroute/opencode-provider` | Natywna integracja z OpenCode | +| 🛠️ **Ze źródeł** | `npm install && npm run dev` | Modyfikuj kod, współtwórz projekt | + +📖 [Podręcznik Docker](../../../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) + +
+ +
+ +# 🔒 Prywatność i lokalne działanie (Local-First) + +
+ +Prywatność i lokalne działanie — Twoje klucze, Twoja maszyna, Twoje dane; OmniRoute to lokalne proxy, które nigdy nie wysyła danych na zewnętrzne serwery. Jedenaście gwarancji: działa w 100% na Twoim sprzęcie (0 przeskoków do chmury), domyślnie zero telemetrii, zaszyfrowane dane uwierzytelniające (AES-256-GCM), brak konieczności zakładania konta czy rejestracji, wzmocniona bramka (ograniczanie zakresu kluczy API, filtrowanie IP, limity zapytań, ochrona przed wstrzykiwaniem promptów), trasy procesów wyłącznie na adresie pętli zwrotnej (loopback-only), oczyszczanie nagłówków wysyłanych do dostawców nadrzędnych, usuwanie danych osobowych (PII) ściśle na żądanie (opt-in), bezpieczne błędy, które nigdy nie ujawniają szczegółów wewnętrznych, lokalny dziennik audytu w Twojej własnej bazie SQLite oraz w pełni otwartoźródłowy kod na licencji MIT. + +📖 [Autoryzacja](../../../docs/architecture/AUTHZ_GUIDE.md) · [Barierki ochronne](../../../docs/security/GUARDRAILS.md) · [Zgodność](../../../docs/security/COMPLIANCE.md) + +
+ +
+ +# 🔌 Pełne CLI + A2A i MCP + +
+ +> OmniRoute to nie tylko serwer — to **kompletny kokpit w wierszu poleceń** z **ponad 80 poleceniami**, plus otwarte protokoły agentów, dzięki którym agent AI może samodzielnie sterować OmniRoute. + +### ⌨️ Prawdziwe CLI (nie tylko `start`) ```bash -npm run system-info +omniroute # uruchom bramkę + panel (port 20128) +omniroute chat # interaktywny klient czatu TUI (polecenia ukośnika: /model /combo /skill /memory) +omniroute setup # kreator pierwszej konfiguracji +omniroute doctor # diagnozuj dostawców, porty, natywne zależności ``` -This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages — everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue. +### 🛰️ Tryb zdalny — uruchom CLI lokalnie, OmniRoute na VPS ---- +OmniRoute na serwerze? Steruj nim ze swojego laptopa za pomocą **tego samego CLI**. Zaloguj się raz +za pomocą tokenu dostępu o ograniczonym zakresie; każde kolejne polecenie będzie skierowane do zdalnej maszyny. -## 🔄 How It Works - -``` -┌─────────────┐ -│ Your CLI │ (Claude Code, Codex, OpenClaw, Cursor, Cline...) -│ Tool │ -└──────┬──────┘ - │ http://localhost:20128/v1 - ↓ -┌─────────────────────────────────────────┐ -│ OmniRoute (Smart Router) │ -│ • Format translation (OpenAI ↔ Claude) │ -│ • Quota tracking + Embeddings + Images │ -│ • Auto token refresh │ -└──────┬──────────────────────────────────┘ - │ - ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex - │ ↓ quota exhausted - ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc. - │ ↓ budget limit - ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M) - │ ↓ budget limit - └─→ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited) - -Result: Never stop coding, minimal cost +```bash +omniroute connect 192.168.0.15 # hasło → token o ograniczonym zakresie, zapisany jako kontekst +omniroute models list # ← działa na ZDALNYM serwerze +omniroute configure codex # ← wybiera zdalny model, zapisuje lokalny profil Codex +omniroute tokens create --name ci --scope read # generuj węższe tokeny dla innych maszyn +omniroute contexts use default # ← przełącz z powrotem na serwer lokalny ``` ---- +Tokeny mają zakresy `read` / `write` / `admin`; trasy uruchamiające procesy pozostają ograniczone do pętli zwrotnej (loopback-only). +📖 [Tryb zdalny](../../../docs/guides/REMOTE-MODE.md) -## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases +
-> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all — from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability. +Animowany terminal demonstrujący CLI OmniRoute — omniroute providers list, omniroute combo list, omniroute health — przechodzący przez obszar ponad 80 poleceń: dostawcy · oauth · klucze · kombo · węzły · modele · pamięć podręczna · kompresja · koszt · użycie · limity · stan techniczny · odporność · telemetria · logi · audyt · mcp · a2a · chmura · pamięć · umiejętności · ewaluacja · tunel · kopia zapasowa · synchronizacja · webhooki · polityka · cennik · tłumacz · symulacja … -
-💸 1. "I pay for an expensive subscription but still get interrupted by limits" +
-Developers pay $20–200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling — 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity. +### 🤝 Połącz agenta — i pozwól mu kontrolować samo OmniRoute -**How OmniRoute solves it:** +Udostępnij OmniRoute przez **MCP** lub **A2A**, a każdy zdolny do tego agent autonomicznie otrzyma klucze do całej bramki — routingu, dostawców, kombinacji (combos), pamięci podręcznej, kompresji i pamięci. -- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention -- **Provider Limits Tracking** — Cached quota snapshots refresh on a server-side schedule (default `PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70`) with manual refresh available in the UI -- **Multi-Account Support** — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next -- **Custom Combos** — Customizable fallback chains with 13 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random, auto, lkgp, context-optimized, **context-relay**) -- **Structured Combo Builder** — Build combos step-by-step with explicit provider + model + account selection, including repeated providers and fixed-account targets -- **Quota-Aware P2C** — Power-of-two account selection now factors quota headroom, backoff, recent errors, and consecutive use -- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard +| Protokół | Punkt końcowy | Zastosowanie | +| ------------------ | ----------------------------------------------- | ------------------------------------------------------- | +| 🧰 **MCP (stdio)** | `omniroute --mcp` | Podłącz do Claude Desktop, Cursor, dowolnego klienta MCP | +| 🌊 **MCP (HTTP)** | `http://localhost:20128/api/mcp/stream` | Zdalny MCP — **104 narzędzia**, 31 zakresów, pełna ścieżka audytu | +| 📡 **MCP (SSE)** | `http://localhost:20128/api/mcp/sse` | Strumieniowy transport MCP | +| 🤝 **A2A** | `http://localhost:20128/.well-known/agent.json` | Komunikacja agent-do-agenta, **JSON-RPC 2.0** + SSE, 6 umiejętności | - +```bash +# Daj Claude Code pełny zestaw narzędzi OmniRoute przez MCP: +claude mcp add-server omniroute --type http --url http://localhost:20128/api/mcp/stream +``` -
-🔌 2. "I need to use multiple providers but each has a different API" +📖 [Serwer MCP](docs/frameworks/MCP-SERVER.md) · [Serwer A2A](docs/frameworks/A2A-SERVER.md) · [Protokoły agentów](../../../docs/frameworks/AGENT_PROTOCOLS_GUIDE.md) -OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints. +
-**How OmniRoute solves it:** +
-- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 100+ providers -- **Format Translation** — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API -- **Response Sanitization** — Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+ -- **Role Normalization** — Converts `developer` → `system` for non-OpenAI providers; `system` → `user` for GLM/ERNIE -- **Think Tag Extraction** — Extracts `` blocks from models like DeepSeek R1 into standardized `reasoning_content` -- **Structured Output for Gemini** — `json_schema` → `responseMimeType`/`responseSchema` automatic conversion -- **`stream` defaults to `false`** — Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs +# 🗜️ Oszczędzaj 15–95% tokenów — automatycznie -
+ -
-🌐 3. "My AI provider blocks my region/country" +> **Po co używać wielu tokenów, skoro kilka wystarczy?** Każde żądanie przechodzi przez potok kompresji OmniRoute w sposób **przezroczysty** — bez zmian po stronie klienta. Jest to teraz **stos 11 modułowych silników**, które działają po kolei i mogą być dowolnie łączone w ramach każdego komba routingu — bazując na pomysłach z [RTK](https://github.com/rtk-ai/rtk), [Caveman](https://github.com/JuliusBrussee/caveman) (⭐ 90k+), [LLMLingua-2](https://github.com/microsoft/LLMLingua) i [Troglodita](https://github.com/leninejunior/troglodita) (PT-BR). -Providers like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries. +### 🧱 Stos 11 silników -**How OmniRoute solves it:** +Silniki działają w kolejności potoku; każdy z nich można niezależnie włączać i konfigurować dla poszczególnych komb: -- **3-Level Proxy Config** — Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key -- **Color-Coded Proxy Badges** — Visual indicators: 🟢 global proxy, 🟡 provider proxy, 🔵 connection proxy, always showing the IP -- **OAuth Token Exchange Through Proxy** — OAuth flow also goes through the proxy, solving `unsupported_country_region_territory` -- **Connection Tests via Proxy** — Connection tests use the configured proxy (no more direct bypass) -- **SOCKS5 Support** — Full SOCKS5 proxy support for outbound routing -- **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint via `wreq-js` to bypass bot detection -- **🔏 CLI Fingerprint Matching** — Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved — you get both stealth **and** IP masking simultaneously +| # | Silnik | Co robi | +| --- | ----------------- | ----------------------------------------------------------------------------------------------------------------------- | +| 1 | **Session-Dedup** | Odrzuca treści powtarzające się między kolejnymi turami (adresowane treścią, międzyturowe) | +| 2 | **CCR** | Archiwizuje duże bloki pod znacznikami pobierania, pobieranymi na żądanie | +| 3 | **RTK** | Inteligentne filtrowanie, deduplikacja i skracanie wyników narzędzi (z uwzględnieniem poleceń) | +| 4 | **Headroom** | Bezstratne upakowanie tabelaryczne jednorodnych tablic JSON, płaskich lub zagnieżdżonych (~30%), poprzez wbudowany kodek **GCF** (specyfikacja v3.2) | +| 5 | **Relevance** | Ekstrakcyjne ocenianie zdań pod kątem dopasowania do ostatniego zapytania użytkownika | +| 6 | **Caveman** | Kompresja prozy oparta na regułach (~65–75% na wyjściu) | +| 7 | **LLMLingua-2** | Semantyczne przycinanie oparte na uczeniu maszynowym przez MobileBERT ONNX — bezpieczne dla kodu, asynchroniczne | +| 8 | **Lite** | Usuwanie białych znaków i skracanie adresów URL obrazów (lekki pod kątem opóżeń punkt odniesienia) | +| 9 | **Aggressive** | Streszczanie + stopniowe "starzenie" starych tur | +| 10 | **Ultra** | Heurystyczne przycinanie tokenów z opcjonalnym poziomem małego modelu (SLM) | -
+Bloki kodu, adresy URL i dane strukturyzowane są **zawsze zachowywane** z dokładnością co do bajtu. Presety uruchamiane jednym kliknięciem łączą te silniki: -
-🆓 4. "I want to use AI for coding but I have no money" +| Tryb | Oszczędności | Najlepszy do | +| ------------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| 🪶 **Lite** | ~15% | Zawsze włączona bezpieczna opcja domyślna | +| 🪨 **Standard (Caveman)** | ~30% | Codzienne kodowanie | +| ⚡ **Aggressive** | ~50% | Długie sesje z intensywnym użyciem narzędzi | +| 🔥 **Ultra** | ~75% | Maksymalne oszczędności | +| 🧰 **RTK** | 60–90% | Dane wyjściowe z terminala/testów/budowania/git | +| 🔗 **Kaskadowa (RTK → Caveman)** | **78–95%** | Mieszane prompty + logi z narzędzi | -Not everyone can pay $20–200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost. +**Rzeczywisty przykład — tryb Standard:** -**How OmniRoute solves it:** +> **Przed (69 tokenów):** _"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."_ +> +> **Po (19 tokenów):** _"New object ref each render. Inline object prop = new ref = re-render. Wrap in useMemo."_ +> +> **Ta sama odpowiedź. 72% mniej tokenów. Zero utraty dokładności. ✅** -- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/` prefix -- **Free-Only Combos** — Chain `if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/month with zero downtime -- **NVIDIA NIM Free Access** — ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits) -- **Cost Optimized Strategy** — Routing strategy that automatically chooses the cheapest available provider +**Przykład w PT-BR — tryb [Troglodita](https://github.com/leninejunior/troglodita):** -
+> **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`."_ +> +> **Ta sama odpowiedź. ~70% mniej tokenów. Dokładność techniczna nienaruszona. ✅** -
-🔒 5. "I need to protect my AI gateway from unauthorized access" +
-When exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse. +### 📖 Jak to działa — potok, architektura i matematyka oszczędności -**How OmniRoute solves it:** +Potok kompresji OmniRoute: żądanie klienta o rozmiarze 10 000 tokenów przechodzi przez 11 ułożonych kaskadowo silników — Session-Dedup, CCR, RTK, Headroom, Relevance, Caveman, LLMLingua-2, Omniglyph, Lite, Aggressive, Ultra — i dociera do dostawcy mając około 1080 tokenów, co daje do 95% oszczędności. Kod, adresy URL i JSON są zawsze zachowywane z dokładnością co do bajtu. -- **API Key Management** — Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page -- **Model-Level Permissions** — Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle -- **API Endpoint Protection** — Require a key for `/v1/models` and block specific providers from the listing -- **Auth Guard + CSRF Protection** — All dashboard routes protected with `withAuth` middleware + CSRF tokens -- **Rate Limiter** — Per-IP rate limiting with configurable windows -- **IP Filtering** — Allowlist/blocklist for access control -- **Prompt Injection Guard** — Sanitization against malicious prompt patterns -- **AES-256-GCM Encryption** — Credentials encrypted at rest - -
- -
-🛑 6. "My provider went down and I lost my coding flow" - -AI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application. - -**How OmniRoute solves it:** - -- **Request Queue & Pacing** — Per-connection request buckets smooth bursts before they hit upstream rate caps -- **Connection Cooldown** — A single connection cools down after retryable failures with optional upstream `Retry-After` hints and exponential backoff -- **Provider Circuit Breaker** — The provider only trips after fallback is exhausted and the provider request still fails with provider-wide transient errors; connection-scoped `429` rate limits stay in Connection Cooldown -- **Wait For Cooldown** — The server can wait for the earliest connection cooldown to expire and retry the same client request automatically -- **Anti-Thundering Herd** — Mutex + semaphore protection against concurrent retry storms -- **Combo Fallback Chains** — If the primary provider fails, automatically falls through the chain with no intervention -- **Health Dashboard** — Uptime monitoring, provider circuit breaker states, cooldowns, cache stats, p50/p95/p99 latency - -
- -
-🔧 7. "Configuring each AI tool is tedious and repetitive" - -**How OmniRoute solves it:** - -- **CLI Tools Dashboard** — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline -- **GitHub Copilot Config Generator** — Generates `chatLanguageModels.json` for VS Code with bulk model selection -- **Onboarding Wizard** — Guided 4-step setup for first-time users -- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 100+ providers - -
- -
-🔑 8. "Managing OAuth tokens from multiple providers is hell" - -Claude Code, Codex, Copilot — all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic. - -**How OmniRoute solves it:** - -- **Auto Token Refresh** — OAuth tokens refresh in background before expiration -- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Copilot, Kiro, Qwen, Qoder -- **Multi-Account OAuth** — Multiple accounts per provider via JWT/ID token extraction -- **OAuth LAN/Remote Fix** — Private IP detection for `redirect_uri` + manual URL mode for remote servers -- **OAuth Behind Nginx** — Uses `window.location.origin` for reverse proxy compatibility -- **Remote OAuth Guide** — Step-by-step guide for Google Cloud credentials on VPS/Docker - -
- -
-📊 9. "I don't know how much I'm spending or where" - -Developers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up. - -**How OmniRoute solves it:** - -- **Cost Analytics Dashboard** — Per-token cost tracking and budget management per provider -- **Budget Limits per Tier** — Spending ceiling per tier that triggers automatic fallback -- **Per-Model Pricing Configuration** — Configurable prices per model -- **Usage Statistics Per API Key** — Request count and last-used timestamp per key -- **Analytics Dashboard** — Stat cards, model usage chart, provider table with success rates and latency - -
- -
-🐛 10. "I can't diagnose errors and problems in AI calls" - -When a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error. - -**How OmniRoute solves it:** - -- **Unified Logs Dashboard** — 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console -- **Console Log Viewer** — Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter -- **SQLite Summary Logs** — Request and proxy log indexes stay queryable across restarts without loading large payload blobs into SQLite -- **Translator Playground** — 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time) -- **Request Telemetry** — p50/p95/p99 latency + X-Request-Id tracing -- **File-Based Detail Artifacts** — App logs rotate by size, retention days, and archive count; detailed request/response payloads live in `DATA_DIR/call_logs/` and rotate independently of SQLite summaries -- **System Info Report** — `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage. - -
- -
-🏗️ 11. "Deploying and maintaining the gateway is complex" - -Installing, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction. - -**How OmniRoute solves it:** - -- **npm global install** — `npm install -g omniroute && omniroute` — done -- **Docker Multi-Platform** — AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi) -- **Docker Compose Profiles** — `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw) -- **Electron Desktop App** — Native app for Windows/macOS/Linux with system tray, auto-start, offline mode -- **Split-Port Mode** — API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking) -- **Cloud Sync** — Config synchronization across devices via Cloudflare Workers -- **DB Backups** — Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups - -
- -
-🌍 12. "The interface is English-only and my team doesn't speak English" - -Teams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors. - -**How OmniRoute solves it:** - -- **Dashboard i18n — 30 Languages** — All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English -- **RTL Support** — Right-to-left support for Arabic and Hebrew -- **Multi-Language READMEs** — 30 complete documentation translations -- **Language Selector** — Globe icon in header for real-time switching - -
- -
-🔄 13. "I need more than chat — I need embeddings, images, audio" - -AI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format. - -**How OmniRoute solves it:** - -- **Embeddings** — `/v1/embeddings` with 6 providers and 9+ models -- **Image Generation** — `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI) -- **Text-to-Video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) and SD WebUI -- **Text-to-Music** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen) -- **Audio Transcription** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3 -- **Text-to-Speech** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers -- **Moderations** — `/v1/moderations` — Content safety checks -- **Reranking** — `/v1/rerank` — Document relevance reranking -- **Responses API** — Full `/v1/responses` support for Codex - -
- -
-🧪 14. "I have no way to test and compare quality across models" - -Developers want to know which model is best for their use case — code, translation, reasoning — but comparing manually is slow. No integrated eval tools exist. - -**How OmniRoute solves it:** - -- **LLM Evaluations** — Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal -- **4 Match Strategies** — `exact`, `contains`, `regex`, `custom` (JS function) -- **Translator Playground Test Bench** — Batch testing with multiple inputs and expected outputs, cross-provider comparison -- **Chat Tester** — Full round-trip with visual response rendering -- **Live Monitor** — Real-time stream of all requests flowing through the proxy - -
- -
-📈 15. "I need to scale without losing performance" - -As request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected. - -**How OmniRoute solves it:** - -- **Semantic Cache** — Two-tier cache (signature + semantic) reduces cost and latency -- **Request Idempotency** — 5s deduplication window for identical requests -- **Rate Limit Detection** — Per-provider RPM, min gap, and max concurrent tracking -- **Request Queue & Pacing** — Configurable queue, pacing, and concurrency defaults in Settings → Resilience -- **API Key Validation Cache** — 3-tier cache for production performance -- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime - -
- -
-🤖 16. "I want to control model behavior globally" - -Developers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical. - -**How OmniRoute solves it:** - -- **System Prompt Injection** — Global prompt applied to all requests -- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive) -- **9 Routing Strategies** — Global strategies that determine how requests are distributed -- **Wildcard Router** — `provider/*` patterns route dynamically to any provider -- **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard -- **Manual Combo Ordering** — Drag combo cards by handle and persist the order in SQLite -- **Provider Toggle** — Enable/disable all connections for a provider with one click -- **Blocked Providers** — Exclude specific providers from `/v1/models` listing - -
- -
-🧰 17. "I need MCP tools as first-class product capabilities" - -Many AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer. - -**How OmniRoute solves it:** - -- MCP appears in the dashboard navigation and endpoint protocol tab -- Dedicated MCP management page with process, tools, scopes, and audit -- Built-in quick-start for `omniroute --mcp` and client onboarding - -
- -
-🧠 18. "I need A2A orchestration with sync + stream task paths" - -Agent workflows need both direct replies and long-running streamed execution with lifecycle control. - -**How OmniRoute solves it:** - -- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream` -- SSE streaming with terminal state propagation -- Task lifecycle APIs for `tasks/get` and `tasks/cancel` - -
- -
-🛰️ 19. "I need real MCP process health, not guessed status" - -Operational teams need to know if MCP is actually alive, not just whether an API is reachable. - -**How OmniRoute solves it:** - -- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode -- MCP status API combining heartbeat + recent activity -- UI status cards for process/uptime/heartbeat freshness - -
- -
-📋 20. "I need auditable MCP tool execution" - -When tools mutate config or trigger ops actions, teams need forensic traceability. - -**How OmniRoute solves it:** - -- SQLite-backed audit logging for MCP tool calls -- Filters by tool, success/failure, API key, and pagination -- Dashboard audit table + stats endpoints for automation - -
- -
-🔐 21. "I need scoped MCP permissions per integration" - -Different clients should have least-privilege access to tool categories. - -**How OmniRoute solves it:** - -- 10 granular MCP scopes for controlled tool access -- Scope enforcement and visibility in MCP management UI -- Safe default posture for operational tooling - -
- -
-⚙️ 22. "I need operational controls without redeploying" - -Teams need quick runtime changes during incidents or cost events. - -**How OmniRoute solves it:** - -- Switch combo activation directly from MCP dashboard -- Tune queue, cooldown, breaker, and wait settings from the dedicated Resilience page -- Review live provider breaker state from the Health dashboard - -
- -
-🔄 23. "I need live A2A task lifecycle visibility and cancellation" - -Without lifecycle visibility, task incidents become hard to triage. - -**How OmniRoute solves it:** - -- Task listing/filtering by state/skill with pagination -- Drill-down on task metadata, events, and artifacts -- Task cancellation endpoint and UI action with confirmation - -
- -
-🌊 24. "I need active stream metrics for A2A load" - -Streaming workflows require operational insight into concurrency and live connections. - -**How OmniRoute solves it:** - -- Active stream counters integrated into A2A status -- Last task timestamp and per-state counts -- A2A dashboard cards for real-time ops monitoring - -
- -
-🪪 25. "I need standard agent discovery for clients" - -External clients and orchestrators need machine-readable metadata for onboarding. - -**How OmniRoute solves it:** - -- Agent Card exposed at `/.well-known/agent.json` -- Capabilities and skills shown in management UI -- A2A status API includes discovery metadata for automation - -
- -
-🧭 26. "I need protocol discoverability in the product UX" - -If users cannot discover protocol surfaces, adoption and support quality drop. - -**How OmniRoute solves it:** - -- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints -- Inline service status toggles (Online/Offline) for MCP and A2A -- Links from overview to dedicated management tabs - -
- -
-🧪 27. "I need end-to-end protocol validation with real clients" - -Mock tests are not enough to validate protocol compatibility before release. - -**How OmniRoute solves it:** - -- E2E suite that boots app and uses real MCP SDK client transport -- A2A client tests for discovery, send, stream, get, and cancel flows -- Cross-check assertions against MCP audit and A2A tasks APIs - -
- -
-📡 28. "I need unified observability across all interfaces" - -Splitting observability by protocol creates blind spots and longer MTTR. - -**How OmniRoute solves it:** - -- Unified dashboards/logs/analytics in one product -- Health + audit + request telemetry across OpenAI, MCP, and A2A layers -- Operational APIs for status and automation - -
- -
-💼 29. "I need one runtime for proxy + tools + agent orchestration" - -Running many separate services increases operational cost and failure modes. - -**How OmniRoute solves it:** - -- OpenAI-compatible proxy, MCP server, and A2A server in one stack -- Shared auth, resilience, data store, and observability -- Consistent policy model across all interaction surfaces - -
- -
-🚀 30. "I need to ship agentic workflows without glue-code sprawl" - -Teams lose velocity when stitching multiple ad-hoc services and scripts. - -**How OmniRoute solves it:** - -- Unified endpoint strategy for clients and agents -- Built-in protocol management UIs and smoke validation paths -- Production-ready foundations (security, logging, resilience, backup) - -
- -
-📚 31. "My long sessions crash with 'context_length_exceeded' limits" - -During deep debugging, long histories with tool results quickly exceed provider token windows, causing failed requests and orphaned context. - -**How OmniRoute solves it:** - -- **Proactive Context Compression** — Evaluates token budgets before the request hits upstream and proactively prunes old conversation history with a smart binary-search mechanism. -- **Structural Integrity Guards** — Automatically tracks explicit `tool_use` definitions and ensures that if a tool input is truncated, its corresponding `tool_result` is also safely removed, preventing API validation errors. -- **Multi-Layer Dropping** — Progressively drops system messages, regular messages, and finally enforces strict length limits without breaking conversational logic. - -
- -### Example Playbooks (Integrated Use Cases) - -**Playbook A: Maximize paid subscription + cheap backup** +Domyślne kaskadowe kombo uruchamia `RTK → Caveman`. Gdy oba silniki działają na tym samym ładunku narzędzia/kontekstu, oszczędności się kumulują: ```txt -Combo: "maximize-claude" - 1. cc/claude-opus-4-7 - 2. glm/glm-4.7 - 3. if/kimi-k2-thinking - -Monthly cost: $20 + small backup spend -Outcome: higher quality, near-zero interruption +combined = 1 − (1 − RTK) × (1 − Caveman_input) +average = 1 − (1 − 0.80) × (1 − 0.46) = 89.2% +range = 78.4 – 94.6% ``` -**Playbook B: Zero-cost coding stack** +Bloki kodu, adresy URL, JSON i dane strukturyzowane są **zawsze chronione** przez silnik zachowania integralności. -```txt -Combo: "free-forever" - 1. if/kimi-k2-thinking (unlimited free) - 2. qw/qwen3-coder-plus (unlimited free) +### 🎚️ Poza silnikami — style wyjściowe, pokrętło adaptacyjne i kontrola per żądanie -Monthly cost: $0 -Outcome: stable free coding workflow -``` +Opisane wyżej silniki zmniejszają dane wejściowe. Trzy dodatkowe warstwy kształtują jak, kiedy i co trafia na wyjście: -**Playbook C: 24/7 always-on fallback chain** +- **🪄 Style wyjściowe** (sterowanie osią wyjściową) — wstrzykiwanie deterministycznych, bezpiecznych dla cache instrukcji kształtowania odpowiedzi; można je łączyć, każda o intensywności `lite` / `full` / `ultra`. Dodanie stylu to jednolinijkowy wpis w rejestrze: + - **Zwiezła proza** — odrzucanie wypełniaczy / przedimków / asekuracyjnych sformułowań; zachowanie dokładnej treści technicznej. + - **Mniej kodu** — podejście "leniwego seniora" (YAGNI): najmniejsza działająca zmiana, bez nieproszonych struktur kodu. + - **Zwięzły CJK (文言)** — klasyczny, ultra-zwięzły styl chiński (ograniczony lokalizacyjnie do języka `zh`). +- **🎯 Adaptacyjny budżet kontekstu** (pokrętło) — zamiast jednego sztywnego progu włączenia/wyłączenia, uruchamia najtańsze i najbardziej bezstratne silniki tylko w takim stopniu, w jakim jest to konieczne, aby zmieścić się w oknie kontekstowym modelu. Polityka: `reserve-output` (domyślna, dopasowana do modelu) · `percentage` · `absolute`. Tryb: `floor` (gwarantowane dopasowanie) · `replace-autotrigger` (wygrywa Twój wyraźny wybór) · `off` (stary próg). +- **🛞 Miejsce decyzji o kompresji** (priorytet od najwyższego do najniższego) — nagłówek `x-omniroute-compression` w żądaniu › nadpisanie w kombie routingu › aktywny profil nazwany › adaptacyjny / automatyczny wyzwalacz › domyślne ustawienie panelu › wyłączone. Zastosowany plan jest zwracany w nagłówku odpowiedzi `X-OmniRoute-Compression: ; source=<źródło>`. -```txt -Combo: "always-on" - 1. cc/claude-opus-4-7 - 2. cx/gpt-5.2-codex - 3. glm/glm-4.7 - 4. minimax/MiniMax-M2.1 - 5. if/kimi-k2-thinking +Wyzwalaj automatycznie według progu tokenów, włącz pokrętło adaptacyjne, przypnij nazwany profil, ustaw jednorazowo dla żądania lub przypisz potok do komba routingu — cokolwiek pasuje do Twojego obciążenia pracy. Opcjonalne środowisko testowe offline (`npm run eval:compression`) ocenia wierność vs oszczędności na przypisanym korpusie przed wdrożeniem zmian. -Outcome: deep fallback depth for deadline-critical workloads -``` +📖 [`COMPRESSION_GUIDE.md`](../../../docs/compression/COMPRESSION_GUIDE.md) · [`RTK_COMPRESSION.md`](../../../docs/compression/RTK_COMPRESSION.md) · [`COMPRESSION_ENGINES.md`](../../../docs/compression/COMPRESSION_ENGINES.md) -**Playbook D: Agent ops with MCP + A2A** +
-```txt -1) Start MCP transport (`omniroute --mcp`) for tool-driven operations -2) Run A2A tasks via `message/send` and `message/stream` -3) Observe via /dashboard/endpoint (MCP and A2A tabs) -4) Toggle services via inline status controls -``` +
---- +# ⚡ Szybki start -## 🆓 Start Free — Zero Configuration Cost +
-> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo. - -| Step | Action | Providers Unlocked | -| ---- | -------------------------------------------------- | ------------------------------------------------------------------ | -| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 — **unlimited** | -| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** | -| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** | -| 4 | `/dashboard/combos` → **Free Stack ($0)** template | Round-robin all free providers automatically | - -**Point any IDE/CLI to:** `http://localhost:20128/v1` · API Key: `any-string` · Done. - -> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models). - -## Szybki start - -### 1) Install and run +**1) Zainstaluj i uruchom** ```bash npm install -g omniroute omniroute ``` -> **pnpm users:** Pass `--allow-build` at install time to enable native build scripts required by `better-sqlite3` and `@swc/core` (the `approve-builds -g` command is not supported for global installs on pnpm v11): -> -> ```bash -> pnpm add -g omniroute@latest --allow-build=better-sqlite3 --allow-build=@swc/core -> omniroute -> ``` +Panel pod adresem `http://localhost:20128` · API pod adresem `http://localhost:20128/v1`. -Dashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`. +**2) Podłącz DARMOWEGO dostawcę (bez rejestracji)** -#### Arch Linux (AUR) +Panel → **Dostawcy** (Providers) → połącz **Kiro AI** (darmowy Claude, ~50 kredytów/miesiąc na konto) lub **OpenCode Free** (bez autoryzacji) → gotowe. -Arch Linux users can install the [AUR package](https://aur.archlinux.org/packages/omniroute-bin), which installs OmniRoute and provides a systemd user service: - -```bash -yay -S omniroute-bin -systemctl --user enable --now omniroute.service -``` - -| Command | Description | -| ----------------------- | ----------------------------------------------------------- | -| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) | -| `omniroute --port 3000` | Set canonical/API port to 3000 | -| `omniroute --mcp` | Start MCP server (stdio transport) | -| `omniroute --no-open` | Don't auto-open browser | -| `omniroute --help` | Show help | - -Optional split-port mode: - -```bash -PORT=20128 DASHBOARD_PORT=20129 omniroute -# API: http://localhost:20128/v1 -# Dashboard: http://localhost:20129 -``` - -### 2) Uninstalling - -When you no longer need OmniRoute, we provide two quick scripts for a clean removal: - -| Command | Action | -| ------------------------ | ----------------------------------------------------------------------------------- | -| `npm run uninstall` | Removes the system app but **keeps your DB and configurations** in `~/.omniroute`. | -| `npm run uninstall:full` | Removes the app AND permanently **erases all configurations, keys, and databases**. | - -> Note: To run these commands, navigate to the OmniRoute project folder (if you cloned it) and run them. Alternatively, if globally installed, you can simply run `npm uninstall -g omniroute`. - -### Long-Running Streaming Timeouts - -For most deployments, you only need: - -| Variable | Default | Purpose | -| ------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -| `REQUEST_TIMEOUT_MS` | `600000` | Shared baseline for upstream response-start timeout, hidden Undici timeouts, TLS fingerprint requests, and API bridge request/proxy timeouts | -| `STREAM_IDLE_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Maximum gap between streaming chunks before OmniRoute aborts the SSE stream | - -Backward compatibility is preserved: existing `FETCH_TIMEOUT_MS`, `API_BRIDGE_PROXY_TIMEOUT_MS`, and other per-layer timeout vars still work and override the shared baseline. - -For Claude Code-compatible upstreams (`anthropic-compatible-cc-*`), OmniRoute also derives the outbound `X-Stainless-Timeout` header from the resolved fetch timeout so provider-side read timeouts stay aligned with your env configuration. - -For third-party Claude Code-compatible reverse proxies, OmniRoute keeps the default -`anthropic-beta` set conservative and, when `Client Cache Control` is left on `Auto`, -only forwards client-provided `cache_control` markers. If the request does not include -`cache_control`, OmniRoute does not inject bridge-owned markers. - -Advanced overrides are available if you need finer control: - -| Variable | Default | Purpose | -| ---------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- | -| `FETCH_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` | Upstream response-start timeout used until response headers arrive | -| `FETCH_HEADERS_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit for receiving upstream response headers | -| `FETCH_BODY_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Undici time limit between upstream body chunks (`0` disables it) | -| `FETCH_CONNECT_TIMEOUT_MS` | `30000` | Undici TCP connect timeout | -| `FETCH_KEEPALIVE_TIMEOUT_MS` | `4000` | Undici idle keep-alive socket timeout | -| `TLS_CLIENT_TIMEOUT_MS` | inherits `FETCH_TIMEOUT_MS` | Timeout for TLS fingerprint requests made through `wreq-js` | -| `API_BRIDGE_PROXY_TIMEOUT_MS` | inherits `REQUEST_TIMEOUT_MS` or `600000` | Timeout for `/v1` proxy forwarding from API port to dashboard port | -| `API_BRIDGE_SERVER_REQUEST_TIMEOUT_MS` | `max(API_BRIDGE_PROXY_TIMEOUT_MS, 300000)` | Incoming request timeout on the API bridge server | -| `API_BRIDGE_SERVER_HEADERS_TIMEOUT_MS` | `60000` | Incoming header timeout on the API bridge server | -| `API_BRIDGE_SERVER_KEEPALIVE_TIMEOUT_MS` | `5000` | Keep-alive timeout on the API bridge server | -| `API_BRIDGE_SERVER_SOCKET_TIMEOUT_MS` | `0` | Socket inactivity timeout on the API bridge server (`0` disables it) | - -For streaming requests, `FETCH_TIMEOUT_MS` only covers connection setup / waiting for the first upstream response. Once the stream is active, OmniRoute will only abort on an actual stall (`STREAM_IDLE_TIMEOUT_MS`) or Undici body inactivity (`FETCH_BODY_TIMEOUT_MS`). - -If you run OmniRoute behind Nginx, Caddy, Cloudflare, or another reverse proxy, make sure the proxy -timeouts are also higher than your OmniRoute stream/fetch timeouts. - -### 2) Connect providers and create your API key - -1. Open Dashboard → `Providers` and connect at least one provider (OAuth or API key). -2. Open Dashboard → `Endpoints` and create an API key. -3. (Optional) Open Dashboard → `Combos` and set your fallback chain. - -### 3) Point your coding tool to OmniRoute +**3) Skieruj swoje narzędzie do kodowania** ```txt Base URL: http://localhost:20128/v1 -API Key: [copy from Endpoint page] -Model: if/kimi-k2-thinking (or any provider/model prefix) +API Key: [skopiuj z Panel → Endpoints] +Model: auto (inteligentny routing bez konfiguracji — lub dowolny dostawca/model) ``` -### 4) Enable and validate protocols (v2.0) - -**MCP (for tool-driven operations):** +**4) Sprawdź, czy działa** ```bash -omniroute --mcp +curl http://localhost:20128/v1/models -H "Authorization: Bearer TWÓJ_KLUCZ" ``` -Then connect your MCP client over `stdio` and test tools like: +Powinieneś zobaczyć listę połączonych modeli. 🎉 To wszystko — zacznij kodować, a OmniRoute automatycznie zajmie się routingiem i przełączaniem awaryjnym. -- `omniroute_get_health` -- `omniroute_list_combos` - -**A2A (for agent-to-agent workflows):** - -```bash -curl http://localhost:20128/.well-known/agent.json -``` - -```bash -curl -X POST http://localhost:20128/a2a \ - -H 'content-type: application/json' \ - -d '{"jsonrpc":"2.0","id":"quickstart","method":"message/send","params":{"skill":"quota-management","messages":[{"role":"user","content":"Give me a short quota summary."}]}}' -``` - -### 5) Validate everything end-to-end (recommended) - -```bash -npm run test:protocols:e2e -``` - -This suite validates real MCP and A2A client flows against a running app. - -### Alternative: run from source - -```bash -cp .env.example .env -npm install -PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev -``` - -
-Void Linux (`xbps-src` template) - -For Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`: - -```bash -# Template file for 'omniroute' -pkgname=omniroute -version=3.4.1 -revision=1 -hostmakedepends="nodejs python3 make" -depends="openssl" -short_desc="Universal AI gateway with smart routing for multiple LLM providers" -maintainer="zenobit " -license="MIT" -homepage="https://github.com/diegosouzapw/OmniRoute" -distfiles="https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz" -checksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b -system_accounts="_omniroute" -omniroute_homedir="/var/lib/omniroute" -export NODE_ENV=production -export npm_config_engine_strict=false -export npm_config_loglevel=error -export npm_config_fund=false -export npm_config_audit=false - -do_build() { - # Determine target CPU arch for node-gyp - local _gyp_arch - case "$XBPS_TARGET_MACHINE" in - aarch64*) _gyp_arch=arm64 ;; - armv7*|armv6*) _gyp_arch=arm ;; - i686*) _gyp_arch=ia32 ;; - *) _gyp_arch=x64 ;; - esac - - # 1) Install all deps – skip scripts (no network in do_build, native modules - # compiled separately below; better-sqlite3 is serverExternalPackage so - # Next.js does not execute it during next build) - NODE_ENV=development npm ci --ignore-scripts - - # 2) Build the Next.js standalone bundle - npm run build - - # 3) Copy static assets into standalone - cp -r .next/static .next/standalone/.next/static - [ -d public ] && cp -r public .next/standalone/public || true - - # 4) Compile better-sqlite3 native binding for the target architecture. - # Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used - # without npm altering them. - local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js - (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch") - - # 5) Place the compiled binding into the standalone bundle - local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release - mkdir -p "$_bs3_release" - cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/" - - # 6) Remove arch-specific sharp bundles – upstream sets images.unoptimized=true - # so sharp is not used at runtime; x64 .so files would break aarch64 strip - rm -rf .next/standalone/node_modules/@img - - # 7) Copy pino runtime deps omitted by Next.js static analysis: - # pino-abstract-transport – required by pino's worker thread - # split2 – dep of pino-abstract-transport - # process-warning – dep of pino itself - for _mod in pino-abstract-transport split2 process-warning; do - cp -r "node_modules/$_mod" .next/standalone/node_modules/ - done -} - -do_check() { - npm run test:unit -} - -do_install() { - vmkdir usr/lib/omniroute/.next - - vcopy .next/standalone/. usr/lib/omniroute/.next/standalone - - # Prevent removal of empty Next.js app router dirs by the post-install hook - for _d in \ - .next/standalone/.next/server/app/dashboard \ - .next/standalone/.next/server/app/dashboard/settings \ - .next/standalone/.next/server/app/dashboard/providers; do - touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep" - done - - cat > "${WRKDIR}/omniroute" <<'EOF' -#!/bin/sh -export PORT="${PORT:-20128}" -export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}" -export APP_LOG_TO_FILE="${APP_LOG_TO_FILE:-false}" -mkdir -p "${DATA_DIR}" -exec node /usr/lib/omniroute/.next/standalone/server.js "$@" -EOF - vbin "${WRKDIR}/omniroute" -} - -post_install() { - vlicense LICENSE -} -``` - -
- ---- - -## 🐳 Docker - -OmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute). - -**Quick run:** - -```bash -docker run -d \ - --name omniroute \ - --restart unless-stopped \ - --stop-timeout 40 \ - -p 20128:20128 \ - -v omniroute-data:/app/data \ - diegosouzapw/omniroute:latest -``` - -**With environment file:** - -```bash -# Copy and edit .env first -cp .env.example .env - -docker run -d \ - --name omniroute \ - --restart unless-stopped \ - --stop-timeout 40 \ - --env-file .env \ - -p 20128:20128 \ - -v omniroute-data:/app/data \ - diegosouzapw/omniroute:latest -``` - -**Using Docker Compose:** - -```bash -# Base profile (no CLI tools) -docker compose --profile base up -d - -# CLI profile (Claude Code, Codex, OpenClaw built-in) -docker compose --profile cli up -d -``` - -Dashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard → Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL. - -Notes: - -- Quick Tunnel URLs are temporary and change after every restart. -- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed. -- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`. -- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport. -- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container. -- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`. -- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup. -- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one. - -**Using Docker Compose with Caddy (HTTPS Auto-TLS):** - -OmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP. - -```yaml -services: - omniroute: - image: diegosouzapw/omniroute:latest - container_name: omniroute - restart: unless-stopped - volumes: - - omniroute-data:/app/data - environment: - - PORT=20128 - - NEXT_PUBLIC_BASE_URL=https://your-domain.com - - caddy: - image: caddy:latest - container_name: caddy - restart: unless-stopped - ports: - - "80:80" - - "443:443" - command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128 - -volumes: - omniroute-data: -``` - -| Image | Tag | Size | Description | -| ------------------------ | -------- | ------ | --------------------- | -| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release | -| `diegosouzapw/omniroute` | `3.6.2` | ~250MB | Current version | - ---- - -## 🖥️ Desktop App — Offline & Always-On - -> 🆕 **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux. - -Run OmniRoute as a standalone desktop app — no terminal, no browser, no internet required for local models. The Electron-based app includes: - -- 🖥️ **Native Window** — Dedicated app window with system tray integration -- 🔄 **Auto-Start** — Launch OmniRoute on system login -- 🔔 **Native Notifications** — Get alerts for quota exhaustion or provider issues -- ⚡ **One-Click Install** — NSIS (Windows), DMG (macOS), AppImage (Linux) -- 🌐 **Offline Mode** — Works fully offline with bundled server - -### Szybki start - -```bash -# Development mode -npm run electron:dev - -# Build for your platform -npm run electron:build # Current platform -npm run electron:build:win # Windows (.exe) -npm run electron:build:mac # macOS (.dmg) — x64 & arm64 -npm run electron:build:linux # Linux (.AppImage) -``` - -### System Tray - -When minimized, OmniRoute lives in your system tray with quick actions: - -- Open dashboard -- Change server port -- Quit application - -📖 Full documentation: [`electron/README.md`](electron/README.md) - ---- - -## 💰 Pricing at a Glance - -| Tier | Provider | Cost | Quota Reset | Best For | -| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- | -| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed | -| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users | -| | GitHub Copilot | $10-19/mo | Monthly | GitHub users | -| **🔑 API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models | -| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest | -| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma | -| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning | -| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** 🆕 | None | Fastest + tool calling, ultralow | -| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M 🆕 | None | Reasoning flagship from xAI | -| | Mistral | Free trial + paid | Rate limited | European AI | -| | OpenRouter | Pay-per-use | None | 100+ models aggr. | -| **💰 CHEAP** | GLM-5 (via Z.AI) 🆕 | $0.5/1M | Daily 10AM | 128K output, newest flagship | -| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup | -| | MiniMax M2.5 🆕 | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks | -| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option | -| | Kimi K2.5 (Moonshot API) 🆕 | Pay-per-use | None | Direct Moonshot API access | -| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost | -| **🆓 FREE** | Qoder | **$0** | Unlimited | 5 models unlimited | -| | Qwen | **$0** | Unlimited | 4 models unlimited | -| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) | -| | LongCat Flash-Lite 🆕 | **$0** (50M tok/day 🔥) | 1 RPS | Largest free quota on Earth | -| | Pollinations AI 🆕 | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 | -| | Cloudflare Workers AI 🆕 | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge | -| | Scaleway AI 🆕 | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B | - -> 🆕 **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms — 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API. - -**💡 $0 Combo Stack — The Complete Free Setup:** - -``` -# 🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever -Kiro (kr/) → Claude Sonnet/Haiku UNLIMITED -Qoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED -LongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥 -Pollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed -Qwen (qw/) → qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED -Gemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free API key -Cloudflare AI (cf/) → Llama 70B, Gemma 3, Mistral — 10K Neurons/day -Scaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU) -Groq (groq/) → Llama/Gemma ultra-fast — 14.4K req/day -NVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever -Cerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day -``` - -**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically — no manual switching ever. - ---- - ---- - -## 🆓 Free Models — What You Actually Get - -> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out — combine them all for an unbreakable $0 combo. - -### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID) - -| Model | Prefix | Limit | Rate Limit | -| ------------------- | ------ | ------------- | --------------------- | -| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap | -| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap | -| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro | - -### 🟢 QODER MODELS (Free PAT via qodercli) - -| Model | Prefix | Limit | Rate Limit | -| ------------------ | ------ | ------------- | --------------- | -| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap | -| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap | -| `deepseek-r1` | `if/` | **Unlimited** | No reported cap | -| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap | -| `kimi-k2` | `if/` | **Unlimited** | No reported cap | - -> Recommended connection method: **Personal Access Token + `qodercli`**. Browser OAuth is -> experimental and disabled by default unless `QODER_OAUTH_*` environment variables are configured. - -### 🟡 QWEN MODELS (Device Code Auth) - -| Model | Prefix | Limit | Rate Limit | -| ------------------- | ------ | ------------- | ------------------- | -| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap | -| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap | -| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap | -| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) | - -### ⚫ NVIDIA NIM (Free API Key — build.nvidia.com) - -| Tier | Daily Limit | Rate Limit | Notes | -| ---------- | ------------ | ----------- | ------------------------------------------------------ | -| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 | - -Popular free models: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct`, `deepseek/deepseek-r1` - -### ⚪ CEREBRAS (Free API Key — inference.cerebras.ai) - -| Tier | Daily Limit | Rate Limit | Notes | -| ---- | ----------------- | ---------------- | ------------------------------------------- | -| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily | - -Available free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b` - -### 🔴 GROQ (Free API Key — console.groq.com) - -| Tier | Daily Limit | Rate Limit | Notes | -| ---- | ------------- | ---------------- | ----------------------------------------- | -| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged | - -Available free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3` - -### 🔴 LONGCAT AI (Free API Key — longcat.chat) 🆕 - -| Model | Prefix | Daily Free Quota | Notes | -| ----------------------------- | ------ | ----------------- | ----------------------- | -| `LongCat-Flash-Lite` | `lc/` | **50M tokens** 💥 | Largest free quota ever | -| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat | -| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT | -| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version | -| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal | - -> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC. - -### 🟢 POLLINATIONS AI (No API Key Required) 🆕 - -| Model | Prefix | Rate Limit | Provider Behind | -| ---------- | ------ | ---------- | ------------------ | -| `openai` | `pol/` | 1 req/15s | GPT-5 | -| `claude` | `pol/` | 1 req/15s | Anthropic Claude | -| `gemini` | `pol/` | 1 req/15s | Google Gemini | -| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 | -| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout | -| `mistral` | `pol/` | 1 req/15s | Mistral AI | - -> ✨ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately. - -### 🟠 CLOUDFLARE WORKERS AI (Free API Key — cloudflare.com) 🆕 - -| Tier | Daily Neurons | Equivalent Usage | Notes | -| ---- | ------------- | --------------------------------------- | ----------------------- | -| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models | - -Popular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct` - -> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings. - -### 🟣 SCALEWAY AI (1M Free Tokens — scaleway.com) 🆕 - -| Tier | Free Quota | Location | Notes | -| ---- | ------------- | ------------ | ----------------------------------- | -| Free | **1M tokens** | 🇫🇷 Paris, EU | No credit card needed within limits | - -Available free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324` - -> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com). - -> **💡 The Ultimate Free Stack (11 Providers, $0 Forever):** -> -> ``` -> Kiro (kr/) → Claude Sonnet/Haiku UNLIMITED -> Qoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED -> LongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥 -> Pollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed -> Qwen (qw/) → qwen3-coder models UNLIMITED -> Gemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free -> Cloudflare AI (cf/) → 50+ models — 10K Neurons/day -> Scaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU) -> Groq (groq/) → Llama/Gemma — 14.4K req/day ultra-fast -> NVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever -> Cerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day -> ``` - -## 🎙️ Free Transcription Combo - -> Transcribe any audio/video for **$0** — Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup. - -| Provider | Free Credits | Best Model | Rate Limit | -| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- | -| 🟢 **Deepgram** | **$200 free** (signup) | `nova-3` — best accuracy, 30+ languages | No RPM limit on free credits | -| 🔵 **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` — chapters, sentiment, PII | No RPM limit on free credits | -| 🔴 **Groq** | **Free forever** | `whisper-large-v3` — OpenAI Whisper | 30 RPM (rate limited) | - -**Suggested combo in `/dashboard/combos`:** - -``` -Name: free-transcription -Strategy: Priority -Nodes: - [1] deepgram/nova-3 → uses $200 free first - [2] assemblyai/universal-3-pro → fallback when Deepgram credits run out - [3] groq/whisper-large-v3 → free forever, emergency fallback -``` - -Then in `/dashboard/media` → **Transcription** tab: upload any audio or video file → select your combo endpoint → get transcription in supported formats. - -## 💡 Key Features - -OmniRoute v3.6 is built as an operational platform, not just a relay proxy. - -### 🆕 New — v3.6.x Highlights (Apr 2026) - -| Feature | What It Does | -| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -| 🌐 **V1 WebSocket Bridge** | OpenAI-compatible WebSocket traffic upgraded and proxied via `/v1/ws` — full streaming over WS with session auth (API key or session cookie) | -| 🔑 **Sync Tokens & Config Bundle** | Issue/revoke sync tokens for config sync endpoints. Config bundles versioned with ETag for bandwidth-efficient polling | -| 🧠 **GLM Thinking (glmt) Preset** | GLM Thinking registered first-class: 65 536 max tokens, 24 576 thinking budget, 900s timeout, usage sync & pricing — Claude-compatible API | -| 🔢 **Hybrid Token Counting** | Uses provider-side `/messages/count_tokens` when available; falls back to estimation — accurate usage tracking without guessing | -| 🌱 **Model Alias Auto-Seed** | 30+ cross-proxy dialect aliases normalised at startup — no more routing mismatches | -| 🛡️ **Safe Outbound Fetch** | All provider validation and model discovery go through a guarded fetch layer blocking private/local URLs with retry, timeout, and SSRF protection | -| ⏳ **Wait For Cooldown** | Server-side chat retries when every candidate connection is cooling down; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` | -| 🔍 **Runtime Env Validation** | Startup validates all env vars with Zod schemas — clear errors for missing secrets, invalid URLs, or wrong types | -| 📋 **Compliance Audit Expansion** | Structured audit logs with pagination, request context, auth events, provider CRUD events, and SSRF-blocked validation logging | -| 🔐 **TPS Log Metric** | Log details modal shows Tokens Per Second (TPS) — quick performance at-a-glance for every request | -| 🗑️ **Uninstall / Full Uninstall** | `npm run uninstall` keeps data, `npm run uninstall:full` removes everything — clean removal for all install methods | -| 🔧 **OAuth Env Repair** | One-click "Repair env" action for OAuth providers restores missing env vars and fixes broken auth state | -| 🔒 **Graceful Electron Shutdown** | Electron `before-quit` shuts down Next.js gracefully, preventing SQLite WAL database locks on desktop close | -| 👁️ **Model Visibility Toggle** | Per-model visibility toggle (👁 icon) with search filter and active-count badge (`N/M active`) on provider pages | -| 📧 **Email Privacy Masking** | OAuth account emails masked (`di*****@g****.com`), full address visible on hover | -| 🔗 **Context Relay Strategy** | Combo strategy preserving session continuity via structured handoff summaries when accounts rotate mid-conversation | -| 🛡️ **Proxy Hardening** | Token health check, API key validation, and undici dispatcher all honor proxy config | -| ⚠️ **Node.js 24 Login Warning** | Login page proactively detects incompatible Node.js versions and shows a clear warning banner | -| 📎 **Gemini PDF Attachments** | PDF attachments correctly routed to Gemini via `inline_data` and generic base64 detection | -| 🔒 **CodeQL Security Hardening** | Resolved SSRF, insecure randomness, polynomial ReDoS, and incomplete URL sanitization alerts | - -### 🆕 New — ClawRouter-Inspired Improvements (Mar 2026) - -| Feature | What It Does | -| ------------------------------------ | ------------------------------------------------------------------------------------------- | -| ⚡ **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M — benchmarked 1143ms (30% faster than Gemini 2.5 Flash) | -| 🧠 **GLM-5 via Z.AI** | 128K output context, $0.5/1M — newest flagship from the GLM family | -| 🔮 **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M — significant upgrade from M2.1 | -| 🎯 **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry — AutoCombo skips non-tool-capable models | -| 🌍 **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring — better model selection for non-English content | -| 📊 **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring — AutoCombo learns from actual data | -| 🔁 **Request Deduplication** | Content-hash based dedup window — multi-agent safe, prevents duplicate charges | -| 🔌 **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface — add custom routing logic as plugins | - -### 🚀 Previous v2.0.9+ — Playground, CLI Fingerprints & ACP - -| Feature | What It Does | -| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 🎮 **Model Playground** | Dashboard page to test any model directly — provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing | -| 🔏 **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures — toggle per provider in Settings > Security. **Your proxy IP is preserved** | -| 🤖 **ACP Agents Dashboard** | Debug › Agents page — grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a "Download opencode.json" button that auto-generates a ready-to-use config with all available models. | -| 🔧 **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: "responses"` now correctly route to the Responses API translator | -| 🏢 **Codex Workspace Isolation** | Multiple Codex workspaces per email — OAuth correctly separates connections by workspace ID | -| 🔄 **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart | - -### 🤖 Agent & Protocol Operations (v2.0) - -| Feature | What It Does | -| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -| 🔧 **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools | -| 🤝 **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | -| 🧭 **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | -| 🎚️ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | -| 🛰️ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | -| 📋 **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | -| 🔐 **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access | -| 📡 **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | -| 📋 **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | -| 🧪 **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | -| ⚙️ **Operational Controls** | Switch combos, tune resilience settings, and review breaker state from dedicated Health and Settings surfaces | - -### 🧠 Routing & Intelligence - -| Feature | What It Does | -| ---------------------------------- | ------------------------------------------------------------------------ | -| 🎯 **Smart 4-Tier Fallback** | Auto-route: Subscription → API Key → Cheap → Free | -| 📊 **Real-Time Quota Tracking** | Live token count + reset countdown per provider | -| 🔄 **Format Translation** | OpenAI ↔ Claude ↔ Gemini ↔ Responses with schema-safe conversions | -| 👥 **Multi-Account Support** | Multiple accounts per provider with intelligent selection | -| 🔄 **Auto Token Refresh** | OAuth tokens refresh automatically with retry | -| 🎨 **Custom Combos** | 13 balancing strategies + fallback chain control | -| 🔗 **Context Relay** | Session continuity handoffs when account rotation happens mid-session | -| 🌐 **Wildcard Router** | `provider/*` dynamic routing | -| 🧠 **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits | -| 🔀 **Model Aliases** | Built-in + custom model aliasing and migration safety | -| ⚡ **Background Degradation** | Route low-priority background tasks to cheaper models | -| 🧪 **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) | -| 🔄 **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions | -| 🔀 **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity | -| 🎲 **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution | -| 💬 **System Prompt Injection** | Global behavior controls applied consistently | -| 📄 **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows | - -### 🎵 Multi-Modal APIs - -| Feature | What It Does | -| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 🖼️ **Image Generation** | `/v1/images/generations` with cloud and local backends | -| 📐 **Embeddings** | `/v1/embeddings` for search and RAG pipelines | -| 🎤 **Audio Transcription** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support | -| 🔊 **Text-to-Speech** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages | -| 🎬 **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) | -| 🎵 **Music Generation** | `/v1/music/generations` (ComfyUI workflows) | -| 🛡️ **Moderations** | `/v1/moderations` safety checks | -| 🔀 **Reranking** | `/v1/rerank` for relevance scoring | -| 🔍 **Web Search** 🆕 | `/v1/search` — 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache | - -### 🛡️ Resilience, Security & Governance - -| Feature | What It Does | -| ----------------------------------- | ------------------------------------------------------------------------------------------------------- | -| 🔌 **Provider Circuit Breakers** | Provider-wide trip/recover after fallback exhaustion with configurable thresholds | -| 🔒 **Daily Quota Lock** 🆕 | Detects exhaustion signals and locks routing for the specific model until midnight | -| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format | -| 🛡️ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events | -| 🧠 **Semantic + Signature Cache** | Cost/latency reduction with two cache layers | -| ⚡ **Request Idempotency** | Duplicate protection window | -| 🔒 **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint — **reduces bot detection and account flagging** | -| 🔏 **CLI Fingerprint Matching** | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP** | -| 🌐 **IP Filtering** | Allowlist/blocklist control for exposed deployments | -| 🚦 **Request Queue & Pacing** | Configurable per-connection request buckets for RPM, spacing, concurrency, and max wait | -| 📉 **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations | -| 📜 **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks | -| ⏳ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures | -| ❄️ **Connection Cooldown** | Retryable 408/429/5xx failures cool down a single connection with optional upstream hints | -| 🚪 **Auto-Disable Banned Accounts** | Permanently blocked token accounts can be disabled automatically | -| 🔑 **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls | -| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` | -| 🛡️ **Protected `/models`** | Optional auth gating and provider hiding for model catalog | -| 🛡️ **Safe Outbound Fetch** 🆕 | Guarded fetch for provider calls — blocks private/local URLs, retries, SSRF protection | -| ⏳ **Wait For Cooldown** 🆕 | Auto-retry chat after connection cooldowns; configurable `enabled`, `maxRetries`, and `maxRetryWaitSec` | -| 🔍 **Runtime Env Validation** 🆕 | Zod-based env schema validation at startup with actionable error messages | -| 📋 **Compliance Audit v2** 🆕 | Pagination, request context, auth events, provider CRUD, and SSRF-blocked logging | - -### 📊 Observability & Analytics - -| Feature | What It Does | -| -------------------------------- | ----------------------------------------------------- | -| 📝 **Request + Proxy Logging** | Full request/response and proxy logging | -| 📉 **Streamed Detailed Logs** | Reconstructs SSE payload streams cleanly into the UI | -| 🏷️ **Real-Time Model Badges** 🆕 | Live model status and daily quota countdown timers | -| 📋 **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page | -| 🔍 **Request Telemetry** | p50/p95/p99 latency and request tracing | -| 🏥 **Health Dashboard** | Uptime, breaker states, lockouts, cache stats | -| 💰 **Cost Tracking** | Budget controls and per-model pricing visibility | -| 📈 **Analytics Visualizations** | Model/provider usage insights and trend views | -| 🧪 **Evaluation Framework** | Golden set testing with configurable match strategies | -| 📡 **Live Diagnostics** 🆕 | Semantic cache bypass for accurate combo live testing | -| 🔐 **TPS Log Metric** 🆕 | Tokens Per Second badge in log details modal | - -### ☁️ Deployment & Platform - -| Feature | What It Does | -| ------------------------------ | --------------------------------------------------------------------- | -| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments | -| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard | -| 🔑 **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles | -| ⚡ **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls | -| 🔄 **Backup/Restore** | Export/import and disaster recovery flows | -| 🧙 **Onboarding Wizard** | First-run guided setup | -| 🔧 **CLI Tools Dashboard** | One-click setup for popular coding tools | -| 🎮 **Model Playground** | Test any provider/model/endpoint from the dashboard | -| 🔏 **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security | -| 🌐 **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage | -| 🧹 **Clear All Models** | One-click model list clearing in provider details | -| 👁️ **Sidebar Controls** 🆕 | Hide components and integrations from Appearance Settings | -| 📋 **Issue Templates** | Standardized GitHub templates for bugs and features | -| 📂 **Custom Data Directory** | `DATA_DIR` override for storage location | -| 🌐 **V1 WebSocket Bridge** 🆕 | OpenAI-compatible WebSocket traffic proxied via `/v1/ws` | -| 🔑 **Sync Tokens & Bundle** 🆕 | Config sync tokens + versioned bundle endpoint with ETag support | - -### Feature Deep Dive - -#### Smart fallback with practical cost control +Jeśli Twój klient nie może wysyłać niestandardowych nagłówków, OmniRoute udostępnia również stokenizowane aliasy zgodności: ```txt -Combo: "my-coding-stack" - 1. cc/claude-opus-4-7 - 2. nvidia/llama-3.3-70b - 3. glm/glm-4.7 - 4. if/kimi-k2-thinking +OpenAI catalog: http://localhost:20128/vscode/TWÓJ_KLUCZ/ +OpenAI models: http://localhost:20128/vscode/TWÓJ_KLUCZ/models +OpenAI chat: http://localhost:20128/vscode/TWÓJ_KLUCZ/chat/completions +OpenAI responses: http://localhost:20128/vscode/TWÓJ_KLUCZ/responses +Ollama chat: http://localhost:20128/vscode/TWÓJ_KLUCZ/api/chat +Ollama tags: http://localhost:20128/vscode/TWÓJ_KLUCZ/api/tags ``` -When quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching. +Używaj ich tylko w przypadku klientów, którzy nie mogą dołączyć nagłówka `Authorization: Bearer ...`. Autoryzacja przez nagłówek pozostaje preferowanym trybem. -#### Protocol management that is visible and operable +
-- MCP + A2A are discoverable in UI and docs (not hidden) -- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`) -- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation) +## 📦 Więcej metod instalacji — Docker, źródła, pnpm, Arch -#### Translator + validation workflow - -The Translator area includes: - -- **Playground**: request transformation checks -- **Chat Tester**: full request/response round-trip -- **Test Bench**: multiple cases in one run -- **Live Monitor**: real-time traffic view - -Plus protocol validation with real clients via `npm run test:protocols:e2e`. - -> 📖 **[MCP Server README](open-sse/mcp-server/README.md)** — Tool reference, IDE configs, and client examples -> -> 📖 **[A2A Server README](src/lib/a2a/README.md)** — Skills, JSON-RPC methods, streaming, and task lifecycle - -## 🧪 Evaluations (Evals) - -OmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics → Evals** in the dashboard. - -### Built-in Golden Set - -The pre-loaded "OmniRoute Golden Set" contains test cases for: - -- Greetings, math, geography, code generation -- JSON format compliance, translation, markdown generation -- Safety refusal (harmful content), counting, boolean logic - -### Evaluation Strategies - -| Strategy | Description | Example | -| ---------- | ------------------------------------------------ | -------------------------------- | -| `exact` | Output must match exactly | `"4"` | -| `contains` | Output must contain substring (case-insensitive) | `"Paris"` | -| `regex` | Output must match regex pattern | `"1.*2.*3"` | -| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` | - ---- - -## 📖 Setup Guide - -### Protocol Setup (MCP + A2A) - -
-🧩 MCP Setup (Model Context Protocol) - -Start MCP transport in stdio mode: +**🐳 Docker** ```bash -omniroute --mcp +docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \ + -p 20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest ``` -Recommended validation flow: - -1. Connect your MCP client over stdio. -2. Run `omniroute_get_health`. -3. Run `omniroute_list_combos`. -4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit. - -Useful APIs for automation: - -- `GET /api/mcp/status` -- `GET /api/mcp/tools` -- `GET /api/mcp/audit` -- `GET /api/mcp/audit/stats` - -
- -
-🤝 A2A Setup (Agent2Agent) - -Discover the agent: +**🛠️ Ze źródeł** ```bash -curl http://localhost:20128/.well-known/agent.json +cp .env.example .env && npm install +PORT=20128 npm run dev ``` -Send a task: +**📦 pnpm** ```bash -curl -X POST http://localhost:20128/a2a \ - -H 'content-type: application/json' \ - -d '{"jsonrpc":"2.0","id":"setup-a2a","method":"message/send","params":{"skill":"quota-management","messages":[{"role":"user","content":"Summarize quota status."}]}}' +pnpm add -g omniroute@latest --allow-build=better-sqlite3 --allow-build=@swc/core && omniroute ``` -Manage lifecycle: - -- `GET /api/a2a/status` -- `GET /api/a2a/tasks` -- `GET /api/a2a/tasks/:id` -- `POST /api/a2a/tasks/:id/cancel` - -Operational UI: - -- `/dashboard/a2a` for task/state/stream observability and smoke actions - -
- -
-🧪 End-to-end protocol validation - -Validate both protocols with real clients: +**🐧 Arch Linux (AUR)** ```bash -npm run test:protocols:e2e +yay -S omniroute-bin && systemctl --user enable --now omniroute.service ``` -This verifies: - -- MCP SDK client connect/list/call -- A2A discovery/send/stream/get/cancel -- Cross-check data in MCP audit and A2A task management APIs - -
- -
-💳 Subscription Providers - -### Claude Code (Pro/Max) +**🔧 Nix (Flake)** ```bash -Dashboard → Providers → Connect Claude Code -→ OAuth login → Auto token refresh -→ 5-hour + weekly quota tracking - -Models: - cc/claude-opus-4-7 - cc/claude-sonnet-4-5-20250929 - cc/claude-haiku-4-5-20251001 -``` - -**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! - -### OpenAI Codex (Plus/Pro) - -```bash -Dashboard → Providers → Connect Codex -→ OAuth login (port 1455) -→ 5-hour + weekly reset - -Models: - cx/gpt-5.2-codex - cx/gpt-5.1-codex-max -``` - -#### Codex Account Limit Management (5h + Weekly) - -Each Codex account now has policy toggles in `Dashboard -> Providers`: - -- `5h` (ON/OFF): enforce the 5-hour window threshold policy. -- `Weekly` (ON/OFF): enforce the weekly window threshold policy. -- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped. -- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically. -- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically. - -Scenarios: - -- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold. -- `5h OFF` + `Weekly ON`: only weekly usage can block the account. -- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account. -- `resetAt` passed: account re-enters rotation automatically (no manual re-enable). - -### GitHub Copilot - -```bash -Dashboard → Providers → Connect GitHub -→ OAuth via GitHub -→ Monthly reset (1st of month) - -Models: - gh/gpt-5 - gh/claude-4.5-sonnet - gh/gemini-3.1-pro-preview -``` - -
- -
-🔑 API Key Providers - -### NVIDIA NIM (FREE developer access — 70+ models) - -1. Sign up: [build.nvidia.com](https://build.nvidia.com) -2. Get free API key (1000 inference credits included) -3. Dashboard → Add Provider → NVIDIA NIM: - - API Key: `nvapi-your-key` - -**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more - -**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation! - -### DeepSeek - -1. Sign up: [platform.deepseek.com](https://platform.deepseek.com) -2. Get API key -3. Dashboard → Add Provider → DeepSeek - -**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` - -### Groq (Free Tier Available!) - -1. Sign up: [console.groq.com](https://console.groq.com) -2. Get API key (free tier included) -3. Dashboard → Add Provider → Groq - -**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` - -**Pro Tip:** Ultra-fast inference — best for real-time coding! - -### OpenRouter (100+ Models) - -1. Sign up: [openrouter.ai](https://openrouter.ai) -2. Get API key -3. Dashboard → Add Provider → OpenRouter - -**Models:** Access 100+ models from all major providers through a single API key. - -**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list. - -
- -
-💰 Cheap Providers (Backup) - -### GLM-4.7 (Daily reset, $0.6/1M) - -1. Sign up: [Zhipu AI](https://open.bigmodel.cn/) -2. Get API key from Coding Plan -3. Dashboard → Add API Key: - - Provider: `glm` - - API Key: `your-key` - -**Use:** `glm/glm-4.7` - -**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. - -### MiniMax M2.1 (5h reset, $0.20/1M) - -1. Sign up: [MiniMax](https://www.minimax.io/) -2. Get API key -3. Dashboard → Add API Key - -**Use:** `minimax/MiniMax-M2.1` - -**Pro Tip:** Cheapest option for long context (1M tokens)! - -### Kimi K2 ($9/month flat) - -1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) -2. Get API key -3. Dashboard → Add API Key - -**Use:** `kimi/kimi-latest` - -**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost! - -
- -
-🆓 FREE Providers (Emergency Backup) - -### Qoder (5 FREE models via OAuth) - -```bash -Dashboard → Connect Qoder -→ Qoder OAuth login -→ Unlimited usage - -Models: - if/kimi-k2-thinking - if/qwen3-coder-plus - if/glm-4.7 - if/minimax-m2 - if/deepseek-r1 -``` - -### Qwen (4 FREE models via Device Code) - -```bash -Dashboard → Connect Qwen -→ Device code authorization -→ Unlimited usage - -Models: - qw/qwen3-coder-plus - qw/qwen3-coder-flash -``` - -### Kiro (Claude FREE) - -```bash -Dashboard → Connect Kiro -→ AWS Builder ID or Google/GitHub -→ Unlimited usage - -Models: - kr/claude-sonnet-4.5 - kr/claude-haiku-4.5 -``` - -
- -
-🎨 Create Combos - -### Example 1: Maximize Subscription → Cheap Backup - -``` -Dashboard → Combos → Create New - -Name: premium-coding -Models: - 1. cc/claude-opus-4-7 (Subscription primary) - 2. glm/glm-4.7 (Cheap backup, $0.6/1M) - 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M) - -Use in CLI: premium-coding -``` - -### Example 2: Free-Only (Zero Cost) - -``` -Name: free-combo -Models: - 1. if/kimi-k2-thinking (unlimited) - 2. qw/qwen3-coder-plus (unlimited) - -Cost: $0 forever! -``` - -
- -
-🔧 CLI Integration - -### Cursor IDE - -``` -Settings → Models → Advanced: - OpenAI API Base URL: http://localhost:20128/v1 - OpenAI API Key: [from OmniRoute dashboard] - Model: cc/claude-opus-4-7 -``` - -### Claude Code - -Use the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually. - -### Codex CLI - -```bash -export OPENAI_BASE_URL="http://localhost:20128" -export OPENAI_API_KEY="your-omniroute-api-key" - -codex "your prompt" -``` - -### OpenClaw - -**Option 1 — Dashboard (recommended):** - -``` -Dashboard → CLI Tools → OpenClaw → Select Model → Apply -``` - -**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`: - -```json -{ - "models": { - "providers": { - "omniroute": { - "baseUrl": "http://127.0.0.1:20128/v1", - "apiKey": "sk_omniroute", - "api": "openai-completions" - } - } - } -} -``` - -> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues. - -### Cline / Continue / RooCode - -``` -Settings → API Configuration: - Provider: OpenAI Compatible - Base URL: http://localhost:20128/v1 - API Key: [from OmniRoute dashboard] - Model: if/kimi-k2-thinking -``` - -### OpenCode - -**Step 1:** Add OmniRoute as a custom provider: - -```bash -opencode -/connect -# Select "Other" → Enter ID: "omniroute" → Enter your OmniRoute API key -``` - -**Step 2:** Create/edit `opencode.json` in your project root: - -```json -{ - "$schema": "https://opencode.ai/config.json", - "provider": { - "omniroute": { - "npm": "@ai-sdk/openai-compatible", - "name": "OmniRoute", - "options": { - "baseURL": "http://localhost:20128/v1" - }, - "models": { - "cc/claude-sonnet-4-20250514": { "name": "Claude Sonnet 4" }, - "gg/gemini-2.5-pro": { "name": "Gemini 2.5 Pro" }, - "if/kimi-k2-thinking": { "name": "Kimi K2 (Free)" } - } - } - } -} -``` - -**Step 3:** Select the model in OpenCode: - -```bash -/models -# Select any OmniRoute model from the list -``` - -> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard. - -
- ---- - -## Rozwiązywanie problemów - -
-Click to expand troubleshooting guide - -**"Language model did not provide messages"** - -- Provider quota exhausted → Check dashboard quota tracker -- Solution: Use combo fallback or switch to cheaper tier - -**Rate limiting** - -- Subscription quota out → Fallback to GLM/MiniMax -- Add combo: `cc/claude-opus-4-7 → glm/glm-4.7 → if/kimi-k2-thinking` - -**OAuth token expired** - -- Auto-refreshed by OmniRoute -- If issues persist: Dashboard → Provider → Reconnect - -**High costs** - -- Check usage stats in Dashboard → Costs -- Switch primary model to GLM/MiniMax - -**Dashboard/API ports are wrong** - -- `PORT` is the canonical base port (and API port by default) -- `API_PORT` overrides only OpenAI-compatible API listener -- `DASHBOARD_PORT` overrides only dashboard/Next.js listener -- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks) - -**Cloud sync errors** - -- Verify `BASE_URL` points to your running instance -- Verify `CLOUD_URL` points to your expected cloud endpoint -- Keep `NEXT_PUBLIC_*` values aligned with server-side values - -**First login not working** - -- Check `INITIAL_PASSWORD` in `.env` -- If unset, fallback password is `123456` - -**No request logs** - -- `call_logs` in SQLite stores summary metadata for the Request Logs table and analytics views -- Detailed request/response payloads are written to `DATA_DIR/call_logs/` as one JSON artifact per request -- Enable pipeline capture from Dashboard → Logs → Request Logs if you need detailed per-stage payloads -- `Export Logs` reads the artifact files on demand, while `Export All` includes the `call_logs/` directory alongside `storage.sqlite` -- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log` -- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed - -**Connection test shows "Invalid" for OpenAI-compatible providers** - -- Many providers don't expose a `/models` endpoint -- OmniRoute v1.0.6+ includes fallback validation via chat completions -- Ensure base URL includes `/v1` suffix - -### 🔐 OAuth on a Remote Server - - - - -> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server** - -The OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with: - -``` -Error 400: redirect_uri_mismatch -``` - -#### Solution: Configure your own OAuth credentials - -You need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI. - -#### Step-by-step - -**1. Open Google Cloud Console** - -Go to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) - -**2. Create a new OAuth 2.0 Client ID** - -- Click **"+ Create Credentials"** → **"OAuth client ID"** -- Application type: **"Web application"** -- Name: anything you like (e.g. `OmniRoute Remote`) - -**3. Add Authorized Redirect URIs** - -In the **"Authorized redirect URIs"** field, add: - -``` -https://your-server.com/callback -``` - -> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`). - -**4. Save and copy the credentials** - -After creating, Google will show the **Client ID** and **Client Secret**. - -**5. Set environment variables** - -In your `.env` (or Docker environment variables): - -```bash -# For Antigravity: -ANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com -ANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret - -GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com -GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret -``` - -**6. Restart OmniRoute** - -```bash -# npm: +# Używając Nix flakes +nix develop npm run dev -# Docker: -docker restart omniroute +# Lub używając devbox +devbox run npm run dev ``` -**7. Try connecting again** +📖 [Podręcznik Docker](../../../docs/guides/DOCKER_GUIDE.md) — Profile Compose, HTTPS przez Caddy, tunele Cloudflare. -Google will now redirect correctly to `https://your-server.com/callback`. - ---- - -#### Temporary workaround (without custom credentials) - -If you don't want to set up your own credentials right now, you can still use the **manual URL flow**: - -1. OmniRoute opens the Google authorization URL -2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server) -3. **Copy the full URL** from your browser's address bar (even if the page doesn't load) -4. Paste that URL into the field shown in the OmniRoute connection modal -5. Click **"Connect"** - -> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded. - ---- - -## 🛠️ Tech Stack - -
-Click to expand tech stack details - -- **Runtime**: Node.js 18–22 LTS (⚠️ Node.js 24+ is **not supported** — `better-sqlite3` native binaries are incompatible) -- **Language**: TypeScript 5.9 — **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) -- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization -- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E) -- **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 - -
- ---- - -## Dokumentacja - -| Document | Description | -| --------------------------------------------------------------------- | --------------------------------------------------- | -| [User Guide](docs/guides/USER_GUIDE.md) | Providers, combos, CLI integration, deployment | -| [API Reference](docs/reference/API_REFERENCE.md) | All endpoints with examples | -| [MCP Server](open-sse/mcp-server/README.md) | 25 MCP tools, IDE configs, Python/TS/Go clients | -| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt | -| [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing | -| [Context Relay](docs/features/context-relay.md) | Session handoff strategy for account rotation | -| [Troubleshooting](docs/guides/TROUBLESHOOTING.md) | Common problems and solutions | -| [Architecture](docs/architecture/ARCHITECTURE.md) | System architecture and internals | -| [Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough | -| [Uninstall Guide](docs/guides/UNINSTALL.md) | Clean removal for all install methods | -| [Environment Config](docs/reference/ENVIRONMENT.md) | Complete `.env` variables and references | -| [Contributing](CONTRIBUTING.md) | Development setup and guidelines | -| [OpenAPI Spec](docs/reference/openapi.yaml) | OpenAPI 3.0 specification | -| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices | -| [VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup | -| [Features Gallery](docs/guides/FEATURES.md) | Visual dashboard tour with screenshots | -| [Release Checklist](docs/ops/RELEASE_CHECKLIST.md) | Pre-release validation steps | - ---- - -## 🗺️ Roadmap - -OmniRoute has **218+ features planned** across multiple development phases. Here are the key areas: - -| Category | Planned Features | Highlights | -| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- | -| 🧠 **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, quota-aware P2C, step-based combo routing | -| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping | -| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, combo target health, cost tracking per model | -| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, connection cooldowns, multi-account Codex, Copilot quota parsing | -| ⚡ **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API | -| 🌐 **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode | - -### 🔜 Coming Soon - -- 🔗 **OpenCode Integration** — Native provider support for the OpenCode AI coding IDE -- 🔗 **TRAE Integration** — Full support for the TRAE AI development framework -- 📦 **Batch API** — Asynchronous batch processing for bulk requests -- 🎯 **Tag-Based Routing** — Route requests based on custom tags and metadata -- 💰 **Lowest-Cost Strategy** — Automatically select the cheapest available provider - -> 📝 Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs) - ---- - -## 👥 Contributors - -[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](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 +**🦭 Podman** ```bash -# Create a release — npm publish happens automatically -gh release create v2.0.0 --title "v2.0.0" --generate-notes +# 1. Zbuduj obraz +podman build --target runner-base -t omniroute:base . + +# 2. Napraw uprawnienia katalogu danych dla Podmana bez roota +mkdir -p data && podman unshare chown 1000:1000 ./data + +# 3. Ustaw środowisko wykonawcze w .env, a następnie uruchom (zobacz contrib/podman/ dla Quadlet) +echo "CONTAINER_HOST=podman" >> .env +podman compose --profile base up -d ``` +📖 [Podręcznik Podman](../../../contrib/podman/README.md) — Integracja Quadlet z systemd, podman-compose, Quadlet. + +**⚡ Szybsza / lżejsza instalacja (pomiń budowanie natywne)** + +Natywny silnik SQLite (`better-sqlite3`) jest zależnością **opcjonalną**, więc globalna instalacja nigdy nie blokuje się na kompilacji ze źródeł: używa prekompilowanego pliku binarnego, jeśli pasuje do Twojej platformy/Node, a w przeciwnym razie przezroczyście przełącza się na silnik czystego JS (`node:sqlite` na Node 22+, w przeciwnym razie dołączony `sql.js` WASM) — nie są wymagane żadne narzędzia budowania. + +Aby całkowicie pominąć natywne przygotowanie po instalacji (CI, tryb bezgłowy/headless lub wolne maszyny): + +```bash +OMNIROUTE_SKIP_POSTINSTALL=1 npm install -g omniroute # CI=1 również to pomija +``` + +W celu uzyskania najszybszej instalacji preferuj **pnpm** (magazyn adresowany treścią + twarde dowiązania — patrz wyżej). Dla środowiska bez panelu graficznego (headless) użyj profilu Docker `base` (powyżej) lub podręcznika Termux. CLI i panel webowy są obsługiwane przez ten sam proces na jednym porcie, więc obecnie nie ma osobnego pakietu wyłącznie z CLI. + +
+ +
+ +# 🎬 OmniRoute w akcji + +
+ +
+ + + + + + +
+ Guia em Português
+ 🇧🇷 Português
Pełny przewodnik + 		+ English Guide
+ 🇺🇸 English
Pełne omówienie + 		+ Руководство
+ 🇷🇺 Русский
Pełny przewodnik +
+
+ +
+ +> 🎬 **Nagrałeś film o OmniRoute?** Otwórz [zgłoszenie (issue)](https://github.com/diegosouzapw/OmniRoute/issues/new) lub [dyskusję (discussion)](https://github.com/diegosouzapw/OmniRoute/discussions) z linkiem — umieścimy go tutaj. + +
+
+ +
+ +# 📸 Zrzuty ekranu z panelu + +
+ +| Strona | Zrzut ekranu | Strona | Zrzut ekranu | +| ---------- | ------------------------------------------------- | ---------- | --------------------------------------------- | +| Dostawcy | ![Providers](../../../docs/screenshots/01-providers.png) | Komba | ![Combos](../../../docs/screenshots/02-combos.png) | +| Analityka | ![Analytics](../../../docs/screenshots/03-analytics.png) | Stan techniczny | ![Health](../../../docs/screenshots/04-health.png) | +| Tłumacz | ![Translator](../../../docs/screenshots/05-translator.png) | Ustawienia | ![Settings](../../../docs/screenshots/06-settings.png) | +| Narzędzia CLI | ![CLI Tools](../../../docs/screenshots/07-cli-tools.png) | Logi użycia | ![Usage](../../../docs/screenshots/08-usage.png) | + +
+ +
+ +# 📧 Wsparcie i społeczność + +> 💬 **Rozmawiaj ze społecznością** — linki do Discorda, Telegrama i WhatsAppa (🌍 / 🇧🇷) znajdują się na [górze tego pliku README](#-do%C5%82%C4%85cz-do-spo%C5%82eczno%C5%9Bci). + +- 🌍 **Strona internetowa**: [omniroute.online](https://omniroute.online) +- 🐙 **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute) +- 🐛 **Zgłoszenia (Issues)**: [zgłoś błąd](https://github.com/diegosouzapw/OmniRoute/issues) (dołącz wynik działania komendy `npm run system-info`) +- 🤝 **Współtworzenie**: zobacz [CONTRIBUTING.md](CONTRIBUTING.md) lub wybierz zadanie typu `good first issue` + +
+ --- -## 📊 Star History +
+
- +## 🛠️ Stos technologiczny + +
+ +- **Środowisko uruchomieniowe**: Node.js 22.x lub 24.x LTS (zalecane 24 LTS) — `>=22.22.2 <23 || >=24.0.0 <27` +- **Język**: TypeScript 6.0 — **100% TypeScript** w `src/` oraz `open-sse/` (zero typów `any` w modułach rdzenia od wersji v2.0) +- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4 +- **Baza danych**: better-sqlite3 (SQLite) + LowDB (spuścizna JSON) — stan domeny, logi proxy, audyt MCP, decyzje o routingu, pamięć, umiejętności +- **Schematy**: Zod (walidacja wejścia/wyjścia narzędzi MCP, kontrakty API) +- **Protokoły**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE) +- **Strumieniowanie**: Server-Sent Events (SSE) + most WebSocket (`/v1/ws`) +- **Uwierzytelnianie**: OAuth 2.0 (PKCE) + JWT + Klucze API + Autoryzacja zakresów MCP +- **Testowanie**: Node.js test runner + Vitest (**ponad 25 000 przypadków testowych** w ponad 3300 plikach — jednostkowe, integracyjne, E2E, bezpieczeństwo, ekosystem) +- **Platformy**: Desktop (Electron), Android (Termux), PWA (dowolna przeglądarka) +- **CI/CD**: GitHub Actions (automatyczna publikacja w npm + Docker Hub przy wydaniu wersji) +- **Strona WWW**: [omniroute.online](https://omniroute.online) +- **Pakiet**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute) +- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute) +- **Odporność**: Wyłącznik awaryjny (circuit breaker), wykładnicze opóźnienie (exponential backoff), ochrona przed kumulacją zapytań (anti-thundering herd), podszywanie się pod TLS, samonaprawiające się auto-kombo + +
+ +
+ +## 📖 Dokumentacja + +
+ +### 📘 Wprowadzenie + +| Dokument | Opis | +| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| [Podręcznik użytkownika](docs/guides/USER_GUIDE.md) | Dostawcy, komba, integracja CLI, wdrażanie | +| [Podręcznik instalacji](../../../docs/guides/SETUP_GUIDE.md) | Pełne metody instalacji, konfiguracje narzędzi CLI, konfiguracja protokołów, dostrajanie limitów czasu (timeout) | +| [Podręcznik narzędzi CLI](docs/reference/CLI-TOOLS.md) | Konfiguracja per narzędzie dla Claude Code, Codex, Cursor, Cline, OpenClaw, Kilo, Copilot | +| [Tryb zdalny](../../../docs/guides/REMOTE-MODE.md) | Steruj zdalnym OmniRoute (VPS) z poziomu CLI na swoim laptopie za pomocą tokenów o ograniczonym zakresie | +| [Konfiguracja Claude Code](../../../docs/guides/CLAUDE-CODE-CONFIGURATION.md) | Skieruj Claude Code na OmniRoute (lokalnie/zdalnie) za pomocą polecenia launch + profili dla poszczególnych modeli | +| [Szybki start](#-szybki-start) | 3-krokowa instalacja → połącz → skonfiguruj | + +### 🔧 Administracja i wdrażanie + +| Dokument | Opis | +| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Podręcznik Docker](../../../docs/guides/DOCKER_GUIDE.md) | Uruchamianie w Dockerze, profile Compose, HTTPS przez Caddy, tunele, tagi obrazów | +| [Podręcznik Podman](../../../contrib/podman/README.md) | Integracja Quadlet z systemd, podman-compose, SELinux | +| [Wdrożenie na VM](docs/ops/VM_DEPLOYMENT_GUIDE.md) | Pełny poradnik: konfiguracja VM + nginx + Cloudflare | +| [Wdrożenie na Fly.io](docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) | Wdrażanie na Fly.io z trwałą pamięcią masową | +| [Podręcznik Termux](../../../docs/guides/TERMUX_GUIDE.md) | Uruchamianie OmniRoute na systemie Android za pomocą Termux | +| [Podręcznik PWA](../../../docs/guides/PWA_GUIDE.md) | Instalacja Progressive Web App, buforowanie, architektura | +| [Podręcznik odinstalowywania](docs/guides/UNINSTALL.md) | Czyste usuwanie dla wszystkich metod instalacji | +| [Konfiguracja środowiska](docs/reference/ENVIRONMENT.md) | Pełny wykaz zmiennych .env i referencji | + +### 🧠 Funkcje i architektura + +| Dokument | Opis | +| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| [Architektura](docs/architecture/ARCHITECTURE.md) | Architektura systemu, przepływ danych i mechanizmy wewnętrzne | +| [Podręcznik kompresji](../../../docs/compression/COMPRESSION_GUIDE.md) | 7-opcjowy potok: wyłączona / lite / standard / aggressive / ultra / RTK / kaskadowa | +| [Kompresja RTK](../../../docs/compression/RTK_COMPRESSION.md) | Kompresja danych wyjściowych komend, filtry, zaufanie, weryfikacja, odzyskiwanie surowego wyjścia | +| [Silniki kompresji](../../../docs/compression/COMPRESSION_ENGINES.md) | Caveman, RTK, potoki kaskadowe, interfejsy panelu/API/MCP | +| [Format reguł kompresji](../../../docs/compression/COMPRESSION_RULES_FORMAT.md) | Schematy JSON pakietów reguł dla filtrów Caveman i RTK | +| [Pakiety językowe kompresji](../../../docs/compression/COMPRESSION_LANGUAGE_PACKS.md) | Wykrywanie języka i tworzenie pakietów reguł Caveman | +| [Podręcznik odporności](../../../docs/architecture/RESILIENCE_GUIDE.md) | Wyłączniki awaryjne, czasy schładzania, kolejka, ochrona przed kumulacją zapytań, podszywanie się pod TLS | +| [Silnik Auto-Combo](docs/routing/AUTO-COMBO.md) | Ocenianie na bazie 12 czynników, pakiety trybów, samonaprawianie | +| [Podręcznik proxy](../../../docs/ops/PROXY_GUIDE.md) | 3-poziomowy system proxy, rynek 1proxy, rejestr CRUD | +| [Darmowe poziomy](../../../docs/reference/FREE_TIERS.md) | Skonsolidowany katalog ponad 25 darmowych dostawców API | +| [Galeria funkcji](docs/guides/FEATURES.md) | Wizualny przegląd panelu ze zrzutami ekranu | +| [Dokumentacja kodu źródłowego](docs/architecture/CODEBASE_DOCUMENTATION.md) | Przyjazne dla początkujących omówienie bazy kodu | + +### 🤖 Protokoły i API + +| Dokument | Opis | +| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Referencja API](docs/reference/API_REFERENCE.md) | Wszystkie punkty końcowe z przykładami | +| [Specyfikacja OpenAPI](../../../docs/openapi.yaml) | Specyfikacja OpenAPI 3.0 | +| [Serwer MCP](../../../open-sse/mcp-server/README.md) | 104 narzędzia MCP, konfiguracje IDE, klienci Python/TS/Go | +| [Podręcznik serwera MCP](docs/frameworks/MCP-SERVER.md) | Instalacja MCP, protokoły transportowe i referencja narzędzi | +| [Serwer A2A](../../../src/lib/a2a/README.md) | Protokół JSON-RPC 2.0, umiejętności, strumieniowanie, zarządzanie zadaniami | +| [Podręcznik serwera A2A](docs/frameworks/A2A-SERVER.md) | Karta agenta A2A, zadania, umiejętności i strumieniowanie | + +### 📋 Projekt i Jakość + +| Dokument | Opis | +| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Współtworzenie](CONTRIBUTING.md) | Konfiguracja środowiska deweloperskiego i wytyczne | +| [Dziennik zmian](CHANGELOG.md) | Pełna historia wydań dla każdej wersji | +| [Polityka bezpieczeństwa](SECURITY.md) | Zgłaszanie podatności i praktyki bezpieczeństwa | +| [Podręcznik i18n](docs/guides/I18N.md) | Obsługa ponad 40 języków, przepływ tłumaczeń, kierunek tekstu RTL | +| [Lista kontrolna wydania](docs/ops/RELEASE_CHECKLIST.md) | Kroki walidacji przedwydaniowej | +| [Plan pokrycia testami](docs/ops/COVERAGE_PLAN.md) | Strategia pokrycia testami i zestaw ponad 25 000 testów | + +
+ +
+ +# ⭐ Główni autorzy + +> OmniRoute jest kształtowane przez pasjonatów ze społeczności open-source. Te osoby wniosły wyjątkowy wkład, który bezpośrednio wpływa na jakość, stabilność i zasięg projektu. **Dziękujemy.** + + + + + + + + + + + + + + + + +
+ + oyi77
+ oyi77 +
+ 🥇 207 commits • +114K lines
+ Silnik analityczny, agregacje SQL,
rynek proxy, pokrycie testami + 		+ + R.D. & Randi
+ R.D. & Randi +
+ 🥈 108 commits • +38K lines
+ Strona punktów końcowych, integracje tuneli,
przepływy pracy Docker, status A2A, interfejs kompresji + 		+ + Chris Staley
+ Chris Staley +
+ 🥉 70 commits • +1.8K lines
+ Wzmocnienie strumienia SSE, API Responses,
stronicowanie Gemini, poprawki regresji testów + 		+ + zenobit
+ zenobit +
+ 🏅 62 commits • +22K lines
+ Potok CI/CD, i18n dla 33 języków,
pakiet dla Void Linux, poprawki platformy + 		+ + Jan Leon
+ Jan Leon +
+ 🏅 52 commits • +22K lines
+ Routing uwzględniający moc rozumowania, kontrola proxy,
widoczność limitów, kompresja Live Zone +
+ + Chirag Singhal
+ Chirag Singhal +
+ 🏅 46 commits • +4.8K lines
+ Oczyszczanie błędów, poprawka autouzupełniania MITM,
sędzia fusion, poprawność obsługi wyłącznika awaryjnego/429 + 		+ + backryun
+ backryun +
+ 🏅 43 commits • +70K lines
+ Utrzymanie katalogu dostawców — aktualizacje dla Perplexity, Kimi,
Cerebras, Copilot, LMArena + 		+ + kfiramar
+ kfiramar +
+ 🏅 38 commits • +1.7K lines
+ Obsługa websocket i passthrough dla Codex, autoryzacja/onboarding,
wzmocnienie Electron, migracje baz danych + 		+ + Benson K B
+ Benson K B +
+ 🏅 28 commits • +9.2K lines
+ Aplikacja desktopowa Electron, automatyczny instalator aktualizacji,
przepływy budowania wydań, wieloplatformowe CI + 		+ + Hernan J. Ardila
+ Hernan J. Ardila +
+ 🏅 22 commits • +174K lines
+ Komba o zerowym opóźnieniu, auto-routing mostu wizyjnego,
długość kontekstu w katalogu, wskazówki odporności dla błędów 429 +
+ +> 🙏 Funkcje, poprawki błędów i ulepszenia infrastruktury wprowadzone przez tych autorów stanowią **kluczową część** tego, co czyni OmniRoute niezawodnym i bogatym w funkcje. Każde żądanie ściągnięcia (pull request), każdy przypadek testowy i każdy plik tłumaczenia i18n ma znaczenie. Open source tworzą ludzie tacy jak oni. + +
+ +--- + +
+ +
+ +## 👥 Ponad 350 współtwórców + +
+ +[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=400&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors) + +### Jak współtworzyć + +1. Sforkuj repozytorium +2. Utwórz gałąź dla swojej funkcji (`git checkout -b feature/amazing-feature`) +3. Zatwierdź swoje zmiany (`git commit -m 'Add amazing feature'`) +4. Wypchnij zmiany do gałęzi (`git push origin feature/amazing-feature`) +5. Otwórz Pull Request + +Szczegółowe wytyczne znajdziesz w [CONTRIBUTING.md](CONTRIBUTING.md). + +### Wydawanie nowej wersji + +```bash +# Utwórz wydanie — publikacja w npm następuje automatycznie +gh release create v3.8.2 --title "v3.8.2" --generate-notes +``` + +
+ +
+ +## 📊 Gwiazdki + + - - - Star History Chart + + + Star History Chart +
+ + -## 🙏 Acknowledgments - -Special thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port. - ---- - -## Licencja - -MIT License - see [LICENSE](LICENSE) for details. - ---- +
- Built with ❤️ for developers who code 24/7 -
- omniroute.online + +## 🙏 Podziękowania + +
+ +OmniRoute stoi na barkach gigantów. Projekt powstał jako fork **[9router](https://github.com/decolua/9router)** oraz port na TypeScript projektu w Go **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — a stamtąd każdy z poniższych podsystemów był inspirowany projektem open-source, który powstał wcześniej. Każdy z nich ukształtował konkretny element OmniRoute. To jest nasze podziękowanie dla nich wszystkich. 🙏 + +> ⭐ liczba gwiazdek na lipiec 2026 r. — zachęcamy do dodania gwiazdki tym projektom. + +### 🧬 Rodowód i bramka (gateway) + +| Projekt | ⭐ | Jak zainspirował OmniRoute | +| ------------------------------------------------------------------------------- | ----: | ------------------------------------------------------------------------------------------------------------------------------------- | +| **[9router](https://github.com/decolua/9router)** · decolua | 22.7k | Oryginalny projekt, na którym opiera się ten fork — rozbudowany tutaj o wielomodalne API i pełne przepisanie na TypeScript. | +| **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** · router-for-me | 43.6k | Implementacja w Go, która zainspirowała ten port na JavaScript / TypeScript. | +| **[LiteLLM](https://github.com/BerriAI/litellm)** · BerriAI | 54.0k | Bramka AI, której publiczny zbiór danych o cenach zasila naszą synchronizację śledzenia kosztów, a jej model normalizacji dostawców wpłynął na nasz routing. | + +### 🗜️ Kompresja kontekstu i tokenów — silniki + +| Projekt | ⭐ | Jak zainspirował OmniRoute | +| ----------------------------------------------------------------------------- | ----: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **[Caveman](https://github.com/JuliusBrussee/caveman)** · JuliusBrussee | 90.8k | Wirusowy projekt "po co używać wielu tokenów, skoro kilka wystarczy" — jego filozofia "mowy jaskiniowca" zasila nasz standardowy tryb kompresji i ponad 30 reguł usuwania wypełniaczy/kondensacji. | +| **[RTK – Rust Token Killer](https://github.com/rtk-ai/rtk)** · rtk-ai | 71.8k | Wydajna kompresja danych wyjściowych komend — zainspirowała nasz silnik RTK, DSL filtrów JSON, odzyskiwanie surowego wyjścia oraz kaskadowy potok RTK → Caveman. | +| **[headroom](https://github.com/headroomlabs-ai/headroom)** · headroomlabs-ai | 60.1k | Odwracalna kompresja kontekstu (SmartCrusher) — zainspirowała nasz silnik headroom oraz wzorzec znaczników pobierania ccr. | +| **[LLMLingua](https://github.com/microsoft/LLMLingua)** · Microsoft | 6.5k | Badania nad kompresją promptów (LLMLingua / LLMLingua-2) — zainspirowały nasz asynchroniczny, bezpieczny dla kodu i odporny na błędy (fail-open) silnik llmlingua. | +| **[llmlingua-2-js](https://github.com/atjsh/llmlingua-2-js)** · atjsh | 30 | Port JS/ONNX (MobileBERT / XLM-RoBERTa) używany jako backend wątku roboczego (worker thread) dla naszego silnika LLMLingua. | +| **[Troglodita](https://github.com/leninejunior/troglodita)** · Lenine Júnior | 26 | Kompresja tokenów dla języka portugalskiego (brazylijskiego) — zasila nasz pakiet językowy pt-BR: redukcja pleonazmów i usuwanie wypełniaczy dostosowane do gramatyki brazylijskiej odmiany języka portugalskiego. | +| **[ponytail](https://github.com/DietrichGebert/ponytail)** · DietrichGebert | 86.0k | Wirusowa umiejętność "leniwego programisty seniora" stosującego zasadę YAGNI — zainspirowała nasz styl wyjściowy less-code: sterowanie najmniejszą działającą zmianą, które ogranicza wygenerowany kod (odpowiednik zwięzłej prozy Cavemana na osi wyjściowej). | + +### 🧩 Kompaktowe formaty, badania nad tokenami i narzędzia analizujące kod + +| Projekt | ⭐ | Jak zainspirował OmniRoute | +| ---------------------------------------------------------------------------------------------- | ----: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **[TOON](https://github.com/toon-format/toon)** · toon-format | 24.9k | Token-Oriented Object Notation — jego kolumnowy model oparty na nagłówkach i wierszach ukształtował nasz etap tabelarycznego upakowania. | +| **[GCF – Graph Compact Format](https://github.com/blackwell-systems/gcf)** · Blackwell Systems | 22 | Najpierw zainspirował nasz etap tabelarycznego upakowania; teraz jego bezstratny koder profili ogólnych bez zewnętrznych zależności jest bezpośrednio wbudowany (vendored) jako kodek Headroom (licencja MIT, oznaczenie SPDX), zgodny z wersją v3.2 specyfikacji GCF. | +| **[token-optimizer-mcp](https://github.com/ooples/token-optimizer-mcp)** · ooples | 444 | Pamięć podręczna Brotli/SQLite + delta kontekstu na sesję — zainspirowały nasz silnik session-dedup. | +| **[token-savior](https://github.com/Mibayy/token-savior)** · Mibayy | 1.1k | Upakowanie danych wyjściowych basha + profile MCP — zainspirowały naszą dyscyplinę wycofywania się z kompresji (bail-out) oraz redukcję kardynalności manifestu narzędzi MCP. | +| **[token-saver](https://github.com/ppgranger/token-saver)** · ppgranger | 117 | Zorientowana na treść kompresja wyjściowa per typ pliku z wycofywaniem się w razie błędów — potwierdziła nasze podejście do obsługi per typ oraz pomijania przy minimalnym zysku. | +| **[token-optimizer](https://github.com/alexgreensh/token-optimizer)** · alexgreensh | 1.7k | "Znajdź duchy-tokeny" — jego wzorzec odciążania i odzyskiwalnych uchwytów wpłynął na naszą koncepcję odciążania CCR. | +| **[TokenMizer](https://github.com/Shweta-Mishra-ai/tokenmizer)** · Shweta-Mishra-ai | 16 | Schemat grafu sesji + deduplikacji linii między turami, który wpłynął na projekt naszego session-dedup. | +| **[OmniCompress](https://github.com/jessefreitas/OmniCompress)** · jessefreitas | 3 | Kolumnowy JSON w Rust + pobieranie adresowane treścią + deduplikacja między wiadomościami — potwierdziły poprawność projektu naszych silników headroom/ccr/session-dedup oraz stabilnego dla cache niezmiennika "skompresowana forma jest niezależna od pozycji". | +| **[mcp-compressor](https://github.com/atlassian-labs/mcp-compressor)** · Atlassian Labs | 98 | Kompresja schematów/opisów narzędzi MCP — wpłynęła na redukcję kardynalności manifestu narzędzi MCP. | +| **[RepoMapper](https://github.com/pdavis68/RepoMapper)** · pdavis68 | 187 | Ranking mapy repozytorium w stylu Aider — wpłynął na nasze badania nad mapami repozytoriów i rankingami wyszukiwania. | +| **[quiet-shell-mcp](https://github.com/mrsimpson/quiet-shell-mcp)** · mrsimpson | 4 | Deklaratywna redukcja danych wyjściowych powłoki przez MCP — potwierdziła poprawność naszego deklaratywnego upakowania wyjścia basha. | +| **[ts-morph](https://github.com/dsherret/ts-morph)** · David Sherret | 6.1k | Zestaw narzędzi TypeScript Compiler API — zainspirował nasze usuwanie komentarzy oparte na parserze, które zachowuje ciągi znaków, szablony i literały wyrażeń regularnych. | + +### 🧠 Pamięć i RAG + +| Projekt | ⭐ | Jak zainspirował OmniRoute | +| ------------------------------------------------------------------ | ----: | ------------------------------------------------------------------------------------------------------------------- | +| **[Mem0](https://github.com/mem0ai/mem0)** · mem0ai | 61.2k | Uniwersalna warstwa pamięci — jej model proxy jako granicy zapisu/odczytu ukształtował naszą architekturę pamięci. | +| **[Letta (MemGPT)](https://github.com/letta-ai/letta)** · letta-ai | 23.9k | Agenci stanowi z warstwową pamięcią — zainspirowali nasz warstwowy model Context Control & Recovery (CCR). | +| **[WFGY](https://github.com/onestardao/WFGY)** · onestardao | 1.8k | Taksonomia ProblemMap obejmująca 16 powtarzających się trybów awarii RAG/LLM — wspólny słownik w naszym podręczniku rozwiązywania problemów. | + +### 🛰️ Inspekcja ruchu, MITM i przezroczyste proxy + +| Projekt | ⭐ | Jak zainspirował OmniRoute | +| --------------------------------------------------------------------------------- | ---: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **[llm-interceptor](https://github.com/chouzz/llm-interceptor)** · chouzz | 49 | Przechwytywanie/analiza MITM ruchu asystent kodowania ↔ LLM — nasz Inspektor Ruchu przenosi jego scalanie SSE, normalizację rozmowy, przepuszczanie hosta i maskowanie sekretów (MIT). | +| **[ProxyBridge](https://github.com/InterceptSuite/ProxyBridge)** · InterceptSuite | 5.5k | Przezroczysty routing proxy per proces — zainspirował nasze odporne na awarie zamykanie MITM, limity bezczynności gniazd, atrybucję procesów przez `/proc` i przechwytywanie TPROXY. | + +### 📚 Dane modeli, obserwowalność i UI + +| Projekt | ⭐ | Jak zainspirował OmniRoute | +| -------------------------------------------------------------------------- | ----: | -------------------------------------------------------------------------------------------------------------------------- | +| **[models.dev](https://github.com/anomalyco/models.dev)** · SST / OpenCode | 6.0k | Otwarta baza danych specyfikacji modeli AI, cen i możliwości — synchronizowana natywnie z naszym katalogiem modeli. | +| **[React Flow / xyflow](https://github.com/xyflow/xyflow)** · xyflow | 37.7k | Oparta na węzłach biblioteka wykresów zasilająca nasze działające w czasie rzeczywistym Studio Kompresji oraz Studio Komb/Routingu. | +| **[LangGraph](https://github.com/langchain-ai/langgraph)** · LangChain | 37.6k | Wizualizacja grafu przepływu pracy na żywo z LangGraph Studio zainspirowała widok kaskadowy w czasie rzeczywistym w naszych Studiach. | +| **[Langfuse](https://github.com/langfuse/langfuse)** · Langfuse | 31.4k | Jej model obserwowalności ślad → rozpiętość → generowanie (trace → span → generation) ukształtował widok kaskadowy (waterfall) w naszym Studiu Kompresji. | +| **[Kiali](https://github.com/kiali/kiali)** · Kiali | 3.6k | Obserwowalność siatki usług Istio — zainspirowała nasze plakietki wyłączników awaryjnych oraz wizualizacje krawędzi błędów w Studiu Routingu/Komb. | +| **[lobe-icons](https://github.com/lobehub/lobe-icons)** · LobeHub | 2.2k | Logotypy marek AI/LLM, które renderują ikony dostawców w naszym panelu. | + +### 🛡️ Bezpieczeństwo + +| Projekt | ⭐ | Jak zainspirował OmniRoute | +| ------------------------------------------------------------------------------------------- | --: | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| **[awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults)** · tldrsec | 710 | Starannie dobrana lista domyślnie bezpiecznych bibliotek, która kieruje naszymi wyborami w zakresie bezpieczeństwa (Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink). | + +### 🧭 Narzędzia uzupełniające + +| Projekt | Jak współgra z OmniRoute | +| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **[CodeWebChat](https://github.com/robertpiosik/CodeWebChat)** · robertpiosik | Towarzysz po stronie edytora — rozszerzenie VS Code + przeglądarki, które automatycznie uzupełnia ponad 15 interfejsów webowych chatbotów kontekstem z edytora. Obsługuje ścieżkę darmowego UI webowego obok ścieżki API OmniRoute; pozwala skierować swój tryb API na OmniRoute. | + +## 💖 Sponsorzy + +> **Chcesz się tutaj pojawić?** OmniRoute prezentuje sponsorów przed jedną z najszybciej rozwijających się społeczności bramki AI na GitHubie — i publicznie informujemy, dokąd trafia każdy sponsorowany token. Skontaktuj się z nami: [diegosouza.pw@outlook.com](mailto:diegosouza.pw@outlook.com) + + + + + + +
+ Kimi (Moonshot AI) +
Kimi
Moonshot AI

+ Oficjalny wspierający + 		+ Dziękujemy firmie Kimi (Moonshot AI) za sponsorowanie tego projektu! Kimi to laboratorium AI stojące za otwartymi rodzinami modeli K2 i K3 — Kimi K3 zapewnia okno kontekstowe o rozmiarze 1M tokenów, natywną obsługę wizji oraz możliwości kodowania na najwyższym poziomie za ułamek ceny modeli zamkniętych, i działa od razu z Claude Code, Codex oraz każdym narzędziem programistycznym obsługiwanym przez OmniRoute. +

+ Na co przeznaczane jest sponsorowanie: Kredyty API Kimi zasilają nasz potok wydań walidowany przez AI — etap walidacji scalania opartej na Kimi K3, który analizuje każde żądanie ściągnięcia przed jego wysłaniem — oraz codzienne rozwijanie funkcji. Pełna obsługa Kimi jest dostarczana na obu ścieżkach: bezpośredniego Moonshot API (kimi-k3) oraz planu kodowania Kimi Code (OAuth i klucz API). Pobierz klucz API Moonshot → +
+ +## ❤️ Wsparcie + +OmniRoute jest darmowym projektem o otwartym kodzie źródłowym, tworzonym i utrzymywanym jawnie. Jeśli pozwala Ci zaoszczędzić czas lub pieniądze, rozważ wsparcie rozwoju: + +- ⭐ **Dodaj gwiazdkę do repozytorium** — to naprawdę pomaga w widoczności +- 💖 **[Sponsorzy GitHub](https://github.com/sponsors/diegosouzapw)** — finansuj bieżące utrzymanie i nowych dostawców +- 🐛 **Zgłaszaj błędy i dziel się opiniami** w [Dyskusjach](https://github.com/diegosouzapw/OmniRoute/discussions) + +## 📄 Licencja + +Licencja MIT — szczegóły znajdziesz w pliku [LICENSE](../../../LICENSE). + +--- + +
+
+ +**[⬆ Powrót do góry](#-omniroute--darmowa-bramka-ai)** · Stworzono z ❤️ dla społeczności AI open-source. + +OmniRoute v3.8.49 · Node ≥22.22.2 · Licencja MIT · omniroute.online +
-