+ 
+
+
+---
+
+## 📸 Dashboard Preview
+
+
+
+
+
+---
+
+### 🤖 Free AI Provider for your favorite coding agents
+
+_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._
Click to see dashboard screenshots
+ +| Page | Screenshot | +| -------------- | ------------------------------------------------- | +| **Providers** |  | +| **Combos** |  | +| **Analytics** |  | +| **Health** |  | +| **Translator** |  | +| **Settings** |  | +| **CLI Tools** |  | +| **Usage Logs** |  | +| **Endpoints** |  | + +| @@ -37,7 +111,7 @@ _قم بتوصيل أي أداة IDE أو CLI مدعومة بالذكاء الا |
 - زيرومخلب + ZeroClaw ⭐ 9.9K |
@@ -60,97 +134,80 @@ _قم بتوصيل أي أداة IDE أو CLI مدعومة بالذكاء الا
 - Codex + Codex CLI ⭐ 60.8K |
 - كلود كود + Claude Code ⭐ 67.3K |
 - الجوزاء CLI + Gemini CLI ⭐ 94.7K |
 - كيلو كود + Kilo Code ⭐ 15.5K |
http://localhost:20128/v1 أو http://cloud.omniroute.online/v1 - تكوين واحد ونماذج غير محدودة و حصة
+📡 All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 — one config, unlimited models and quota
---
-### 🆕 What's New in v3.0.0
+## 🤔 Why OmniRoute?
-| Area | Change |
-| ------------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `
Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal ` تنتهي حصة الاشتراك غير المستخدمة كل شهر
-- حدود معدل تمنعك من الترميز المتوسط
-- واجهات برمجة التطبيقات باهظة الثمن (20-50 دولارًا شهريًا لكل مزود)
-- التبديل اليدوي بين مقدمي الخدمة
-
-** OmniRoute يحل هذا: **
-
-- ✅ **تعظيم الاشتراكات** - تتبع الحصة، استخدم كل جزء منها قبل إعادة التعيين
-- ✅ **الرجوع التلقائي** - الاشتراك → مفتاح واجهة برمجة التطبيقات → رخيص → مجاني، بدون توقف
-- ✅ **حسابات متعددة** - جولة روبن بين الحسابات لكل مزود
-- ✅ **عالمي** - يعمل مع Claude Code وCodex وGemini CLI وCursor وCline وOpenClaw وأي أداة CLI
-
----
-
-## 📧 الدعم> 💬 **انضم إلى مجتمعنا!** [مجموعة WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) - احصل على المساعدة وشارك النصائح وابق على اطلاع.
-
-- **الموقع الإلكتروني**: [omniroute.online](https://omniroute.online)
+- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **المشاكل**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **واتساب**: [مجموعة المجتمع](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **المساهمة**: راجع [CONTRIBUTING.md](CONTRIBUTING.md)، أو افتح علاقة عامة، أو اختر `good first issue`
-- **المشروع الأصلي**: [9router by decolua](https://github.com/decolua/9router)
+- **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`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 كيف يعمل
+## 🔄 How It Works
```
┌─────────────┐
@@ -179,441 +236,453 @@ Result: Never stop coding, minimal cost
---
-## 🎯 ما يحله OmniRoute — 30 مشكلة حقيقية وحالات استخدام
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **يواجه كل مطور يستخدم أدوات الذكاء الاصطناعي هذه المشكلات يوميًا.** تم تصميم OmniRoute لحلها جميعًا — بدءًا من تجاوز التكاليف وحتى الكتل الإقليمية، ومن تدفقات OAuth المعطلة إلى عمليات البروتوكول وإمكانية مراقبة المؤسسة.
+> **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.
-
💸 1. "أدفع مقابل اشتراك باهظ الثمن ولكن لا يزال يتم مقاطعتي بسبب الحدود"
+💸 1. "I pay for an expensive subscription but still get interrupted by limits"
-يدفع المطورون ما بين 20 إلى 200 دولار شهريًا مقابل Claude Pro أو Codex Pro أو GitHub Copilot. حتى عند الدفع، فإن الحصة لها حد أقصى — 5 ساعات من الاستخدام، أو حدود أسبوعية، أو حدود لسعر الدقيقة. في منتصف جلسة الترميز، يتوقف الموفر عن الاستجابة ويفقد المطور التدفق والإنتاجية. +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. -**كيف يحل OmniRoute المشكلة:** +**How OmniRoute solves it:** -- **الاحتياطي الذكي ذو 4 طبقات** — في حالة نفاد حصة الاشتراك، تتم إعادة التوجيه تلقائيًا إلى مفتاح واجهة برمجة التطبيقات ← رخيص ← مجاني بدون أي تدخل يدوي -- **تتبع الحصص في الوقت الفعلي** — يُظهر استهلاك الرمز المميز في الوقت الفعلي مع العد التنازلي لإعادة التعيين (5 ساعات، يوميًا، وأسبوعيًا) -- **دعم الحسابات المتعددة** — حسابات متعددة لكل مزود مع نظام روبن تلقائي — عند نفاد الحساب، يتم التبديل إلى التالي -- **مجموعات مخصصة** — سلاسل احتياطية قابلة للتخصيص مع 6 إستراتيجيات موازنة (الملء أولاً، جولة روبن، P2C، عشوائي، الأقل استخدامًا، الأمثل من حيث التكلفة) -- **حصص الدستور الغذائي** — مراقبة حصص مساحة عمل الشركة/الفريق مباشرة في لوحة المعلومات +- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention +- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly) +- **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 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
-` من نماذج مثل DeepSeek R1 إلى `reasoning_content` القياسية
-- **الإخراج المنظم لـ Gemini** — التحويل التلقائي `json_schema` → `responseMimeType`/`responseSchema`
-- **الإعدادات الافتراضية لـ `stream` هي `false`** — تتماشى مع مواصفات OpenAI، وتتجنب SSE غير المتوقع في Python/Rust/Go SDKs
-
-🔌 2. "أحتاج إلى استخدام موفري خدمات متعددين ولكن لكل منهم واجهة برمجة تطبيقات مختلفة"
+🔌 2. "I need to use multiple providers but each has a different API"
-يستخدم OpenAI تنسيقًا واحدًا، ويستخدم Claude (Anthropic) تنسيقًا آخر، ويستخدم Gemini تنسيقًا آخر. إذا أراد أحد المطورين اختبار النماذج من موفري خدمات مختلفين أو إجراء بديل فيما بينهم، فسيحتاج إلى إعادة تكوين مجموعات تطوير البرامج (SDK)، وتغيير نقاط النهاية، والتعامل مع التنسيقات غير المتوافقة. لدى موفري الخدمة المخصصين (FriendLI، NIM) نقاط نهاية نموذجية غير قياسية. +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. -**كيف يحل OmniRoute المشكلة:** +**How OmniRoute solves it:** -- **نقطة النهاية الموحدة** — تعمل نقطة `http://localhost:20128/v1` واحدة كوكيل لجميع مقدمي الخدمة الذين يزيد عددهم عن 36 -- **تنسيق الترجمة** — تلقائي وشفاف: OpenAI ↔ Claude ↔ Gemini ↔ Responses API -- **تطهير الاستجابة** — إزالة الحقول غير القياسية (`x_groq`، `usage_breakdown`، `service_tier`) التي تكسر OpenAI SDK v1.83+ -- **تطبيع الدور** — تحويل `developer` → `system` لمقدمي الخدمات غير التابعين لـ OpenAI؛ `system` → `user` لـ GLM/ERNIE -- **Think Tag Extraction** — يستخرج كتل `
-` 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
🌐 3. "مزود الذكاء الاصطناعي الخاص بي يحظر منطقتي/بلدي"
- -يقوم مقدمو الخدمة مثل OpenAI/Codex بحظر الوصول من مناطق جغرافية معينة. يحصل المستخدمون على أخطاء مثل `unsupported_country_region_territory` أثناء اتصالات OAuth وAPI. وهذا أمر محبط بشكل خاص للمطورين من البلدان النامية. - -**كيف يحل OmniRoute المشكلة:** - -- **تكوين الوكيل ثلاثي المستوى** — وكيل قابل للتكوين على 3 مستويات: عالمي (كل حركة المرور)، لكل مزود (موفر واحد فقط)، ولكل اتصال/مفتاح -- **شارات الوكيل المرمزة بالألوان** — المؤشرات المرئية: 🟢 الوكيل العالمي، 🟡 وكيل الموفر، 🔵 وكيل الاتصال، يظهر دائمًا عنوان IP -- **تبادل رمز OAuth عبر الوكيل** — يمر تدفق OAuth أيضًا عبر الوكيل، مما يؤدي إلى حل مشكلة `unsupported_country_region_territory` -- **اختبارات الاتصال عبر الوكيل** — تستخدم اختبارات الاتصال الوكيل الذي تم تكوينه (لا مزيد من التجاوز المباشر) -- **دعم SOCKS5** — دعم وكيل SOCKS5 الكامل للتوجيه الخارجي -- ** انتحال بصمة إصبع TLS ** — بصمة TLS تشبه المتصفح عبر `wreq-js` لتجاوز اكتشاف الروبوتات +- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 67+ 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 `
-
+
+🆓 4. "أريد استخدام الذكاء الاصطناعي للبرمجة ولكن ليس لدي المال"
+🌐 3. "My AI provider blocks my region/country"
-لا يستطيع الجميع دفع ما بين 20 إلى 200 دولار شهريًا مقابل اشتراكات الذكاء الاصطناعي. يحتاج الطلاب والمطورون من البلدان الناشئة والهواة والمستقلون إلى الوصول إلى نماذج عالية الجودة بدون تكلفة. +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. -**كيف يحل OmniRoute المشكلة:** +**How OmniRoute solves it:** -- **موفرو الطبقة المجانية المضمنون** — دعم أصلي لمقدمي الخدمات المجانيين بنسبة 100%: iFlow (8 نماذج غير محدودة)، Qwen (3 نماذج غير محدودة)، Kiro (Claude مجانًا)، Gemini CLI (180 ألف/شهر مجانًا) +- **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 + +
+` prefix
-- **المجموعات المجانية فقط** — السلسلة `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = 0 USD/الشهر بدون أي توقف عن العمل
-- **أرصدة NVIDIA NIM المجانية** — 1000 رصيد مجاني مدمج
-- **استراتيجية التكلفة المحسنة** — استراتيجية التوجيه التي تختار تلقائيًا أرخص مزود متاح
+- **Free-Only Combos** — Chain `gc/gemini-3-flash → 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
🆓 4. "I want to use AI for coding but I have no money"
+ +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. + +**How OmniRoute solves it:** + +- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free) - **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/
-
🔒 5. "أحتاج إلى حماية بوابة الذكاء الاصطناعي الخاصة بي من الوصول غير المصرح به"
+🔒 5. "I need to protect my AI gateway from unauthorized access"
-عند تعريض بوابة AI للشبكة (LAN، VPS، Docker)، يمكن لأي شخص لديه العنوان استهلاك الرموز المميزة/الحصة النسبية للمطور. بدون الحماية، تكون واجهات برمجة التطبيقات (API) عرضة لإساءة الاستخدام والحقن الفوري وإساءة الاستخدام. +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. -**كيف يحل OmniRoute المشكلة:** +**How OmniRoute solves it:** -- **إدارة مفاتيح واجهة برمجة التطبيقات** — الإنشاء والتدوير وتحديد النطاق لكل مزود من خلال صفحة `/dashboard/api-manager` المخصصة -- **أذونات على مستوى النموذج** — تقييد مفاتيح واجهة برمجة التطبيقات (API) على نماذج محددة (`openai/*`، أنماط أحرف البدل)، مع تبديل السماح للكل/تقييد -- **API Endpoint Protection** — اطلب مفتاحًا لـ `/v1/models` وقم بحظر موفري خدمة محددين من القائمة -- **Auth Guard + CSRF Protection** — جميع مسارات لوحة المعلومات محمية بالبرمجيات الوسيطة `withAuth` + رموز CSRF -- **محدد المعدل** — تحديد معدل لكل IP مع نوافذ قابلة للتكوين -- **تصفية IP** — القائمة المسموح بها/القائمة المحظورة للتحكم في الوصول -- **حماية الحقن الفوري** — التعقيم ضد أنماط المطالبة الضارة -- **تشفير AES-256-GCM** — بيانات الاعتماد مشفرة في حالة عدم النشاط +- **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. "تعطل مزود الخدمة الخاص بي وفقدت تدفق الترميز الخاص بي"
يمكن أن يصبح موفرو الذكاء الاصطناعي غير مستقرين، أو يعرضون أخطاء 5xx، أو يصلون إلى حدود المعدلات المؤقتة. إذا كان أحد المطورين يعتمد على موفر واحد، فسيتم مقاطعته. بدون قواطع الدائرة، يمكن أن تؤدي عمليات إعادة المحاولة المتكررة إلى تعطل التطبيق. +🛑 6. "My provider went down and I lost my coding flow"
-**كيف يحل OmniRoute المشكلة:** +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. -- **قاطع الدائرة الكهربائية لكل مزود** — فتح/إغلاق تلقائي مع حدود قابلة للتكوين وفترة تهدئة (مغلق/مفتوح/نصف مفتوح) -- **التراجع الأسي** — تأخير إعادة المحاولة التدريجي -- **مكافحة الرعد القطيع** — Mutex + حماية الإشارة ضد عواصف إعادة المحاولة المتزامنة -- **السلاسل الاحتياطية المجمعة** — إذا فشل الموفر الأساسي، فسيتم دخوله تلقائيًا عبر السلسلة دون أي تدخل -- **Combo Circuit Breaker** — التعطيل التلقائي لمقدمي الخدمات الفاشلين ضمن سلسلة التحرير والسرد - | 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format | -- **لوحة معلومات الصحة** — مراقبة وقت التشغيل، وحالات قاطع الدائرة، وعمليات التأمين، وإحصائيات ذاكرة التخزين المؤقت، ووقت الاستجابة p50/p95/p99 +**How OmniRoute solves it:** + +- **Circuit Breaker per-model** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks +- **Exponential Backoff** — Progressive retry delays +- **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 +- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain +- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
-
🔧 7. "تكوين كل أداة من أدوات الذكاء الاصطناعي أمر ممل ومتكرر"
+🔧 7. "Configuring each AI tool is tedious and repetitive"
-يستخدم المطورون Cursor وClaude Code وCodex CLI وOpenClaw وGemini CLI وKilo Code... تحتاج كل أداة إلى تكوين مختلف (نقطة نهاية واجهة برمجة التطبيقات، المفتاح، النموذج). تعد إعادة التكوين عند تبديل مقدمي الخدمات أو النماذج مضيعة للوقت. +Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time. -**كيف يحل OmniRoute المشكلة:** +**How OmniRoute solves it:** -- **لوحة تحكم أدوات CLI** — صفحة مخصصة مع إعداد بنقرة واحدة لـ Claude Code، وCodex CLI، وOpenClaw، وKilo Code، وAntigravity، وCline -- **GitHub Copilot Config Generator** — يُنشئ `chatLanguageModels.json` لرمز VS مع اختيار نموذج مجمع -- **معالج الإعداد** — إعداد إرشادي من 4 خطوات للمستخدمين لأول مرة -- **نقطة نهاية واحدة، جميع الطرز** — قم بتكوين `http://localhost:20128/v1` مرة واحدة، وقم بالوصول إلى أكثر من 36 موفرًا +- **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 67+ providers
-
🔑 8. "إدارة رموز OAuth المميزة من موفري خدمات متعددين أمر جحيم"
+🔑 8. "Managing OAuth tokens from multiple providers is hell"
-Claude Code، وCodex، وGemini CLI، وCopilot — جميعهم يستخدمون OAuth 2.0 مع الرموز المميزة التي تنتهي صلاحيتها. يحتاج المطورون إلى إعادة المصادقة باستمرار، والتعامل مع `client_secret is missing`، و`redirect_uri_mismatch`، والفشل في الخوادم البعيدة. يعد OAuth على LAN/VPS مشكلة بشكل خاص. +Claude Code, Codex, Gemini CLI, 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. -**كيف يحل OmniRoute المشكلة:** +**How OmniRoute solves it:** -- **التحديث التلقائي للرمز المميز** — يتم تحديث رموز OAuth المميزة في الخلفية قبل انتهاء الصلاحية -- **OAuth 2.0 (PKCE) مدمج** — التدفق التلقائي لـ Claude Code وCodex وGemini CLI وCopilot وKiro وQwen وiFlow -- **OAuth متعدد الحسابات** — حسابات متعددة لكل مزود عبر استخراج الرمز المميز JWT/ID -- **OAuth LAN/Remote Fix** — اكتشاف IP الخاص لـ `redirect_uri` + وضع URL اليدوي للخوادم البعيدة -- **OAuth Behind Nginx** — يستخدم `window.location.origin` للتوافق مع الوكيل العكسي -- **دليل OAuth عن بعد** — دليل خطوة بخطوة لبيانات اعتماد Google Cloud على VPS/Docker +- **Auto Token Refresh** — OAuth tokens refresh in background before expiration +- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow +- **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. "لا أعرف كم أنفق أو أين"
+📊 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. -**كيف يحل OmniRoute المشكلة:** +**How OmniRoute solves it:** -- **لوحة معلومات تحليلات التكلفة** — تتبع التكلفة لكل رمز مميز وإدارة الميزانية لكل مزود -- **حدود الميزانية لكل طبقة** — سقف الإنفاق لكل طبقة يؤدي إلى حدوث تراجع تلقائي -- **تكوين التسعير لكل نموذج** — أسعار قابلة للتكوين لكل نموذج- **إحصاءات الاستخدام لكل مفتاح API** — عدد الطلبات والطابع الزمني الأخير المستخدم لكل مفتاح -- **لوحة التحكم التحليلية** — بطاقات الإحصائيات، ومخطط استخدام النموذج، وجدول الموفر مع معدلات النجاح وزمن الاستجابة +- **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. "لا يمكنني تشخيص الأخطاء والمشكلات في مكالمات الذكاء الاصطناعي"
+🐛 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. -**كيف يحل OmniRoute المشكلة:** +**How OmniRoute solves it:** -- **لوحة تحكم السجلات الموحدة** — 4 علامات تبويب: سجلات الطلبات، وسجلات الوكيل، وسجلات التدقيق، ووحدة التحكم -- **عارض سجل وحدة التحكم** — عارض بنمط المحطة الطرفية في الوقت الفعلي مع مستويات مرمزة بالألوان، والتمرير التلقائي، والبحث، والتصفية -- **سجلات وكيل SQLite** — السجلات المستمرة التي تستمر حتى بعد إعادة تشغيل الخادم -- **ساحة المترجم** — 4 أوضاع لتصحيح الأخطاء: ساحة اللعب (ترجمة التنسيق)، اختبار الدردشة (ذهابًا وإيابًا)، منصة الاختبار (دفعة)، المراقبة المباشرة (في الوقت الفعلي) -- **قياس الطلب عن بعد** — زمن الاستجابة p50/p95/p99 + تتبع معرف طلب X -- **التسجيل المستند إلى الملف مع التدوير** — يلتقط جهاز اعتراض وحدة التحكم كل شيء إلى سجل JSON من خلال التدوير المستند إلى الحجم +- **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 Proxy Logs** — Persistent logs that survive server restarts +- **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 Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation +- **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. "إن نشر البوابة وصيانتها أمر معقد"
+🏗️ 11. "Deploying and maintaining the gateway is complex"
-يعد تثبيت وكيل AI وتكوينه وصيانته عبر بيئات مختلفة (محلية، VPS، Docker، سحابية) عملية كثيفة العمالة. مشاكل مثل المسارات المضمنة، `EACCES` في الدلائل، وتعارضات المنافذ، والبنيات عبر الأنظمة الأساسية تزيد من الاحتكاك. +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. -**كيف يحل OmniRoute المشكلة:** +**How OmniRoute solves it:** -- **تثبيت npm الشامل** — `npm install -g omniroute && omniroute` — تم -- **منصة Docker المتعددة** — AMD64 + ARM64 الأصلي (Apple Silicon، AWS Graviton، Raspberry Pi) -- **ملفات تعريف Docker Compose** — `base` (لا توجد أدوات CLI) و`cli` (مع Claude Code وCodex وOpenClaw) -- **Electron Desktop App** — تطبيق أصلي لنظام التشغيل Windows/macOS/Linux مع علبة النظام، والتشغيل التلقائي، ووضع عدم الاتصال -- **وضع المنفذ المقسم** — واجهة برمجة التطبيقات ولوحة المعلومات على منافذ منفصلة للسيناريوهات المتقدمة (الوكيل العكسي، وشبكات الحاويات) -- **Cloud Sync** — مزامنة التكوين عبر الأجهزة عبر Cloudflare Workers -- **النسخ الاحتياطية لقاعدة البيانات** — النسخ الاحتياطي التلقائي لجميع الإعدادات واستعادتها وتصديرها واستيرادها +- **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
-
-
-🌍 12. "الواجهة باللغة الإنجليزية فقط وفريقي لا يتحدث الإنجليزية"
+🌍 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. -**كيف يحل OmniRoute المشكلة:** +**How OmniRoute solves it:** -- **لوحة المعلومات i18n — 30 لغة** — أكثر من 500 مفتاح مترجم بما في ذلك العربية والبلغارية والدنماركية والألمانية والإسبانية والفنلندية والفرنسية والعبرية والهندية والمجرية والإندونيسية والإيطالية واليابانية والكورية والماليزية والهولندية والنرويجية والبولندية والبرتغالية (PT/BR) والرومانية والروسية والسلوفاكية والسويدية والتايلاندية والأوكرانية والفيتنامية والصينية والفلبينية والإنجليزية -- **دعم RTL** — دعم من اليمين إلى اليسار للغتين العربية والعبرية -- **الملفات التمهيدية متعددة اللغات** — 30 ترجمة كاملة للوثائق -- **محدد اللغة** — رمز الكرة الأرضية في رأس الصفحة للتبديل في الوقت الفعلي
-
🔄 13. "أحتاج إلى أكثر من مجرد الدردشة - أحتاج إلى التضمين والصور والصوت"
- -الذكاء الاصطناعي ليس مجرد استكمال للدردشة. يحتاج المطورون إلى إنشاء صور، ونسخ الصوت، وإنشاء تضمينات لـ RAG، وإعادة ترتيب المستندات، والإشراف على المحتوى. تحتوي كل واجهة برمجة تطبيقات على نقطة نهاية وتنسيق مختلفين. - -**كيف يحل OmniRoute المشكلة:** - -- **التضمينات** — `/v1/embeddings` مع 6 موفري خدمة وأكثر من 9 نماذج -- **إنشاء الصور** — `/v1/images/generations` مع 10 موفرين وأكثر من 20 نموذجًا (OpenAI، وxAI، وTogether، وFireworks، وNebius، وHyperbolic، وNanoBanana، وAntigravity، وSD WebUI، وComfyUI) -- **تحويل النص إلى فيديو** — `/v1/videos/generations` — ComfyUI (AnimateDiff، SVD) وSD WebUI -- **تحويل النص إلى موسيقى** — `/v1/music/generations` — ComfyUI (فتح الصوت الثابت، MusicGen) -- **النسخ الصوتي** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM، HuggingFace، Qwen3 -- **تحويل النص إلى كلام** — `/v1/audio/speech` — ElevenLabs، وNvidia NIM، وHuggingFace، وCoqui، وTortoise، وQwen3، بالإضافة إلى مقدمي الخدمات الحاليين -- **الإشراف** — `/v1/moderations` — التحقق من سلامة المحتوى -- **إعادة الترتيب** — `/v1/rerank` — إعادة ترتيب مدى ملاءمة المستند -- **Responses API** — دعم `/v1/responses` الكامل لـ Codex +- **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
-
🧪 14. "ليس لدي طريقة لاختبار ومقارنة الجودة عبر النماذج"
+🔄 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. -**كيف يحل OmniRoute المشكلة:** +**How OmniRoute solves it:** -- ** تقييمات LLM ** — اختبار المجموعة الذهبية مع 10 حالات محملة مسبقًا تغطي التحيات، والرياضيات، والجغرافيا، وإنشاء التعليمات البرمجية، والامتثال لـ JSON، والترجمة، وتخفيض السعر، والرفض الآمن -- **4 إستراتيجيات مطابقة** — `exact`، `contains`، `regex`، `custom` (وظيفة JS) -- **منصة اختبار ساحة المترجم** — اختبار الدفعات بمدخلات متعددة ومخرجات متوقعة، ومقارنة بين الموفرين -- **أداة اختبار الدردشة** — رحلة ذهابًا وإيابًا كاملة مع عرض الاستجابة المرئية -- **المراقبة المباشرة** — البث المباشر لجميع الطلبات المتدفقة عبر الوكيل +- **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
-
📈 15. "أحتاج إلى التوسع دون فقدان الأداء"
+🧪 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. -**كيف يحل OmniRoute المشكلة:** +**How OmniRoute solves it:** -- **ذاكرة التخزين المؤقت الدلالية** — تعمل ذاكرة التخزين المؤقت ذات المستويين (التوقيع + الدلالي) على تقليل التكلفة ووقت الاستجابة -- **صلاحية الطلب** — نافذة إلغاء البيانات المكررة لمدة 5 ثوانٍ للطلبات المتماثلة -- **الكشف عن حدود المعدل** — عدد الدورات في الدقيقة لكل مزود، والفجوة الدنيا، والحد الأقصى للتتبع المتزامن -- **حدود المعدل القابلة للتحرير** — الإعدادات الافتراضية القابلة للتكوين في الإعدادات → المرونة مع الثبات -- **ذاكرة التخزين المؤقت للتحقق من صحة مفتاح واجهة برمجة التطبيقات** — ذاكرة تخزين مؤقت ثلاثية الطبقات لأداء الإنتاج -- **لوحة معلومات الصحة مع القياس عن بعد** — زمن الاستجابة p50/p95/p99، وإحصائيات ذاكرة التخزين المؤقت، ووقت التشغيل +- **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
-
🤖 16. "أريد التحكم في سلوك النموذج عالميًا"
المطورون الذين يريدون جميع الاستجابات بلغة معينة، بنبرة معينة، أو يريدون الحد من الرموز المميزة للاستدلال. يعد تكوين هذا في كل أداة/طلب أمرًا غير عملي. +📈 15. "I need to scale without losing performance"
-**كيف يحل OmniRoute المشكلة:** +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. -- **الحقن الفوري للنظام** — يتم تطبيق المطالبة العامة على جميع الطلبات -- **التحقق من صحة ميزانية التفكير** — التحكم في تخصيص الرمز المميز لكل طلب (العبور، التلقائي، المخصص، التكيفي) -- **6 إستراتيجيات التوجيه** — إستراتيجيات عالمية تحدد كيفية توزيع الطلبات -- **Wildcard Router** — يتم توجيه أنماط `provider/*` ديناميكيًا إلى أي مزود -- **تبديل تمكين/تعطيل التحرير والسرد** — تبديل المجموعات مباشرة من لوحة المعلومات -- **تبديل الموفر** — تمكين/تعطيل جميع اتصالات الموفر بنقرة واحدة -- **المقدمون المحظورون** — استبعاد موفري الخدمة المحددين من قائمة `/v1/models` +**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 +- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence +- **API Key Validation Cache** — 3-tier cache for production performance +- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
-
🧰 17. "أحتاج إلى أدوات MCP كقدرات منتج من الدرجة الأولى"
+🤖 16. "I want to control model behavior globally"
-تعرض العديد من بوابات الذكاء الاصطناعي MCP فقط كتفاصيل تنفيذ مخفية. تحتاج الفرق إلى طبقة تشغيل مرئية ويمكن التحكم فيها. +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. -**كيف يحل OmniRoute المشكلة:** +**How OmniRoute solves it:** -- يظهر MCP في لوحة التحكم وعلامة تبويب بروتوكول نقطة النهاية -- صفحة إدارة MCP مخصصة تحتوي على العمليات والأدوات والنطاقات والتدقيق -- بداية سريعة مدمجة لـ `omniroute --mcp` وتأهيل العميل +- **System Prompt Injection** — Global prompt applied to all requests +- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive) +- **6 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 +- **Provider Toggle** — Enable/disable all connections for a provider with one click +- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
-
🧠 18. "أحتاج إلى تنسيق A2A مع مسارات مهمة المزامنة + الدفق"
+🧰 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. -**كيف يحل OmniRoute المشكلة:** +**How OmniRoute solves it:** -- نقطة نهاية A2A JSON-RPC (`POST /a2a`) مع `message/send` و`message/stream` -- تدفق SSE مع انتشار الحالة الطرفية -- واجهات برمجة تطبيقات دورة حياة المهام لـ `tasks/get` و`tasks/cancel` +- 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
-
🛰️ 19. "أحتاج إلى صحة عملية MCP حقيقية، وليس حالة تخمينية"
+🧠 18. "I need A2A orchestration with sync + stream task paths"
-تحتاج الفرق التشغيلية إلى معرفة ما إذا كان MCP حيًا بالفعل، وليس فقط ما إذا كان يمكن الوصول إلى واجهة برمجة التطبيقات (API). +Agent workflows need both direct replies and long-running streamed execution with lifecycle control. -**كيف يحل OmniRoute المشكلة:** +**How OmniRoute solves it:** -- ملف نبضات وقت التشغيل مع PID والطوابع الزمنية والنقل وعدد الأدوات ووضع النطاق -- واجهة برمجة تطبيقات حالة MCP التي تجمع بين نبضات القلب + النشاط الأخير -- بطاقات حالة واجهة المستخدم للعملية/وقت التشغيل/نضارة نبضات القلب +- 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`
-
📋 20. "أحتاج إلى تنفيذ أداة MCP قابلة للتدقيق"
+🛰️ 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. -**كيف يحل OmniRoute المشكلة:** +**How OmniRoute solves it:** -- تسجيل التدقيق المدعوم من SQLite لاستدعاءات أداة MCP -- عوامل التصفية حسب الأداة، والنجاح/الفشل، ومفتاح API، وترقيم الصفحات -- جدول تدقيق لوحة المعلومات + إحصائيات نقاط النهاية للأتمتة +- 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
-
-
-🔐 21. "أحتاج إلى أذونات MCP محددة النطاق لكل عملية تكامل"
+📋 20. "I need auditable MCP tool execution"
-يجب أن يتمتع العملاء المختلفون بإمكانية وصول أقل امتيازًا إلى فئات الأدوات. +When tools mutate config or trigger ops actions, teams need forensic traceability. -**كيف يحل OmniRoute المشكلة:** +**How OmniRoute solves it:** -- 9 نطاقات MCP محببة للتحكم في الوصول إلى الأدوات -- إنفاذ النطاق والرؤية في واجهة مستخدم إدارة MCP -- الوضع الافتراضي الآمن للأدوات التشغيلية - -⚙️ 22. "أحتاج إلى عناصر تحكم تشغيلية دون إعادة النشر"
- -تحتاج الفرق إلى تغييرات سريعة في وقت التشغيل أثناء الحوادث أو أحداث التكلفة. - -**كيف يحل OmniRoute المشكلة:** - -- قم بتبديل تنشيط التحرير والسرد مباشرةً من لوحة معلومات MCP -- تطبيق ملفات تعريف المرونة من حزم السياسات المحددة مسبقًا -- إعادة ضبط حالة قاطع الدائرة من نفس لوحة العمليات +- SQLite-backed audit logging for MCP tool calls +- Filters by tool, success/failure, API key, and pagination +- Dashboard audit table + stats endpoints for automation
-
🔄 23. "أحتاج إلى رؤية وإلغاء دورة حياة مهمة A2A المباشرة"
+🔐 21. "I need scoped MCP permissions per integration"
-وبدون رؤية دورة الحياة، يصبح من الصعب فرز حوادث المهام. +Different clients should have least-privilege access to tool categories. -**كيف يحل OmniRoute المشكلة:** +**How OmniRoute solves it:** -- قائمة المهام/التصفية حسب الحالة/المهارة مع ترقيم الصفحات -- التعمق في البيانات الوصفية للمهمة، والأحداث، والتحف -- نقطة نهاية إلغاء المهمة وإجراء واجهة المستخدم مع التأكيد +- 9 granular MCP scopes for controlled tool access +- Scope enforcement and visibility in MCP management UI +- Safe default posture for operational tooling
-
🌊 24. "أحتاج إلى مقاييس تيار نشطة لتحميل A2A"
+⚙️ 22. "I need operational controls without redeploying"
-يتطلب تدفق سير العمل رؤية تشغيلية للتزامن والاتصالات المباشرة. +Teams need quick runtime changes during incidents or cost events. -**كيف يحل OmniRoute المشكلة:** +**How OmniRoute solves it:** -- عدادات التدفق النشطة مدمجة في حالة A2A -- الطابع الزمني للمهمة الأخيرة وعدد كل ولاية -- بطاقات لوحة القيادة A2A لمراقبة العمليات في الوقت الفعلي +- Switch combo activation directly from MCP dashboard +- Apply resilience profiles from pre-defined policy packs +- Reset circuit breaker state from the same operations panel
-
🪪 25. "أحتاج إلى اكتشاف الوكيل القياسي للعملاء"
+🔄 23. "I need live A2A task lifecycle visibility and cancellation"
-يحتاج العملاء والمنسقون الخارجيون إلى بيانات تعريف يمكن قراءتها آليًا من أجل الإعداد. +Without lifecycle visibility, task incidents become hard to triage. -**كيف يحل OmniRoute المشكلة:** +**How OmniRoute solves it:** -- بطاقة الوكيل معروضة في `/.well-known/agent.json` -- القدرات والمهارات الموضحة في واجهة المستخدم الإدارية -- تتضمن واجهة برمجة التطبيقات لحالة A2A بيانات تعريف الاكتشاف للأتمتة +- Task listing/filtering by state/skill with pagination +- Drill-down on task metadata, events, and artifacts +- Task cancellation endpoint and UI action with confirmation
-
🧭 26. "أحتاج إلى إمكانية اكتشاف البروتوكول في تجربة المستخدم للمنتج"
+🌊 24. "I need active stream metrics for A2A load"
-إذا لم يتمكن المستخدمون من اكتشاف أسطح البروتوكول، فسوف ينخفض جودة الاعتماد والدعم. +Streaming workflows require operational insight into concurrency and live connections. -**كيف يحل OmniRoute المشكلة:** +**How OmniRoute solves it:** -- إدخالات الشريط الجانبي لـ MCP وA2A -- علامة تبويب بروتوكولات صفحة نقطة النهاية مع البدء السريع والحالة -- روابط من النظرة العامة إلى لوحات معلومات الإدارة المخصصة +- Active stream counters integrated into A2A status +- Last task timestamp and per-state counts +- A2A dashboard cards for real-time ops monitoring
-
🧪 27. "أحتاج إلى التحقق من صحة البروتوكول الشامل مع عملاء حقيقيين"
+🪪 25. "I need standard agent discovery for clients"
-الاختبارات الوهمية ليست كافية للتحقق من توافق البروتوكول قبل الإصدار. +External clients and orchestrators need machine-readable metadata for onboarding. -**كيف يحل OmniRoute المشكلة:** +**How OmniRoute solves it:** -- مجموعة E2E التي تعمل على تشغيل التطبيق وتستخدم نقل عميل MCP SDK الحقيقي -- اختبارات عميل A2A لاكتشاف التدفقات وإرسالها ودفقها والحصول عليها وإلغائها -- التحقق من التأكيدات ضد تدقيق MCP وواجهات برمجة تطبيقات مهام A2A +- Agent Card exposed at `/.well-known/agent.json` +- Capabilities and skills shown in management UI +- A2A status API includes discovery metadata for automation
-
📡 28. "أحتاج إلى إمكانية ملاحظة موحدة عبر جميع الواجهات"
+🧭 26. "I need protocol discoverability in the product UX"
-يؤدي تقسيم إمكانية المراقبة حسب البروتوكول إلى إنشاء نقاط عمياء وMTTR أطول. +If users cannot discover protocol surfaces, adoption and support quality drop. -**كيف يحل OmniRoute المشكلة:** +**How OmniRoute solves it:** -- لوحات معلومات/سجلات/تحليلات موحدة في منتج واحد -- الصحة + التدقيق + طلب القياس عن بعد عبر طبقات OpenAI وMCP وA2A -- واجهات برمجة التطبيقات التشغيلية للحالة والأتمتة +- 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
-
💼 29. "أحتاج إلى وقت تشغيل واحد للوكيل + الأدوات + تنسيق الوكيل"
+🧪 27. "I need end-to-end protocol validation with real clients"
-يؤدي تشغيل العديد من الخدمات المنفصلة إلى زيادة تكلفة التشغيل وأوضاع الفشل. +Mock tests are not enough to validate protocol compatibility before release. -**كيف يحل OmniRoute المشكلة:**- وكيل متوافق مع OpenAI وخادم MCP وخادم A2A في مكدس واحد +**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
-
-### أمثلة لقواعد اللعبة (حالات الاستخدام المتكاملة)
+🚀 30. "أحتاج إلى شحن عمليات سير عمل الوكيل دون امتداد كود الغراء"
+📡 28. "I need unified observability across all interfaces"
-تفقد الفرق سرعتها عند دمج العديد من الخدمات والبرامج النصية المخصصة. +Splitting observability by protocol creates blind spots and longer MTTR. -**كيف يحل OmniRoute المشكلة:** +**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 + +
+
+
+### Example Playbooks (Integrated Use Cases)
+
+**Playbook A: Maximize paid subscription + cheap backup**
```txt
Combo: "maximize-claude"
@@ -625,7 +694,7 @@ Monthly cost: $20 + small backup spend
Outcome: higher quality, near-zero interruption
```
-**دليل التشغيل ب: مكدس البرمجة بدون تكلفة**
+**Playbook B: Zero-cost coding stack**
```txt
Combo: "free-forever"
@@ -637,7 +706,7 @@ Monthly cost: $0
Outcome: stable free coding workflow
```
-**Playbook C: سلسلة احتياطية تعمل دائمًا على مدار 24 ساعة طوال أيام الأسبوع**
+**Playbook C: 24/7 always-on fallback chain**
```txt
Combo: "always-on"
@@ -650,37 +719,61 @@ Combo: "always-on"
Outcome: deep fallback depth for deadline-critical workloads
```
-**قواعد اللعبة د: عمليات العميل مع MCP + A2A**
+**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/mcp and /dashboard/a2a
-4) Control incidents with resilience profile + task cancellation
+3) Observe via /dashboard/endpoint (MCP and A2A tabs)
+4) Toggle services via inline status controls
```
---
-## ⚡ بداية سريعة
+## 🆓 Start Free — Zero Configuration Cost
-### 1) التثبيت والتشغيل
+> 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 **iFlow** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |
+| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |
+| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |
+| 5 | `/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).
+
+## بداية سريعة
+
+### 1) Install and run
```bash
npm install -g omniroute
omniroute
```
-يتم فتح لوحة المعلومات على `http://localhost:20128` ويكون عنوان URL الأساسي لواجهة برمجة التطبيقات هو `http://localhost:20128/v1`.
+> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:
+>
+> ```bash
+> pnpm install -g omniroute
+> pnpm approve-builds -g # Select all packages → approve
+> omniroute
+> ```
-| الأمر | الوصف |
-| ----------------------- | ------------------------------------------------------------------------------------- |
-| `omniroute` | بدء تشغيل الخادم (`PORT=20128` وواجهة برمجة التطبيقات ولوحة المعلومات على نفس المنفذ) |
-| `omniroute --port 3000` | اضبط منفذ Canonical/API على 3000 |
-| `omniroute --mcp` | بدء تشغيل خادم MCP (نقل stdio) |
-| `omniroute --no-open` | لا تفتح المتصفح تلقائيًا |
-| `omniroute --help` | عرض المساعدة |
+Dashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.
-وضع المنفذ المقسم الاختياري:
+| 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
@@ -688,13 +781,13 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
# Dashboard: http://localhost:20129
```
-### 2) قم بتوصيل مقدمي الخدمة وإنشاء مفتاح واجهة برمجة التطبيقات (API) الخاص بك
+### 2) Connect providers and create your API key
-1. افتح لوحة المعلومات → `Providers` وقم بتوصيل موفر واحد على الأقل (مفتاح OAuth أو API).
-2. افتح لوحة المعلومات → `Endpoint` وقم بإنشاء مفتاح API.
-3. (اختياري) افتح Dashboard → `Combos` وقم بتعيين السلسلة الاحتياطية.
+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) قم بتوجيه أداة الترميز الخاصة بك إلى OmniRoute
+### 3) Point your coding tool to OmniRoute
```txt
Base URL: http://localhost:20128/v1
@@ -702,21 +795,22 @@ API Key: [copy from Endpoint page]
Model: if/kimi-k2-thinking (or any provider/model prefix)
```
-يعمل مع Claude Code، وCodex CLI، وGemini CLI، وCursor، وCline، وOpenClaw، وOpenCode، وحزم SDK المتوافقة مع OpenAI.
+Works with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.
-### 4) تمكين البروتوكولات والتحقق من صحتها (الإصدار 2.0)
+### 4) Enable and validate protocols (v2.0)
-**MCP (للعمليات التي تعتمد على الأدوات):**
+**MCP (for tool-driven operations):**
```bash
omniroute --mcp
```
-ثم قم بتوصيل عميل MCP الخاص بك عبر `stdio` وأدوات الاختبار مثل:
+Then connect your MCP client over `stdio` and test tools like:
--`omniroute_get_health` -`omniroute_list_combos`
+- `omniroute_get_health`
+- `omniroute_list_combos`
-**A2A (لسير العمل من وكيل إلى وكيل):**
+**A2A (for agent-to-agent workflows):**
```bash
curl http://localhost:20128/.well-known/agent.json
@@ -728,15 +822,15 @@ curl -X POST http://localhost:20128/a2a \
-d '{"jsonrpc":"2.0","id":"quickstart","method":"message/send","params":{"skill":"quota-management","messages":[{"role":"user","content":"Give me a short quota summary."}]}}'
```
-### 5) التحقق من صحة كل شيء من البداية إلى النهاية (مستحسن)
+### 5) Validate everything end-to-end (recommended)
```bash
npm run test:protocols:e2e
```
-يتحقق هذا الجناح من تدفقات عميل MCP وA2A الحقيقية مقابل تطبيق قيد التشغيل.
+This suite validates real MCP and A2A client flows against a running app.
-### البديل: التشغيل من المصدر
+### Alternative: run from source
```bash
cp .env.example .env
@@ -746,11 +840,11 @@ PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm
---
-## 🐳 عامل الميناء
+## 🐳 Docker
-OmniRoute متاح كصورة Docker عامة على [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
+OmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
-**الجري السريع:**
+**Quick run:**
```bash
docker run -d \
@@ -761,7 +855,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-** مع ملف البيئة: **
+**With environment file:**
```bash
# Copy and edit .env first
@@ -776,7 +870,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**استخدام Docker Compose:**
+**Using Docker Compose:**
```bash
# Base profile (no CLI tools)
@@ -786,22 +880,61 @@ docker compose --profile base up -d
docker compose --profile cli up -d
```
-| صورة | العلامة | الحجم | الوصف |
-| ------------------------ | -------- | ------------- | ---------------- |
-| `diegosouzapw/omniroute` | `latest` | ~250 ميجابايت | أحدث إصدار مستقر |
-| `diegosouzapw/omniroute` | `1.0.3` | ~250 ميجابايت | النسخة الحالية |
+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.
+- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.
+- 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` | `1.0.3` | ~250MB | Current version |
---
-## 🖥️
+## 🖥️ Desktop App — Offline & Always-On
-قم بتشغيل OmniRoute كتطبيق مستقل لسطح المكتب - لا توجد محطة طرفية أو متصفح أو إنترنت مطلوب للطرز المحلية. يتضمن التطبيق المعتمد على Electron ما يلي:
+> 🆕 **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.
-- 🖥️ **النافذة الأصلية** — نافذة تطبيق مخصصة مع تكامل علبة النظام
-- 🔄 **البدء التلقائي** — قم بتشغيل OmniRoute عند تسجيل الدخول إلى النظام
-- 🔔 **الإشعارات الأصلية** — احصل على تنبيهات بشأن استنفاد الحصص أو مشكلات المزود
-- ⚡ **التثبيت بنقرة واحدة** — NSIS (Windows)، DMG (macOS)، AppImage (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
### بداية سريعة
@@ -816,135 +949,348 @@ npm run electron:build:mac # macOS (.dmg) — x64 & arm64
npm run electron:build:linux # Linux (.AppImage)
```
-### علبة النظام
+### System Tray
-عند تصغيره، يظل OmniRoute موجودًا في علبة النظام لديك من خلال الإجراءات السريعة:
+When minimized, OmniRoute lives in your system tray with quick actions:
-- فتح لوحة القيادة
-- تغيير منفذ الخادم
-- قم بإنهاء التطبيق
+- Open dashboard
+- Change server port
+- Quit application
-📖 التوثيق الكامل : [`electron/README.md`](electron/README.md)
+📖 Full documentation: [`electron/README.md`](electron/README.md)
---
-## 💰 لمحة سريعة عن الأسعار
+## 💰 Pricing at a Glance
-| الطبقة | مقدم | التكلفة | إعادة ضبط الحصص | الأفضل لـ |
-| ---------------------------------- | ---------------------------- | ---------------------- | ----------------------- | ------------------------- |
-| **💳الإشتراك** | كلود كود (برو) | 20 دولارًا شهريًا | 5 ساعات + أسبوعي | اشتركت بالفعل |
-| | الدستور الغذائي (زائد / برو) | 20-200 دولار شهريًا | 5 ساعات + أسبوعي | مستخدمي OpenAI |
-| | الجوزاء CLI | **مجاني** | 180 ألف/شهر + 1 ألف/يوم | الجميع! |
-| | جيثب مساعد الطيار | 10-19 دولارًا شهريًا | شهري | مستخدمي جيثب |
-| **🔑 مفتاح واجهة برمجة التطبيقات** | نفيديا نيم | **مجانًا** (1000 نقطة) | لمرة واحدة | اختبار المستوى المجاني |
-| | ديب سيك | الدفع لكل استخدام | لا شيء | أفضل سعر/جودة |
-| | جروك | طبقة مجانية + مدفوعة | معدل محدود | الاستدلال فائق السرعة |
-| | xAI (جروك) | الدفع لكل استخدام | لا شيء | نماذج جروك |
-| | ميسترال | طبقة مجانية + مدفوعة | معدل محدود | الذكاء الاصطناعي الأوروبي |
-| | اوبن راوتر | الدفع لكل استخدام | لا شيء | أكثر من 100 موديل |
-| **💰 رخيص** | جي إل إم-4.7 | 0.6 دولار/1 مليون | يوميا 10 صباحا | نسخة احتياطية للميزانية |
-| | ميني ماكس M2.1 | 0.2 دولار/1 مليون | المتداول لمدة 5 ساعات | الخيار الأرخص |
-| | كيمي ك2 | 9 دولارات شهريًا مسطحة | 10 مليون رمز/شهر | التكلفة المتوقعة |
-| **🆓مجانًا** | اي فلو | $0 | غير محدود | 8 نماذج مجانية |
-| | كوين | $0 | غير محدود | 3 نماذج مجانية |
-| | كيرو | $0 | غير محدود | كلود مجاني |
+| 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 |
+| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |
+| | 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** | iFlow | **$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 |
-**💡 نصيحة احترافية:** ابدأ مع Gemini CLI (180 ألفًا مجانًا شهريًا) + مجموعة iFlow (مجانية غير محدودة) = تكلفة 0 دولار!
+> 🆕 **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
+iFlow (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.
---
-## 💡 الميزات الرئيسية
+---
-تم تصميم OmniRoute v2.0 كمنصة تشغيلية، وليس مجرد وكيل ترحيل.
+## 🆓 Free Models — What You Actually Get
-### 🤖 عمليات الوكيل والبروتوكول (الإصدار 2.0)| ميزة | ماذا يفعل |
+> 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.
-| ------------------------------------ | -------------------------------------------------------------------------------- |
-| 🔧 **خادم MCP (16 أداة)** | تتحكم أدوات IDE/agent في التوجيه والصحة والمجموعات والحدود والعمليات | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`)
-| 🤝 **خادم A2A (JSON-RPC + SSE)** | تنفيذ المهام من وكيل إلى وكيل مع تدفقات المزامنة والتدفق |
-| 🧭 **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** | حالة العملية الحقيقية (معرف المنتج، وقت التشغيل، عمر نبضات القلب، النقل، وضع النطاق) |
-| 📋 **مسار تدقيق MCP** | سجلات التدقيق القابلة للتصفية مع النجاح/الفشل والإسناد الرئيسي |
-| 🔐 **تنفيذ نطاق MCP** | 9 أذونات نطاق تفصيلية للوصول إلى الأدوات الخاضعة للرقابة |
-| 📡 **إدارة دورة حياة المهام A2A** | قائمة/تصفية المهام، فحص الأحداث/التحف، إلغاء المهام قيد التشغيل |
-| 📋 **اكتشاف بطاقة الوكيل** | `/.well-known/agent.json` للاكتشاف التلقائي للعميل |
-| 🧪 **أداة اختبار البروتوكول E2E** | يتدفق عميل MCP SDK + A2A الحقيقي في `test:protocols:e2e` |
-| ⚙️ **ضوابط التشغيل** | مجموعة التبديل، وتطبيق ملفات تعريف المرونة، وإعادة ضبط القواطع من سطح تحكم واحد |
+### 🔵 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 |
-| ميزة | ماذا يفعل |
-| ----------------------------------------- | ------------------------------------------------------------ |
-| 🎯 **احتياطي ذكي من 4 طبقات** | المسار التلقائي: الاشتراك → مفتاح API → رخيص → مجاني |
-| 📊 **تتبع الحصص في الوقت الفعلي** | عدد الرموز الحية + إعادة تعيين العد التنازلي لكل مزود |
-| 🔄 **تنسيق الترجمة** | OpenAI ↔ Claude ↔ Gemini ↔ الردود مع التحويلات الآمنة للمخطط |
-| 👥 **دعم الحسابات المتعددة** | حسابات متعددة لكل مزود مع اختيار ذكي |
-| 🔄 **تحديث تلقائي للرمز** | يتم تحديث رموز OAuth المميزة تلقائيًا من خلال إعادة المحاولة |
-| 🎨 **مجموعات مخصصة** | 6 استراتيجيات موازنة + التحكم في السلسلة الاحتياطية |
-| 🌐 **جهاز توجيه Wildcard** | التوجيه الديناميكي `provider/*` |
-| 🧠 **التفكير في ضوابط الميزانية** | حدود التفكير المنطقي والتلقائي والمخصص والتكيفي |
-| 🔀 **الأسماء المستعارة للنماذج** | مدمج + اسم مستعار للنموذج المخصص وأمان الترحيل |
-| ⚡ **تدهور الخلفية** | قم بتوجيه مهام الخلفية ذات الأولوية المنخفضة إلى نماذج أرخص |
-| 💬 **الحقن الفوري للنظام** | يتم تطبيق ضوابط السلوك العالمية بشكل متسق |
-| 📄 **توافق واجهة برمجة التطبيقات للردود** | دعم `/v1/responses` الكامل لـ Codex وسير عمل الوكلاء المتقدم |
+### 🟢 IFLOW MODELS (Free OAuth — No Credit Card)
-### 🎵 واجهات برمجة التطبيقات متعددة الوسائط
+| 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 |
-| ميزة | ماذا يفعل || -------------------------- | ------------------------------------------------------------- |
-| 🖼️ **إنشاء الصور** | `/v1/images/generations` مع الواجهات الخلفية السحابية والمحلية |
-| 📐 **المضامين** | `/v1/embeddings` للبحث وخطوط أنابيب RAG |
-| 🎤 **نسخ صوتي** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |
-| 🔊 **تحويل النص إلى كلام** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) |
-| 🎬 **توليد الفيديو** | `/v1/videos/generations` (سير عمل ComfyUI + SD WebUI) |
-| 🎵 **جيل الموسيقى** | `/v1/music/generations` (سير عمل ComfyUI) |
-| 🛡️ **اعتدالات** | فحوصات السلامة `/v1/moderations` |
-| 🔀 **إعادة الترتيب** | `/v1/rerank` لقياس مدى الملاءمة |
+### 🟡 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) |
-| ميزة | ماذا يفعل |
-| -------------------------------------------------------- | --------------------------------------------------------------------- |
-| 🔌 **قواطع الدائرة** | رحلة/استرداد على مستوى الموفر مع عناصر التحكم في العتبة |
-| 🛡️ **القطيع المضاد للرعد** | حماية Mutex + الإشارة في أحداث إعادة المحاولة/التقييم |
-| 🧠 ** ذاكرة التخزين المؤقت الدلالية + التوقيع ** | تقليل التكلفة/زمن الوصول باستخدام طبقتين من ذاكرة التخزين المؤقت |
-| ⚡ **طلب العجز** | نافذة الحماية المكررة |
-| 🔒 **انتحال بصمة الإصبع TLS** | توافق أفضل مع مقدمي خدمات مكافحة الروبوتات الذين تمت تصفيتهم |
-| 🌐 **تصفية IP** | التحكم في القائمة المسموح بها/القائمة المحظورة لعمليات النشر المكشوفة |
-| 📊 **حدود المعدل القابلة للتحرير** | حدود عالمية/مستوى مزود قابلة للتكوين مع الثبات |
-| 🔑 **إدارة مفاتيح واجهة برمجة التطبيقات + تحديد النطاق** | تأمين إصدار/تدوير المفتاح وضوابط النموذج/المزود |
-| 🛡️ **محمية `/models`** | بوابة مصادقة اختيارية وإخفاء الموفر لكتالوج النماذج |
+### 🟣 GEMINI CLI (Google OAuth)
-### 📊 إمكانية الملاحظة والتحليلات
+| Model | Prefix | Limit | Rate Limit |
+| ------------------------ | ------ | --------------------------- | ------------- |
+| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |
+| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |
-| ميزة | ماذا يفعل |
-| -------------------------------- | ------------------------------------------------------------------------- |
-| 📝 **الطلب + تسجيل الوكيل** | الطلب/الاستجابة الكاملة وتسجيل الوكيل |
-| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |
-| 📋 **لوحة تحكم السجلات الموحدة** | طلب العروض والوكيل والتدقيق ووحدة التحكم في صفحة واحدة |
-| 🔍 **طلب القياس عن بعد** | زمن الاستجابة p50/p95/p99 وطلب التتبع |
-| 🏥 **لوحة المعلومات الصحية** | وقت التشغيل، حالات الكسارة، عمليات الإغلاق، إحصائيات ذاكرة التخزين المؤقت |
-| 💰 **تتبع التكلفة** | ضوابط الميزانية ورؤية التسعير لكل نموذج |
-| 📈 **تصورات التحليلات** | رؤى استخدام النموذج/الموفر وطرق عرض الاتجاه |
-| 🧪 **إطار التقييم** | اختبار المجموعة الذهبية مع استراتيجيات المطابقة القابلة للتكوين |
+### ⚫ 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 |
-| ميزة | ماذا يفعل |
-| -------------------------------- | --------------------------------------------------------- | --- | ------------------------ | ------------------------------- |
-| 🌐 **النشر في أي مكان** | المضيف المحلي، VPS، Docker، البيئات السحابية | | 💾 **المزامنة السحابية** | مزامنة التكوين عبر عامل السحابة |
-| 🔄 **النسخ الاحتياطي/الاستعادة** | تدفقات التصدير/الاستيراد والتعافي من الكوارث |
-| 🧙 **معالج الإعداد** | الإعداد الموجه لأول مرة |
-| 🔧 **لوحة تحكم أدوات CLI** | إعداد بنقرة واحدة لأدوات الترميز الشائعة |
-| 🌐 **i18n (30 لغة)** | لوحة تحكم كاملة + دعم لغة المستندات مع تغطية RTL |
-| 🧹 **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 |
-| 📂 **دليل البيانات المخصصة** | تجاوز `DATA_DIR` لموقع التخزين |
+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
+> iFlow (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 v2.0 is built as an operational platform, not just a relay proxy.
+
+### 🆕 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 Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |
+| 🤖 **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 (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) |
+| 🤝 **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** | 9 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 combo, apply resilience profiles, reset breakers from one control surface |
+
+### 🧠 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** | 6 balancing strategies + fallback chain control |
+| 🌐 **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) |
+| 💬 **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 |
+| ----------------------------------- | -------------------------------------------------------------------------------------- |
+| 🔌 **Circuit Breakers** | Per-model trip/recover with threshold controls |
+| 🎯 **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 |
+| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |
+| 🔑 **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 |
+
+### 📊 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 |
+| 📋 **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 |
+
+### ☁️ Deployment & Platform
+
+| Feature | What It Does |
+| ----------------------------- | --------------------------------------------------------- |
+| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |
+| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |
+| 💾 **Cloud Sync** | Configuration sync via cloud worker |
+| 🔄 **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 |
+
+### Feature Deep Dive
+
+#### Smart fallback with practical cost control
```txt
Combo: "my-coding-stack"
@@ -954,87 +1300,91 @@ Combo: "my-coding-stack"
4. if/kimi-k2-thinking
```
-عند فشل الحصة أو المعدل أو الصحة، ينتقل OmniRoute تلقائيًا إلى المرشح التالي دون التبديل اليدوي.
+When quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.
-#### إدارة البروتوكول مرئية وقابلة للتشغيل
+#### Protocol management that is visible and operable
-- يمكن اكتشاف MCP + A2A في واجهة المستخدم والمستندات (غير مخفية)
-- تعرض واجهات برمجة التطبيقات لحالة البروتوكول بيانات التشغيل المباشرة (`/api/mcp/*`، `/api/a2a/*`)
-- تتضمن لوحات المعلومات إجراءات لعمليات اليوم الثاني (تبديل التحرير والسرد، وإعادة ضبط الكسارة، وإلغاء المهام)
+- 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)
-#### سير عمل المترجم + التحقق من الصحة
+#### 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
-بالإضافة إلى التحقق من صحة البروتوكول مع عملاء حقيقيين عبر `npm run test:protocols:e2e`.
+Plus protocol validation with real clients via `npm run test:protocols:e2e`.
-> 📖 **[قراءة خادم MCP](open-sse/mcp-server/README.md)** — مرجع الأداة، وتكوينات IDE، وأمثلة العميل
+> 📖 **[MCP Server README](open-sse/mcp-server/README.md)** — Tool reference, IDE configs, and client examples
>
-> 📖 **[ملف قراءة خادم A2A](src/lib/a2a/README.md)** — المهارات، وأساليب JSON-RPC، والبث، ودورة حياة المهمة
+> 📖 **[A2A Server README](src/lib/a2a/README.md)** — Skills, JSON-RPC methods, streaming, and task lifecycle
-## 🧪 التقييمات (التقييمات)
+## 🧪 Evaluations (Evals)
-يشتمل OmniRoute على إطار تقييم مدمج لاختبار جودة استجابة LLM مقابل المجموعة الذهبية. يمكنك الوصول إليه عبر **Analytics → 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
-تحتوي "OmniRoute Golden Set" المحملة مسبقًا على حالات اختبار لما يلي:
+The pre-loaded "OmniRoute Golden Set" contains test cases for:
-- تحياتي، الرياضيات، الجغرافيا، توليد التعليمات البرمجية
-- الامتثال لتنسيق JSON والترجمة وإنشاء تخفيض السعر
-- رفض السلامة (المحتوى الضار)، العد، المنطق المنطقي
+- Greetings, math, geography, code generation
+- JSON format compliance, translation, markdown generation
+- Safety refusal (harmful content), counting, boolean logic
-### استراتيجيات التقييم
+### Evaluation Strategies
-| استراتيجية | الوصف | مثال |
-| ---------- | ------------------------------------------------------------- | -------------------------------- |
-| `exact` | يجب أن يتطابق الإخراج تمامًا مع | `"4"` |
-| `contains` | يجب أن يحتوي الإخراج على سلسلة فرعية (غير حساسة لحالة الأحرف) | `"Paris"` |
-| `regex` | يجب أن يتطابق الإخراج مع نمط regex | `"1.*2.*3"` |
-| `custom` | ترجع دالة JS المخصصة صواب/خطأ | `(output) => output.length > 10` |
+| 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
-### إعداد البروتوكول (MCP + A2A)
+### Protocol Setup (MCP + A2A)
🚀 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) + +
-
-🧩 إعداد MCP (بروتوكول سياق النموذج)
+🧩 MCP Setup (Model Context Protocol)
-بدء نقل MCP في وضع stdio: +Start MCP transport in stdio mode: ```bash omniroute --mcp ``` -تدفق التحقق الموصى به: +Recommended validation flow: -1. قم بتوصيل عميل MCP الخاص بك عبر stdio. -2. قم بتشغيل `omniroute_get_health`. -3. قم بتشغيل `omniroute_list_combos`. -4. افتح `/dashboard/mcp` لتأكيد نبضات القلب والنشاط والتدقيق. +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` +- `GET /api/mcp/status` +- `GET /api/mcp/tools` +- `GET /api/mcp/audit` +- `GET /api/mcp/audit/stats`🤝 إعداد A2A (Agent2Agent)
+
+
🤝 A2A Setup (Agent2Agent)
-اكتشف الوكيل: +Discover the agent: ```bash curl http://localhost:20128/.well-known/agent.json ``` -إرسال مهمة: +Send a task: ```bash curl -X POST http://localhost:20128/a2a \ @@ -1042,37 +1392,40 @@ curl -X POST http://localhost:20128/a2a \ -d '{"jsonrpc":"2.0","id":"setup-a2a","method":"message/send","params":{"skill":"quota-management","messages":[{"role":"user","content":"Summarize quota status."}]}}' ``` -إدارة دورة الحياة: +Manage lifecycle: --`GET /api/a2a/status` -`GET /api/a2a/tasks` -`GET /api/a2a/tasks/:id` -`POST /api/a2a/tasks/:id/cancel` +- `GET /api/a2a/status` +- `GET /api/a2a/tasks` +- `GET /api/a2a/tasks/:id` +- `POST /api/a2a/tasks/:id/cancel` -واجهة المستخدم التشغيلية: +Operational UI: -- `/dashboard/a2a` لإمكانية ملاحظة المهمة/الحالة/الدفق وإجراءات الدخان +- `/dashboard/a2a` for task/state/stream observability and smoke actions
-
🧪 التحقق من صحة البروتوكول من طرف إلى طرف
+🧪 End-to-end protocol validation
-التحقق من صحة كلا البروتوكولين مع عملاء حقيقيين: +Validate both protocols with real clients: ```bash npm run test:protocols:e2e ``` -هذا يتحقق: +This verifies: -- اتصال/قائمة/اتصال عميل MCP SDK -- اكتشاف A2A/إرسال/دفق/حصول على/إلغاء -- التحقق من البيانات في تدقيق MCP وواجهات برمجة التطبيقات لإدارة المهام A2A +- 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) ```bash Dashboard → Providers → Connect Claude Code @@ -1085,7 +1438,7 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**نصيحة احترافية:** استخدم Opus للمهام المعقدة، وSonnet للسرعة. OmniRoute يتتبع الحصة لكل نموذج! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! ### OpenAI Codex (Plus/Pro) @@ -1099,7 +1452,24 @@ Models: cx/gpt-5.1-codex-max ``` -### Gemini CLI (180 ألفًا شهريًا مجانًا!) +#### 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). + +### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -1111,9 +1481,9 @@ Models: gc/gemini-2.5-pro ``` -**أفضل قيمة:** طبقة مجانية ضخمة! استخدم هذا قبل المستويات المدفوعة. +**Best Value:** Huge free tier! Use this before paid tiers. -### مساعد جيثب +### GitHub Copilot ```bash Dashboard → Providers → Connect GitHub @@ -1129,103 +1499,103 @@ Models:
-
🔑 موفري مفاتيح واجهة برمجة التطبيقات
+🔑 API Key Providers
-### NVIDIA NIM (1000 نقطة مجانية!) +### NVIDIA NIM (FREE developer access — 70+ models) -1. قم بالتسجيل: [build.nvidia.com](https://build.nvidia.com) -2. احصل على مفتاح واجهة برمجة التطبيقات (API) مجانًا (يتضمن 1000 نقطة استدلال) -3. لوحة المعلومات → إضافة موفر → NVIDIA NIM: - - مفتاح API: `nvapi-your-key` +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` -**النماذج:** `nvidia/llama-3.3-70b-instruct` و`nvidia/mistral-7b-instruct` وأكثر من 50 طرازًا آخر +**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more -**نصيحة احترافية:** واجهة برمجة التطبيقات المتوافقة مع OpenAI — تعمل بسلاسة مع ترجمة تنسيق OmniRoute! +**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation! -### ديب سيك +### DeepSeek -1. قم بالتسجيل: [platform.deepseek.com](https://platform.deepseek.com) -2. احصل على مفتاح API -3. لوحة المعلومات → إضافة موفر → DeepSeek +1. Sign up: [platform.deepseek.com](https://platform.deepseek.com) +2. Get API key +3. Dashboard → Add Provider → DeepSeek -**النماذج:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` +**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` -### Groq (الطبقة المجانية متاحة!) +### Groq (Free Tier Available!) -1. قم بالتسجيل: [console.groq.com](https://console.groq.com) -2. احصل على مفتاح API (الطبقة المجانية متضمنة) -3. لوحة المعلومات → إضافة موفر → Groq +1. Sign up: [console.groq.com](https://console.groq.com) +2. Get API key (free tier included) +3. Dashboard → Add Provider → Groq -**النماذج:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` +**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` -**نصيحة احترافية:** استنتاج فائق السرعة — الأفضل للبرمجة في الوقت الفعلي! +**Pro Tip:** Ultra-fast inference — best for real-time coding! -### OpenRouter (+100 موديل) +### OpenRouter (100+ Models) -1. قم بالتسجيل: [openrouter.ai](https://openrouter.ai) -2. احصل على مفتاح API -3. لوحة المعلومات → إضافة موفر → OpenRouter +1. Sign up: [openrouter.ai](https://openrouter.ai) +2. Get API key +3. Dashboard → Add Provider → OpenRouter -**النماذج:** يمكنك الوصول إلى أكثر من 100 نموذج من جميع المزودين الرئيسيين من خلال مفتاح واجهة برمجة التطبيقات (API) واحد. +**Models:** Access 100+ models from all major providers through a single API key.
-
💰 مقدمو الخدمة الرخيصة (النسخ الاحتياطي)
+💰 Cheap Providers (Backup)
-### GLM-4.7 (إعادة التعيين اليومي، 0.6 دولار/1 مليون) +### GLM-4.7 (Daily reset, $0.6/1M) -1. قم بالتسجيل: [Zhipu AI](https://open.bigmodel.cn/) -2. احصل على مفتاح API من خطة الترميز -3. لوحة المعلومات → إضافة مفتاح واجهة برمجة التطبيقات: - - المزود: `glm` - - مفتاح API: `your-key` +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` -**الاستخدام:** `glm/glm-4.7` +**Use:** `glm/glm-4.7` -**نصيحة احترافية:** توفر خطة البرمجة حصة 3× بتكلفة 1/7! إعادة الضبط يوميًا الساعة 10:00 صباحًا. +**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -### MiniMax M2.1 (إعادة الضبط لمدة 5 ساعات، 0.20 دولار/1 مليون) +### MiniMax M2.1 (5h reset, $0.20/1M) -1. قم بالتسجيل: [MiniMax](https://www.minimax.io/) -2. احصل على مفتاح API -3. لوحة المعلومات → إضافة مفتاح API +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key +3. Dashboard → Add API Key -**الاستخدام:** `minimax/MiniMax-M2.1` +**Use:** `minimax/MiniMax-M2.1` -**نصيحة احترافية:** الخيار الأرخص للسياق الطويل (مليون رمز)! +**Pro Tip:** Cheapest option for long context (1M tokens)! -### كيمي K2 (شقة بقيمة 9 دولارات شهريًا) +### Kimi K2 ($9/month flat) -1. الاشتراك: [Moonshot AI](https://platform.moonshot.ai/) -2. احصل على مفتاح API -3. لوحة المعلومات → إضافة مفتاح API +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key +3. Dashboard → Add API Key -**الاستخدام:** `kimi/kimi-latest` +**Use:** `kimi/kimi-latest` -**نصيحة احترافية:** سعر ثابت قدره 9 دولارات شهريًا مقابل 10 ملايين رمز مميز = 0.90 دولارًا أمريكيًا/مليون تكلفة فعالة! +**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
-
🆓 موفري الخدمة المجانية (النسخ الاحتياطي في حالات الطوارئ)
+🆓 FREE Providers (Emergency Backup)
-### iFlow (8 نماذج مجانية)```bash +### iFlow (5 FREE models via OAuth) +```bash Dashboard → Connect iFlow → iFlow OAuth login → Unlimited usage Models: -if/kimi-k2-thinking -if/qwen3-coder-plus -if/glm-4.7 -if/minimax-m2 -if/deepseek-r1 + if/kimi-k2-thinking + if/qwen3-coder-plus + if/glm-4.7 + if/minimax-m2 + if/deepseek-r1 +``` -```` - -### كوين (3 موديلات مجانية) +### Qwen (4 FREE models via Device Code) ```bash Dashboard → Connect Qwen @@ -1235,9 +1605,9 @@ Dashboard → Connect Qwen Models: qw/qwen3-coder-plus qw/qwen3-coder-flash -```` +``` -### كيرو (كلود فري) +### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro @@ -1252,9 +1622,9 @@ Models:
-
🎨 إنشاء المجموعات
+🎨 Create Combos
-### مثال 1: زيادة الاشتراك إلى الحد الأقصى → النسخ الاحتياطي الرخيص +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -1268,7 +1638,7 @@ Models: Use in CLI: premium-coding ``` -### المثال 2: مجاني فقط (بدون تكلفة) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -1283,9 +1653,9 @@ Cost: $0 forever!
-
---
-## 🐛 استكشاف الأخطاء وإصلاحها
+## استكشاف الأخطاء
🔧 تكامل CLI
+🔧 CLI Integration
-### بيئة تطوير متكاملة للمؤشر +### Cursor IDE ``` Settings → Models → Advanced: @@ -1294,11 +1664,11 @@ Settings → Models → Advanced: Model: cc/claude-opus-4-6 ``` -### كلود كود +### Claude Code -استخدم صفحة **أدوات CLI** في لوحة المعلومات للتكوين بنقرة واحدة، أو قم بتحرير `~/.claude/settings.json` يدويًا. +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" @@ -1309,13 +1679,13 @@ codex "your prompt" ### OpenClaw -**الخيار 1 — لوحة التحكم (مستحسن):** +**Option 1 — Dashboard (recommended):** ``` Dashboard → CLI Tools → OpenClaw → Select Model → Apply ``` -**الخيار 2 — يدويًا:** تحرير `~/.openclaw/openclaw.json`: +**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`: ```json { @@ -1331,9 +1701,9 @@ Dashboard → CLI Tools → OpenClaw → Select Model → Apply } ``` -> **ملاحظة:** يعمل OpenClaw فقط مع OmniRoute المحلي. استخدم `127.0.0.1` بدلاً من `localhost` لتجنب مشكلات دقة IPv6. +> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues. -### كلاين / متابعة / RooCode +### Cline / Continue / RooCode ``` Settings → API Configuration: @@ -1343,9 +1713,9 @@ Settings → API Configuration: Model: if/kimi-k2-thinking ``` -### الكود المفتوح +### OpenCode -**الخطوة 1:** أضف OmniRoute كموفر مخصص: +**Step 1:** Add OmniRoute as a custom provider: ```bash opencode @@ -1353,7 +1723,7 @@ opencode # Select "Other" → Enter ID: "omniroute" → Enter your OmniRoute API key ``` -**الخطوة 2:** إنشاء/تحرير `opencode.json` في جذر مشروعك: +**Step 2:** Create/edit `opencode.json` in your project root: ```json { @@ -1375,120 +1745,213 @@ opencode } ``` -**الخطوة 3:** حدد النموذج في OpenCode: +**Step 3:** Select the model in OpenCode: ```bash /models # Select any OmniRoute model from the list ``` -> **نصيحة:** أضف أي نموذج متوفر في نقطة نهاية OmniRoute `/v1/models` إلى قسم `models`. استخدم التنسيق `provider/model-id` من لوحة معلومات OmniRoute. +> **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.
-
+
+## 🛠️ Tech Stack
انقر لتوسيع دليل استكشاف الأخطاء وإصلاحها
+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** -- حصة الاشتراك المحددة → الرجوع إلى GLM/MiniMax -- إضافة التحرير والسرد: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Subscription quota out → Fallback to GLM/MiniMax +- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -** انتهت صلاحية رمز OAuth ** +**OAuth token expired** -- يتم التحديث تلقائيًا بواسطة OmniRoute -- إذا استمرت المشكلات: لوحة المعلومات → الموفر → إعادة الاتصال +- Auto-refreshed by OmniRoute +- If issues persist: Dashboard → Provider → Reconnect -**تكاليف مرتفعة** +**High costs** -- التحقق من إحصائيات الاستخدام في لوحة المعلومات → التكاليف -- تبديل النموذج الأساسي إلى GLM/MiniMax -- استخدم الطبقة المجانية (Gemini CLI، iFlow) للمهام غير الحرجة +- Check usage stats in Dashboard → Costs +- Switch primary model to GLM/MiniMax +- Use free tier (Gemini CLI, iFlow) for non-critical tasks -**منافذ لوحة المعلومات/واجهة برمجة التطبيقات غير صحيحة** +**Dashboard/API ports are wrong** -- `PORT` هو المنفذ الأساسي الأساسي (ومنفذ API افتراضيًا) -- يتجاوز `API_PORT` مستمع واجهة برمجة التطبيقات (API) المتوافق مع OpenAI فقط -- يتجاوز `DASHBOARD_PORT` مستمع لوحة المعلومات/Next.js فقط -- قم بتعيين `NEXT_PUBLIC_BASE_URL` على لوحة المعلومات/عنوان URL العام (لعمليات الاسترجاعات عبر OAuth) +- `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** -- تحقق من نقاط `BASE_URL` لمثيلك قيد التشغيل -- تحقق من نقاط `CLOUD_URL` إلى نقطة النهاية السحابية المتوقعة -- حافظ على محاذاة قيم `NEXT_PUBLIC_*` مع القيم من جانب الخادم +- 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** -- تحقق من `INITIAL_PASSWORD` في `.env` -- في حالة عدم تعيينها، تكون كلمة المرور الاحتياطية هي `123456` +- Check `INITIAL_PASSWORD` in `.env` +- If unset, fallback password is `123456` -** لا توجد سجلات الطلب ** +**No request logs** -- تعيين `ENABLE_REQUEST_LOGS=true` في `.env` +- Set `ENABLE_REQUEST_LOGS=true` in `.env` -**يظهر اختبار الاتصال "غير صالح" لمقدمي الخدمات المتوافقين مع OpenAI** +**Connection test shows "Invalid" for OpenAI-compatible providers** -- لا يكشف العديد من مقدمي الخدمة عن نقطة نهاية `/models` -- يتضمن OmniRoute v1.0.6+ التحقق الاحتياطي من خلال إكمال الدردشة -- تأكد من أن عنوان URL الأساسي يتضمن لاحقة `/v1` +- 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 +### 🔐 OAuth on a Remote Server + -> **⚠️ هام لمستخدمي OmniRoute على VPS/Docker/servidor عن بعد** +> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server** -#### OAuth +#### Why does Antigravity / Gemini CLI OAuth fail on remote servers? -نظرًا لأن اعتمادات OAuth المُدخلة ليست في OmniRoute، فهي عبارة عن سجلات **apenas لـ `localhost`**. عندما تصل إلى OmniRoute من خادم بعيد (على سبيل المثال: `https://omniroute.meuservidor.com`)، تحصل Google على مصادقة عبر: +The **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console. + +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 ``` -#### الحل: تكوين OAuth الخاص بك +#### Solution: Configure your own OAuth credentials -يجب عليك إنشاء **OAuth 2.0 Client ID** على Google Cloud Console باستخدام URI لخادمك. +You need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI. -#### باسو باسو +#### Step-by-step -**1. الوصول إلى Google Cloud Console** +**1. Open Google Cloud Console** -العبرة: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) +Go to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) -**2. طلب معرف عميل OAuth 2.0 ** +**2. Create a new OAuth 2.0 Client ID** -- انقر على **"+ إنشاء بيانات الاعتماد"** → **"معرف عميل OAuth"** -- نوع التطبيق: **"تطبيق ويب"** -- الاسم: اسم escolha qualquer (على سبيل المثال: `OmniRoute Remote`) +- Click **"+ Create Credentials"** → **"OAuth client ID"** +- Application type: **"Web application"** +- Name: anything you like (e.g. `OmniRoute Remote`) -**3. Adicione كمحددات URI لإعادة التوجيه المعتمدة** +**3. Add Authorized Redirect URIs** -ليس هناك مجال **"عناوين URI لإعادة التوجيه المعتمدة"**، أضف: +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 + +# For Gemini CLI: +GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com +GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +``` + +**6. Restart OmniRoute** + +```bash +# npm: +npm run dev + +# Docker: +docker restart omniroute +``` + +**7. Try connecting again** + +Dashboard → Providers → Antigravity (or Gemini CLI) → OAuth + +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. + +--- + +
+
---
-## 🛠️
+🇧🇷 Versão em Português
+ +#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos? + +Os provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo. + +As credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticação com: + +``` +Error 400: redirect_uri_mismatch +``` + +#### Solução: Configure suas próprias credenciais OAuth + +Você precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor. + +#### Passo a passo + +**1. Acesse o Google Cloud Console** + +Abra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) + +**2. Crie um novo OAuth 2.0 Client ID** + +- Clique em **"+ Create Credentials"** → **"OAuth client ID"** +- Tipo de aplicativo: **"Web application"** +- Nome: escolha qualquer nome (ex: `OmniRoute Remote`) + +**3. Adicione as Authorized Redirect URIs** + +No campo **"Authorized redirect URIs"**, adicione: ``` https://seu-servidor.com/callback ``` -> استبدال `seu-servidor.com` بنطاقك أو IP بخادمك (بما في ذلك البوابة الضرورية، على سبيل المثال: `http://45.33.32.156:20128/callback`). +> Substitua `seu-servidor.com` pelo domínio ou IP do seu servidor (inclua a porta se necessário, ex: `http://45.33.32.156:20128/callback`). -**4. حفظ ونسخ كمعتمدة** +**4. Salve e copie as credenciais** -وبعد ذلك، قم بإنشاء أو عرض Google o **معرف العميل** أو **سر العميل**. +Após criar, o Google mostrará o **Client ID** e o **Client Secret**. -**5. تكوين كمتغيرات البيئة ** +**5. Configure as variáveis de ambiente** -ليس لديك `.env` (أو في بيئة Docker المتنوعة): +No seu `.env` (ou nas variáveis de ambiente do Docker): ```bash # Para Antigravity: @@ -1501,7 +1964,7 @@ GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret ``` -**6. Reinicie أو OmniRoute** +**6. Reinicie o OmniRoute** ```bash # Se usando npm: @@ -1511,112 +1974,116 @@ npm run dev docker restart omniroute ``` -**7. خيمة تواصل جديدة** +**7. Tente conectar novamente** -لوحة المعلومات → الموفرون → Antigravity (ou Gemini CLI) → OAuth +Dashboard → Providers → Antigravity (ou Gemini CLI) → OAuth -قم بإعادة توجيه Google بشكل صحيح إلى `https://seu-servidor.com/callback` ووظيفة المصادقة. +Agora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará. --- -#### الحل المؤقت (لم يتم تكوين الاعتمادات الخاصة) +#### Workaround temporário (sem configurar credenciais próprias) -إذا لم ترغب في إنشاء بيانات اعتماد خاصة بك منذ الآن، فمن الممكن استخدام التدفق **دليل URL**: +Se não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**: -1. يفتح OmniRoute عنوان URL لتفويض Google -2. قم بتفويض Google لإعادة توجيه `localhost` (لا يوجد خادم عن بعد) -3. **انسخ عنوان URL كاملاً** من شريط الإدخال في متصفحك (حتى لا يتم نقل الصفحة) -4. هذا هو عنوان URL الذي يظهر في وضع الاتصال بـ OmniRoute -5. انقر على **"الاتصال"** +1. O OmniRoute abrirá a URL de autorização do Google +2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto) +3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue) +4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute +5. Clique em **"Connect"** -> يعمل هذا الحل البديل لأن رمز التفويض الموجود على عنوان URL يكون صالحًا بشكل مستقل لإعادة التوجيه حيث يتم تحميله أو لا. +> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.
-
---
-## 📖 التوثيق
+## التوثيق
-| وثيقة | الوصف |
-| --------------------------------------------------- | ----------------------------------------------------- |
-| [دليل المستخدم](docs/USER_GUIDE.md) | مقدمو الخدمات، والمجموعات، وتكامل CLI، والنشر |
-| [مرجع واجهة برمجة التطبيقات](docs/API_REFERENCE.md) | جميع نقاط النهاية مع الأمثلة |
-| [خادم MCP](open-sse/mcp-server/README.md) | 16 أدوات MCP وتكوينات IDE وعملاء Python/TS/Go |
-| [خادم A2A](src/lib/a2a/README.md) | بروتوكول JSON-RPC 2.0، المهارات، التدفق، إدارة المهام |
-| [محرك التحرير والسرد التلقائي](docs/auto-combo.md) | تسجيل 6 عوامل، حزم الوضع، الشفاء الذاتي |
-| [استكشاف الأخطاء وإصلاحها](docs/TROUBLESHOOTING.md) | المشاكل والحلول الشائعة |
-| [الهندسة المعمارية](docs/ARCHITECTURE.md) | بنية النظام والداخلية |
-| [مساهمة](CONTRIBUTING.md) | إعداد التطوير والمبادئ التوجيهية |
-| [مواصفات OpenAPI](docs/openapi.yaml) | مواصفات OpenAPI 3.0 |
-| [سياسة الأمان](SECURITY.md) | الإبلاغ عن الثغرات الأمنية والممارسات الأمنية |
-| [نشر الجهاز الافتراضي](docs/VM_DEPLOYMENT_GUIDE.md) | الدليل الكامل: إعداد VM + nginx + Cloudflare |
-| [معرض الميزات](docs/FEATURES.md) | جولة لوحة القيادة المرئية مع لقطات الشاشة |
-| [قائمة مراجعة الإصدار](docs/RELEASE_CHECKLIST.md) | خطوات التحقق من صحة الإصدار المسبق |
+| Document | Description |
+| ---------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 16 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/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
+| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
-## 🗺️خريطة الطريق
+## 🗺️ Roadmap
-يحتوي OmniRoute على **210+ ميزات مخطط لها** عبر مراحل تطوير متعددة. فيما يلي المجالات الرئيسية:
+OmniRoute has **210+ features planned** across multiple development phases. Here are the key areas:
-| الفئة | الميزات المخططة | أبرز الأحداث |
-| --------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| 🧠 **التوجيه والاستخبارات** | 25+ | التوجيه ذو زمن الاستجابة الأقل، والتوجيه القائم على العلامات، والاختبار المبدئي للحصة، واختيار حساب P2C |
-| 🔒 **الأمان والامتثال** | 20+ | تقوية SSRF، وإخفاء بيانات الاعتماد، والحد الأقصى للمعدل لكل نقطة نهاية، وتحديد نطاق مفتاح الإدارة |
-| 📊 **قابلية الملاحظة** | 15+ | تكامل OpenTelemetry ومراقبة الحصص في الوقت الفعلي وتتبع التكلفة لكل نموذج |
-| 🔄 **تكامل الموفر** | 20+ | تسجيل النموذج الديناميكي، فترات تهدئة الموفر، الدستور الغذائي متعدد الحسابات، تحليل حصة الطيار المساعد |
-| ⚡ **الأداء** | 15+ | طبقة ذاكرة التخزين المؤقت المزدوجة، ذاكرة التخزين المؤقت السريعة، ذاكرة التخزين المؤقت للاستجابة، استمرار البث، واجهة برمجة التطبيقات الدفعية |
-| 🌐 **النظام البيئي** | 10+ | WebSocket API، إعادة تحميل التكوين السريع، مخزن التكوين الموزع، الوضع التجاري |
+| Category | Planned Features | Highlights |
+| ----------------------------- | ---------------- | -------------------------------------------------------------------------------------- |
+| 🧠 **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, P2C account selection |
+| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |
+| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |
+| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider 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 |
-### 🔜قريبا- 🔗 **تكامل OpenCode** — دعم الموفر الأصلي لـ OpenCode AI IDE للترميز
+### 🔜 Coming Soon
-- 🔗 **تكامل TRAE** — الدعم الكامل لإطار تطوير TRAE AI
-- 📦 **Batch API** — معالجة الدفعات غير المتزامنة للطلبات المجمعة
-- 🎯 **التوجيه المعتمد على العلامات** — توجيه الطلبات بناءً على العلامات المخصصة والبيانات الوصفية
-- 💰 **إستراتيجية أقل تكلفة** — تحديد أرخص مزود متاح تلقائيًا
+- 🔗 **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
-> 📝 مواصفات الميزات الكاملة متوفرة في [`docs/new-features/`](docs/new-features/) (217 مواصفات تفصيلية)
+> 📝 Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)
---
-## 👥 المساهمون
+## 👥 Contributors
-[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
+[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
-### كيفية المساهمة
+### How to Contribute
-1. شوكة المستودع
-2. قم بإنشاء فرع الميزات الخاص بك (`git checkout -b feature/amazing-feature`)
-3. تنفيذ التغييرات (`git commit -m 'Add amazing feature'`)
-4. ادفع إلى الفرع (`git push origin feature/amazing-feature`)
-5. افتح طلب السحب
+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
-راجع [CONTRIBUTING.md](CONTRIBUTING.md) للحصول على إرشادات مفصلة.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
-### إطلاق نسخة جديدة
+### Releasing a New Version
```bash
# Create a release — npm publish happens automatically
@@ -1625,28 +2092,28 @@ gh release create v2.0.0 --title "v2.0.0" --generate-notes
---
-## 📊 تاريخ النجوم
+## 📊 Star History
## Stargazers over time
## [](https://starchart.cc/diegosouzapw/OmniRoute)
-## 🙏 شكر وتقدير
+## 🙏 Acknowledgments
-شكر خاص لـ **[9router](https://github.com/decolua/9router)** بواسطة **[decolua](https://github.com/decolua)** — المشروع الأصلي الذي ألهم هذه الشوكة. يعتمد OmniRoute على هذا الأساس المذهل مع ميزات إضافية وواجهات برمجة التطبيقات متعددة الوسائط وإعادة كتابة TypeScript كاملة.
+Special thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.
-شكر خاص لـ **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — تطبيق Go الأصلي الذي ألهم منفذ JavaScript هذا.
+Special thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.
---
-## 📄 الترخيص
+## الرخصة
-ترخيص MIT - راجع [الترخيص](LICENSE) للحصول على التفاصيل.
+MIT License - see [LICENSE](LICENSE) for details.
---
انقر لتوسيع تفاصيل حزمة التقنية
+Click to expand tech stack details
-- **وقت التشغيل**: Node.js 18–22 LTS (⚠️ Node.js 24+ **غير مدعومة** — الثنائيات الأصلية `better-sqlite3` غير متوافقة) -- **اللغة**: TypeScript 5.9 — **TypeScript بنسبة 100%** عبر `src/` و`open-sse/` (لا يوجد `any` في الوحدات الأساسية منذ الإصدار 2.0) -- **الإطار**: Next.js 16 + React 19 + Tailwind CSS 4 -- **قاعدة البيانات**: LowDB (JSON) + SQLite (حالة المجال + سجلات الوكيل + تدقيق MCP + قرارات التوجيه) -- **المخططات**: Zod (التحقق من صحة الإدخال/الإخراج لأداة MCP، وعقود API) -- **البروتوكولات**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE) -- **البث**: الأحداث المرسلة من الخادم (SSE) -- **المصادقة**: OAuth 2.0 (PKCE) + JWT + مفاتيح API + ترخيص نطاق MCP -- **الاختبار**: مشغل اختبار Node.js + Vitest (أكثر من 900 اختبار بما في ذلك الوحدة والتكامل وE2E)- **CI/CD**: إجراءات GitHub (نشر npm التلقائي + Docker Hub عند الإصدار) -- **الموقع الإلكتروني**: [omniroute.online](https://omniroute.online) -- **الحزمة**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute) -- **دوكر**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute) -- **المرونة**: قاطع الدائرة، والتراجع الأسي، وقطيع مكافحة الرعد، وانتحال TLS، والإصلاح الذاتي للتحرير والسرد التلقائي +- **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**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions) +- **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
- تم تصميمه باستخدام ❤️ للمطورين الذين يبرمجون 24/7
+ Built with ❤️ for developers who code 24/7
omniroute.online
diff --git a/docs/i18n/ar/docs/FEATURES.md b/docs/i18n/ar/docs/FEATURES.md
new file mode 100644
index 0000000000..55f891adce
--- /dev/null
+++ b/docs/i18n/ar/docs/FEATURES.md
@@ -0,0 +1,145 @@
+# OmniRoute — Dashboard Features Gallery (العربية)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/FEATURES.md) · 🇪🇸 [es](../../es/docs/FEATURES.md) · 🇫🇷 [fr](../../fr/docs/FEATURES.md) · 🇩🇪 [de](../../de/docs/FEATURES.md) · 🇮🇹 [it](../../it/docs/FEATURES.md) · 🇷🇺 [ru](../../ru/docs/FEATURES.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FEATURES.md) · 🇯🇵 [ja](../../ja/docs/FEATURES.md) · 🇰🇷 [ko](../../ko/docs/FEATURES.md) · 🇸🇦 [ar](../../ar/docs/FEATURES.md) · 🇮🇳 [in](../../in/docs/FEATURES.md) · 🇹🇭 [th](../../th/docs/FEATURES.md) · 🇻🇳 [vi](../../vi/docs/FEATURES.md) · 🇮🇩 [id](../../id/docs/FEATURES.md) · 🇲🇾 [ms](../../ms/docs/FEATURES.md) · 🇳🇱 [nl](../../nl/docs/FEATURES.md) · 🇵🇱 [pl](../../pl/docs/FEATURES.md) · 🇸🇪 [sv](../../sv/docs/FEATURES.md) · 🇳🇴 [no](../../no/docs/FEATURES.md) · 🇩🇰 [da](../../da/docs/FEATURES.md) · 🇫🇮 [fi](../../fi/docs/FEATURES.md) · 🇵🇹 [pt](../../pt/docs/FEATURES.md) · 🇷🇴 [ro](../../ro/docs/FEATURES.md) · 🇭🇺 [hu](../../hu/docs/FEATURES.md) · 🇧🇬 [bg](../../bg/docs/FEATURES.md) · 🇸🇰 [sk](../../sk/docs/FEATURES.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FEATURES.md) · 🇮🇱 [he](../../he/docs/FEATURES.md) · 🇵🇭 [phi](../../phi/docs/FEATURES.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FEATURES.md)
+
+---
+
+Visual guide to every section of the OmniRoute dashboard.
+
+---
+
+## 🔌 Providers
+
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
+
+
+
+---
+
+## 🎨 Combos
+
+Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
+
+
+
+---
+
+## 📊 Analytics
+
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
+
+
+
+---
+
+## 🏥 System Health
+
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+
+
+
+---
+
+## 🔧 Translator Playground
+
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
+
+
+
+---
+
+## 🎮 Model Playground _(v2.0.9+)_
+
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
+
+---
+
+## 🎨 Themes _(v2.0.5+)_
+
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
+
+## ⚙️ Settings
+
+Comprehensive settings panel with tabs:
+
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning
+- **Advanced** — Configuration overrides
+
+
+
+---
+
+## 🔧 CLI Tools
+
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
+
+
+
+---
+
+## 🤖 CLI Agents _(v2.0.11+)_
+
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
+
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
+
+---
+
+## 🖼️ Media _(v2.0.3+)_
+
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
+
+## 📝 Request Logs
+
+Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
+
+
+
+---
+
+## 🌐 API Endpoint
+
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
+
+
+
+---
+
+## 🔑 API Key Management
+
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
+
+---
+
+## 📋 Audit Log
+
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
+
+---
+
+## 🖥️ Desktop Application
+
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
+
+Key features:
+
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
+
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.
diff --git a/docs/i18n/bg/README.md b/docs/i18n/bg/README.md
index 6c0a4bcd90..2565b5af67 100644
--- a/docs/i18n/bg/README.md
+++ b/docs/i18n/bg/README.md
@@ -1,16 +1,89 @@
-# 🚀 OmniRoute — Безплатният AI Gateway
+# 🚀 OmniRoute — The Free AI Gateway (Български)
-### Никога не спирайте да кодирате. Интелигентно маршрутизиране към **БЕЗПЛАТНИ и евтини AI модели** с автоматичен резервен вариант.
-
-_Вашият универсален API прокси — една крайна точка, 36+ доставчици, нулев престой. Сега с **MCP & A2A** агентска оркестрация._
-
-**Завършвания на чат • Вграждания • Генериране на изображения • Видео • Музика • Аудио • Прекласиране • MCP сървър • A2A протокол • 100% TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Безплатен доставчик на AI за вашите любими кодиращи агенти
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Свържете всеки базиран на AI IDE или CLI инструмент чрез OmniRoute — безплатен API шлюз за неограничено кодиране._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+omniroute.online
+
+[](https://www.npmjs.com/package/omniroute)
+[](https://www.npmjs.com/package/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
+[](https://omniroute.online)
+[](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)
+
+
+
+🌐 **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)
+
+---
+
+## 🆕 What's New in v3.0.0
+
+> **Upgrading from v2.9.5?** — See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes.
+
+| Area | Change |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection remediation |
+| ✅ **Route Validation** | All 176 API routes now validated with Zod schemas + `validateBody()` — CI `check:route-validation:t06` passes |
+| 🐛 **omniModel Tag Leak** | Internal `
+
+
+
+---
+
+## 📸 Dashboard Preview
+
+
+
+
+
+---
+
+### 🤖 Free AI Provider for your favorite coding agents
+
+_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._
Click to see dashboard screenshots
+ +| Page | Screenshot | +| -------------- | ------------------------------------------------- | +| **Providers** |  | +| **Combos** |  | +| **Analytics** |  | +| **Health** |  | +| **Translator** |  | +| **Settings** |  | +| **CLI Tools** |  | +| **Usage Logs** |  | +| **Endpoints** |  | + +| @@ -60,97 +134,80 @@ _Свържете всеки базиран на AI IDE или CLI инстру |
- Кодекс CLI + Codex CLI ⭐ 60.8K |
- Код на Клод + Claude Code ⭐ 67.3K |
- Близнаци CLI + Gemini CLI - ⭐ 94,7K + ⭐ 94.7K |
- Kilo код + Kilo Code - ⭐ 15,5K + ⭐ 15.5K |
http://localhost:20128/v1 или http://cloud.omniroute.online/v1 — една конфигурация, неограничени модели и квота
+📡 All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 — one config, unlimited models and quota
---
-### 🆕 What's New in v3.0.0
+## 🤔 Why OmniRoute?
-| Area | Change |
-| ------------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal ` Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal ` Абонаментната квота изтича неизползвана всеки месец
-- Ограниченията на скоростта ви спират да кодирате по средата
-- Скъпи API ($20-50/месец на доставчик)
-- Ръчно превключване между доставчици
-
-**OmniRoute решава това:**
-
-- ✅ **Увеличете максимално абонаментите** - Проследете квотата, използвайте всеки бит преди нулиране
-- ✅ **Автоматично възстановяване** - Абонамент → API ключ → Евтино → Безплатно, нулево време на престой
-- ✅ **Множество акаунти** - Кръгови сметки между акаунти на доставчик
-- ✅ **Универсален** - Работи с Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, всеки CLI инструмент
-
----
-
-## 📧 Поддръжка> 💬 **Присъединете се към нашата общност!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Получавайте помощ, споделяйте съвети и бъдете в течение.
-
-- **Уебсайт**: [omniroute.online](https://omniroute.online)
+- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Проблеми**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **WhatsApp**: [Група на общността](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Принос**: Вижте [CONTRIBUTING.md](CONTRIBUTING.md), отворете PR или изберете `good first issue`
-- **Оригинален проект**: [9router от decolua](https://github.com/decolua/9router)
+- **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`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 Как работи
+## 🔄 How It Works
```
┌─────────────┐
@@ -179,441 +236,453 @@ Result: Never stop coding, minimal cost
---
-## 🎯 Какво решава OmniRoute — 30 реални болни точки и случаи на употреба
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **Всеки разработчик, използващ AI инструменти, се сблъсква с тези проблеми всеки ден.** OmniRoute е създаден, за да разреши всички тях — от преразход на разходите до регионални блокове, от повредени OAuth потоци до операции на протоколи и корпоративна наблюдаемост.
+> **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.
-
💸 1. „Плащам за скъп абонамент, но все още ме прекъсват ограничения“
+💸 1. "I pay for an expensive subscription but still get interrupted by limits"
-Разработчиците плащат $20–200/месец за Claude Pro, Codex Pro или GitHub Copilot. Дори и да плащате, квотата има таван — 5 часа използване, седмични лимити или лимити на цените на минута. По средата на сесията на кодиране, доставчикът спира да отговаря и разработчикът губи поток и производителност. +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. -**Как OmniRoute го решава:** +**How OmniRoute solves it:** -- **Smart 4-Tier Fallback** — Ако квотата за абонамент се изчерпи, автоматично пренасочва към API Key → Евтино → Безплатно с нулева ръчна намеса -- **Проследяване на квоти в реално време** — Показва потреблението на токени в реално време с обратно отброяване за нулиране (5 часа, ежедневно, седмично) -- **Поддръжка на няколко акаунта** — Множество акаунти на доставчик с автоматичен кръгов режим — когато единият свърши, превключва към следващия -- **Персонализирани комбинации** — Възможност за персонализиране на резервни вериги с 6 стратегии за балансиране (първо попълване, кръгово, P2C, произволно, най-малко използвано, оптимизирано по отношение на разходите) -- **Codex Business Quotas** — Мониторинг на квотите на работното пространство на бизнеса/екипа директно в таблото за управление +- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention +- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly) +- **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 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
-` блокове от модели като DeepSeek R1 в стандартизирани `reasoning_content`
-- **Структуриран изход за Gemini** — `json_schema` → `responseMimeType`/`responseSchema` автоматично преобразуване
-- **`stream` по подразбиране е `false`** — Подравнява се със спецификацията на OpenAI, като се избягват неочаквани SSE в SDK на Python/Rust/Go
-
-🔌 2. „Трябва да използвам няколко доставчика, но всеки има различен API“
+🔌 2. "I need to use multiple providers but each has a different API"
-OpenAI използва един формат, Claude (Anthropic) използва друг, Gemini още един. Ако разработчикът иска да тества модели от различни доставчици или резервен вариант между тях, той трябва да преконфигурира SDK, да промени крайните точки, да се справи с несъвместими формати. Персонализираните доставчици (FriendLI, NIM) имат крайни точки на нестандартен модел. +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. -**Как OmniRoute го решава:** +**How OmniRoute solves it:** -- **Unified Endpoint** — Единичен `http://localhost:20128/v1` служи като прокси за всички 36+ доставчици -- **Превод на формат** — Автоматично и прозрачно: OpenAI ↔ Claude ↔ Gemini ↔ Responses API -- **Response Sanitization** — Премахва нестандартните полета (`x_groq`, `usage_breakdown`, `service_tier`), които нарушават OpenAI SDK v1.83+ -- **Нормализиране на ролята** — Преобразува `developer` → `system` за доставчици, които не са OpenAI; `system` → `user` за GLM/ERNIE -- **Think Tag Extraction** — Извлича `
-` 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
🌐 3. „Моят доставчик на AI блокира моя регион/държава“
- -Доставчици като OpenAI/Codex блокират достъпа от определени географски региони. Потребителите получават грешки като `unsupported_country_region_territory` по време на OAuth и API връзки. Това е особено разочароващо за разработчиците от развиващите се страни. - -**Как OmniRoute го решава:** - -- **3-Level Proxy Config** — Конфигурируем прокси на 3 нива: глобално (цял трафик), на доставчик (само един доставчик) и на връзка/ключ -- **Цветно кодирани прокси значки** — Визуални индикатори: 🟢 глобален прокси, 🟡 прокси на доставчик, 🔵 прокси за връзка, винаги показващ IP -- **OAuth Token Exchange Through Proxy** — OAuth потокът също минава през проксито, решавайки `unsupported_country_region_territory` -- **Тестове за връзка чрез прокси** — Тестовете за връзка използват конфигурирания прокси (без повече директен байпас) -- **SOCKS5 Support** — Пълна SOCKS5 прокси поддръжка за изходящо маршрутизиране -- **TLS Fingerprint Spoofing** — подобен на браузър TLS пръстов отпечатък чрез `wreq-js` за заобикаляне на откриването на ботове +- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 67+ 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 `
-
+
+🆓 4. „Искам да използвам AI за кодиране, но нямам пари“
+🌐 3. "My AI provider blocks my region/country"
-Не всеки може да плаща $20-200/месец за абонаменти за AI. Студенти, разработчици от развиващи се страни, любители и фрийлансъри се нуждаят от достъп до качествени модели на нулева цена. +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. -**Как OmniRoute го решава:** +**How OmniRoute solves it:** -- **Вградени доставчици на безплатни нива** — Вградена поддръжка за 100% безплатни доставчици: iFlow (8 неограничени модела), Qwen (3 неограничени модела), Kiro (Claude безплатно), Gemini CLI (180K/месец безплатно) +- **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 + +
+` prefix
-- **Безплатни само комбинации** — Верига `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/месец с нулев престой
-- **NVIDIA NIM безплатни кредити** — интегрирани 1000 безплатни кредита
-- **Стратегия за оптимизиране на разходите** — Стратегия за маршрутизиране, която автоматично избира най-евтиния наличен доставчик
+- **Free-Only Combos** — Chain `gc/gemini-3-flash → 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
🆓 4. "I want to use AI for coding but I have no money"
+ +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. + +**How OmniRoute solves it:** + +- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free) - **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/
-
🔒 5. „Трябва да защитя моя AI шлюз от неоторизиран достъп“
+🔒 5. "I need to protect my AI gateway from unauthorized access"
-При излагане на AI шлюз към мрежата (LAN, VPS, Docker), всеки с адреса може да използва токените/квотата на разработчика. Без защита приложните програмни интерфейси (API) са уязвими за злоупотреба, незабавно инжектиране и злоупотреба. +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. -**Как OmniRoute го решава:** +**How OmniRoute solves it:** -- **API Key Management** — Генериране, ротация и обхват за всеки доставчик със специална страница `/dashboard/api-manager` -- **Разрешения на ниво модел** — Ограничете API ключовете до конкретни модели (`openai/*`, шаблони със заместващи символи), с превключвател Разрешаване на всички/Ограничаване -- **API Endpoint Protection** — Изискване на ключ за `/v1/models` и блокиране на определени доставчици от списъка -- **Auth Guard + CSRF Protection** — Всички маршрути на таблото са защитени с `withAuth` мидълуер + CSRF токени -- **Ограничител на скоростта** — Ограничаване на скоростта на IP с конфигурируеми прозорци -- **IP Filtering** — Списък с разрешени/списък с блокирани за контрол на достъпа -- **Prompt Injection Guard** — Дезинфекция срещу злонамерени бързи модели -- **AES-256-GCM криптиране** — Идентификационните данни са криптирани в покой +- **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. „Доставчикът ми се срина и загубих потока на кодиране“
Доставчиците на AI могат да станат нестабилни, да върнат грешки 5xx или да достигнат временни лимити на скоростта. Ако разработчикът зависи от един доставчик, той е прекъснат. Без прекъсвачи многократните повторни опити могат да сринат приложението. +🛑 6. "My provider went down and I lost my coding flow"
-**Как OmniRoute го решава:** +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. -- **Прекъсвач за всеки доставчик** — Автоматично отваряне/затваряне с конфигурируеми прагове и изчакване (затворено/отворено/полуотворено) -- **Exponential Backoff** — Прогресивни забавяния при повторен опит -- **Anti-Thundering Herd** — Mutex + семафорна защита срещу едновременни повторни бури -- **Combo Fallback Chains** — Ако основният доставчик се провали, автоматично преминава през веригата без намеса -- **Combo Circuit Breaker** — Автоматично деактивира неизправните доставчици в рамките на комбинирана верига - | 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format | -- **Health Dashboard** — Мониторинг на времето на работа, състояния на прекъсвачи, блокировки, статистика на кеша, латентност на p50/p95/p99 +**How OmniRoute solves it:** + +- **Circuit Breaker per-model** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks +- **Exponential Backoff** — Progressive retry delays +- **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 +- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain +- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
-
🔧 7. „Конфигурирането на всеки AI инструмент е досадно и повтарящо се“
+🔧 7. "Configuring each AI tool is tedious and repetitive"
-Разработчиците използват Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Всеки инструмент се нуждае от различна конфигурация (крайна точка на API, ключ, модел). Преконфигурирането при смяна на доставчик или модел е загуба на време. +Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time. -**Как OmniRoute го решава:** +**How OmniRoute solves it:** -- **CLI Tools Dashboard** — Специална страница с настройка с едно кликване за Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline -- **GitHub Copilot Config Generator** — Генерира `chatLanguageModels.json` за VS код с групов избор на модел -- **Onboarding Wizard** — Насочвана настройка в 4 стъпки за потребители за първи път -- **Една крайна точка, всички модели** — Конфигурирайте `http://localhost:20128/v1` веднъж, достъп до 36+ доставчици +- **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 67+ providers
-
🔑 8. „Управлението на OAuth токени от множество доставчици е ад“
+🔑 8. "Managing OAuth tokens from multiple providers is hell"
-Claude Code, Codex, Gemini CLI, Copilot — всички използват OAuth 2.0 с изтичащи токени. Разработчиците трябва постоянно да се удостоверяват повторно, да се справят с `client_secret is missing`, `redirect_uri_mismatch` и повреди на отдалечени сървъри. OAuth на LAN/VPS е особено проблематичен. +Claude Code, Codex, Gemini CLI, 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. -**Как OmniRoute го решава:** +**How OmniRoute solves it:** -- **Auto Token Refresh** — OAuth токените се опресняват във фонов режим преди изтичане -- **OAuth 2.0 (PKCE) Вграден** — Автоматичен поток за Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow -- **Multi-Account OAuth** — Множество акаунти на доставчик чрез JWT/ID извличане на токени -- **OAuth LAN/Remote Fix** — Частно IP откриване за `redirect_uri` + ръчен URL режим за отдалечени сървъри -- **OAuth зад Nginx** — Използва `window.location.origin` за обратна прокси съвместимост -- **Отдалечено ръководство за OAuth** — Ръководство стъпка по стъпка за идентификационни данни на Google Cloud на VPS/Docker +- **Auto Token Refresh** — OAuth tokens refresh in background before expiration +- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow +- **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. „Не знам колко харча или къде“
+📊 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. -**Как OmniRoute го решава:** +**How OmniRoute solves it:** -- **Табло за анализ на разходите** — Проследяване на разходите за токени и управление на бюджета за доставчик -- **Бюджетни ограничения за ниво** — Таван на разходите за ниво, което задейства автоматично резервно връщане -- **Конфигурация на ценообразуване за модел** — Конфигурируеми цени за модел- **Статистика на използването на API ключ** — Брой заявки и последно използвано клеймо за всеки ключ -- **Табло за управление на анализи** — Статистически карти, диаграма на използването на модела, таблица на доставчика с проценти на успех и закъснение +- **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. „Не мога да диагностицирам грешки и проблеми в AI повиквания“
+🐛 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. -**Как OmniRoute го решава:** +**How OmniRoute solves it:** -- **Табло за управление на унифицирани регистрационни файлове** — 4 раздела: регистрационни файлове за заявки, регистрационни файлове за прокси, регистрационни файлове за одит, конзола -- **Console Log Viewer** — Преглед в стил терминал в реално време с цветно кодирани нива, автоматично превъртане, търсене, филтър -- **SQLite Proxy Logs** — Постоянни регистрационни файлове, които оцеляват при рестартиране на сървъра -- **Translator Playground** — 4 режима за отстраняване на грешки: Playground (превод на формат), Chat Tester (обиколно пътуване), Test Bench (партида), Live Monitor (в реално време) -- **Заявка за телеметрия** — p50/p95/p99 латентност + проследяване на X-Request-Id -- **Регистриране на базата на файлове с ротация** — Прехващачът на конзолата улавя всичко в JSON журнал с ротация, базирана на размера +- **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 Proxy Logs** — Persistent logs that survive server restarts +- **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 Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation +- **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. „Внедряването и поддържането на шлюза е сложно“
+🏗️ 11. "Deploying and maintaining the gateway is complex"
-Инсталирането, конфигурирането и поддържането на AI прокси в различни среди (локални, VPS, Docker, облак) е трудоемко. Проблеми като твърдо кодирани пътища, `EACCES` в директории, конфликти на портове и междуплатформени компилации добавят триене. +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. -**Как OmniRoute го решава:** +**How OmniRoute solves it:** -- **глобално инсталиране на npm** — `npm install -g omniroute && omniroute` — готово -- **Docker Multi-Platform** — роден AMD64 + ARM64 (Apple Silicon, AWS Graviton, Raspberry Pi) -- **Docker Compose Profiles** — `base` (без CLI инструменти) и `cli` (с Claude Code, Codex, OpenClaw) -- **Electron Desktop App** — родно приложение за Windows/macOS/Linux със системна област, автоматично стартиране, офлайн режим -- **Split-Port Mode** — API и табло за управление на отделни портове за разширени сценарии (обратен прокси, контейнерна мрежа) -- **Cloud Sync** — Конфигуриране на синхронизиране между устройства чрез Cloudflare Workers -- **DB Backups** — Автоматично архивиране, възстановяване, експортиране и импортиране на всички настройки +- **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
-
-
-🌍 12. „Интерфейсът е само на английски и екипът ми не говори английски“
+🌍 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. -**Как OmniRoute го решава:** +**How OmniRoute solves it:** -- **Dashboard i18n — 30 езика** — Преведени всички 500+ клавиша, включително арабски, български, датски, немски, испански, фински, френски, иврит, хинди, унгарски, индонезийски, италиански, японски, корейски, малайски, холандски, норвежки, полски, португалски (PT/BR), румънски, руски, словашки, шведски, тайландски, украински, виетнамски, китайски, филипински, английски -- **RTL Support** — Поддръжка отдясно наляво за арабски и иврит -- **Многоезични READMEs** — 30 пълни превода на документация -- **Избор на език** — Икона на глобус в заглавката за превключване в реално време
-
🔄 13. „Имам нужда от повече от чат — имам нужда от вграждания, изображения, аудио“
- -AI не е просто завършване на чат. Разработчиците трябва да генерират изображения, да транскрибират аудио, да създават вграждания за RAG, да прекласират документи и да модерират съдържание. Всеки API има различна крайна точка и формат. - -**Как OmniRoute го решава:** - -- **Вграждания** — `/v1/embeddings` с 6 доставчика и 9+ модела -- **Генериране на изображения** — `/v1/images/generations` с 10 доставчика и 20+ модела (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI) -- **Текст към видео** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) и SD WebUI -- **Текст към музика** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen) -- **Аудио транскрипция** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3 -- **Текст-към-говор** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, Inworld, Cartesia, PlayHT, + съществуващи доставчици -- **Модерации** — `/v1/moderations` — Проверки за безопасност на съдържанието -- **Прекласиране** — `/v1/rerank` — Прекласиране на уместността на документа -- **API за отговори** — Пълна `/v1/responses` поддръжка за Codex +- **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
-
🧪 14. „Нямам начин да тествам и сравнявам качеството между моделите“
+🔄 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. -**Как OmniRoute го решава:** +**How OmniRoute solves it:** -- **Оценки на LLM** — Тестване със златен комплект с 10 предварително заредени случая, обхващащи поздрави, математика, география, генериране на код, съответствие с JSON, превод, маркдаун, отказ за безопасност -- **4 стратегии за съвпадение** — `exact`, `contains`, `regex`, `custom` (JS функция) -- **Translator Playground Test Bench** — Пакетно тестване с множество входове и очаквани изходи, сравнение между доставчици -- **Chat Tester** — Пълно двупосочно пътуване с визуално изобразяване на отговора -- **Монитор на живо** — Поток в реално време на всички заявки, преминаващи през проксито +- **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
-
📈 15. „Трябва да мащабирам, без да губя производителност“
+🧪 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. -**Как OmniRoute го решава:** +**How OmniRoute solves it:** -- **Семантичен кеш** — Двуслоен кеш (подпис + семантичен) намалява разходите и забавянето -- **Request Idempotency** — 5s прозорец за дедупликация за идентични заявки -- **Rate Limit Detection** — RPM на доставчик, минимална разлика и максимално едновременно проследяване -- **Редактируеми ограничения на скоростта** — Конфигурируеми настройки по подразбиране в Настройки → Устойчивост с постоянство -- **API Key Validation Cache** — 3-степенен кеш за производствена производителност -- **Здравно табло с телеметрия** — p50/p95/p99 латентност, статистика на кеша, ъптайм +- **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
-
🤖 16. „Искам да контролирам поведението на модела глобално“
Разработчици, които искат всички отговори на конкретен език, със специфичен тон или искат да ограничат токените за мотивиране. Конфигурирането на това във всеки инструмент/заявка е непрактично. +📈 15. "I need to scale without losing performance"
-**Как OmniRoute го решава:** +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. -- **Инжектиране на системна подкана** — Глобална подкана, приложена към всички заявки -- **Thinking Budget Validation** — Разсъждаващ контрол на разпределението на токени за всяка заявка (преминаване, автоматично, персонализирано, адаптивно) -- **6 стратегии за маршрутизиране** — Глобални стратегии, които определят как се разпределят заявките -- **Wildcard Router** — моделите `provider/*` маршрутизират динамично към всеки доставчик -- **Combo Enable/Disable Toggle** — Превключвайте комбинации директно от таблото за управление -- **Превключване на доставчика** — Активирайте/деактивирайте всички връзки за доставчик с едно щракване -- **Блокирани доставчици** — Изключете определени доставчици от списъка `/v1/models` +**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 +- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence +- **API Key Validation Cache** — 3-tier cache for production performance +- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
-
🧰 17. „Имам нужда от MCP инструменти като първокласни продуктови възможности“
+🤖 16. "I want to control model behavior globally"
-Много AI шлюзове разкриват MCP само като скрит детайл за изпълнение. Екипите се нуждаят от видим, управляем оперативен слой. +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. -**Как OmniRoute го решава:** +**How OmniRoute solves it:** -- MCP се появява в раздела за навигация на таблото за управление и протокол на крайна точка -- Специализирана страница за управление на MCP с процес, инструменти, обхвати и одит -- Вграден бърз старт за `omniroute --mcp` и включване на клиента +- **System Prompt Injection** — Global prompt applied to all requests +- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive) +- **6 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 +- **Provider Toggle** — Enable/disable all connections for a provider with one click +- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
-
🧠 18. „Имам нужда от A2A оркестрация със синхронизиране + пътеки на задачи за поток“
+🧰 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. -**Как OmniRoute го решава:** +**How OmniRoute solves it:** -- A2A JSON-RPC крайна точка (`POST /a2a`) с `message/send` и `message/stream` -- SSE поточно предаване с разпространение на състоянието на терминала -- API на жизнения цикъл на задачата за `tasks/get` и `tasks/cancel` +- 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
-
🛰️ 19. „Имам нужда от реално състояние на MCP процес, а не от познат статус“
+🧠 18. "I need A2A orchestration with sync + stream task paths"
-Оперативните екипи трябва да знаят дали MCP действително е жив, а не само дали API е достъпен. +Agent workflows need both direct replies and long-running streamed execution with lifecycle control. -**Как OmniRoute го решава:** +**How OmniRoute solves it:** -- Сърдечен файл по време на изпълнение с PID, времеви отпечатъци, транспорт, брой инструменти и режим на обхват -- API за състояние на MCP, комбиниращ сърдечен ритъм + скорошна активност -- Карти за състояние на потребителския интерфейс за свежест на процеса/време на работа/пулс +- 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`
-
📋 20. „Имам нужда от изпълнение на MCP инструмент с възможност за проверка“
+🛰️ 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. -**Как OmniRoute го решава:** +**How OmniRoute solves it:** -- Поддържано от SQLite одитно регистриране за извиквания на MCP инструмент -- Филтрира по инструмент, успех/неуспех, API ключ и пагинация -- Таблица за одит на таблото + статистически крайни точки за автоматизация +- 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
-
-
-🔐 21. „Имам нужда от MCP разрешения с обхват за интеграция“
+📋 20. "I need auditable MCP tool execution"
-Различните клиенти трябва да имат най-малко привилегирован достъп до категории инструменти. +When tools mutate config or trigger ops actions, teams need forensic traceability. -**Как OmniRoute го решава:** +**How OmniRoute solves it:** -- 9 гранулирани MCP обхвата за контролиран достъп до инструмента -- Налагане на обхват и видимост в потребителския интерфейс за управление на MCP -- Безопасна поза по подразбиране за оперативни инструменти - -⚙️ 22. „Имам нужда от оперативни контроли без повторно разполагане“
- -Екипите се нуждаят от бързи промени във времето на изпълнение по време на инциденти или разходни събития. - -**Как OmniRoute го решава:** - -- Превключете комбо активирането директно от таблото за управление на MCP -- Прилагайте профили на устойчивост от предварително дефинирани пакети с правила -- Нулирайте състоянието на прекъсвача от същия операционен панел +- SQLite-backed audit logging for MCP tool calls +- Filters by tool, success/failure, API key, and pagination +- Dashboard audit table + stats endpoints for automation
-
🔄 23. „Имам нужда от видимост и анулиране на жизнения цикъл на задачите A2A на живо“
+🔐 21. "I need scoped MCP permissions per integration"
-Без видимост на жизнения цикъл инцидентите със задачи стават трудни за сортиране. +Different clients should have least-privilege access to tool categories. -**Как OmniRoute го решава:** +**How OmniRoute solves it:** -- Списък със задачи/филтриране по състояние/умение с пагинация -- Разбивка на метаданни, събития и артефакти на задачи -- Крайна точка за анулиране на задача и действие на потребителския интерфейс с потвърждение +- 9 granular MCP scopes for controlled tool access +- Scope enforcement and visibility in MCP management UI +- Safe default posture for operational tooling
-
🌊 24. „Имам нужда от показатели за активен поток за A2A натоварване“
+⚙️ 22. "I need operational controls without redeploying"
-Поточните работни потоци изискват оперативно вникване в паралелността и живите връзки. +Teams need quick runtime changes during incidents or cost events. -**Как OmniRoute го решава:** +**How OmniRoute solves it:** -- Броячи на активни потоци, интегрирани в статуса A2A -- Времево клеймо на последната задача и брой на състоянието -- A2A карти на таблото за наблюдение на операциите в реално време +- Switch combo activation directly from MCP dashboard +- Apply resilience profiles from pre-defined policy packs +- Reset circuit breaker state from the same operations panel
-
🪪 25. „Имам нужда от стандартно откриване на агент за клиенти“
+🔄 23. "I need live A2A task lifecycle visibility and cancellation"
-Външните клиенти и оркестраторите се нуждаят от машинночетими метаданни за включване. +Without lifecycle visibility, task incidents become hard to triage. -**Как OmniRoute го решава:** +**How OmniRoute solves it:** -- Карта на агент, изложена на `/.well-known/agent.json` -- Възможности и умения, показани в потребителския интерфейс за управление -- API за състояние A2A включва метаданни за откриване за автоматизация +- Task listing/filtering by state/skill with pagination +- Drill-down on task metadata, events, and artifacts +- Task cancellation endpoint and UI action with confirmation
-
🧭 26. „Имам нужда от откриваемост на протокола в UX на продукта“
+🌊 24. "I need active stream metrics for A2A load"
-Ако потребителите не могат да открият повърхности на протокола, качеството на приемане и поддръжка пада. +Streaming workflows require operational insight into concurrency and live connections. -**Как OmniRoute го решава:** +**How OmniRoute solves it:** -- Записи в страничната лента за MCP и A2A -- Страница с крайна точка Раздел Протоколи с бърз старт и състояние -- Връзки от преглед към специални табла за управление +- Active stream counters integrated into A2A status +- Last task timestamp and per-state counts +- A2A dashboard cards for real-time ops monitoring
-
🧪 27. „Имам нужда от валидиране на протокол от край до край с реални клиенти“
+🪪 25. "I need standard agent discovery for clients"
-Фалшивите тестове не са достатъчни за валидиране на съвместимостта на протокола преди пускане. +External clients and orchestrators need machine-readable metadata for onboarding. -**Как OmniRoute го решава:** +**How OmniRoute solves it:** -- E2E пакет, който зарежда приложение и използва реален MCP SDK клиентски транспорт -- Клиент A2A тества за потоци откриване, изпращане, поточно предаване, получаване и отмяна -- Кръстосана проверка на твърдения срещу MCP одит и API на A2A задачи +- Agent Card exposed at `/.well-known/agent.json` +- Capabilities and skills shown in management UI +- A2A status API includes discovery metadata for automation
-
📡 28. „Имам нужда от унифицирана наблюдаемост във всички интерфейси“
+🧭 26. "I need protocol discoverability in the product UX"
-Разделянето на наблюдаемостта по протокол създава слепи зони и по-дълъг MTTR. +If users cannot discover protocol surfaces, adoption and support quality drop. -**Как OmniRoute го решава:** +**How OmniRoute solves it:** -- Унифицирани табла за управление/логове/аналитика в един продукт -- Здраве + одит + заявка за телеметрия в OpenAI, MCP и A2A слоеве -- Оперативни API за статус и автоматизация +- 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
-
💼 29. „Имам нужда от едно време за изпълнение за прокси + инструменти + оркестрация на агенти“
+🧪 27. "I need end-to-end protocol validation with real clients"
-Изпълнението на много отделни услуги увеличава оперативните разходи и режимите на отказ. +Mock tests are not enough to validate protocol compatibility before release. -**Как OmniRoute го решава:**- OpenAI-съвместим прокси, MCP сървър и A2A сървър в един стек +**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
-
-### Примерни книги за игри (интегрирани случаи на употреба)
+🚀 30. „Трябва да изпратя агентски работни потоци без разрастване на лепен код“
+📡 28. "I need unified observability across all interfaces"
-Екипите губят скорост, когато свързват множество ad-hoc услуги и скриптове. +Splitting observability by protocol creates blind spots and longer MTTR. -**Как OmniRoute го решава:** +**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"
-**Playbook A: Увеличете максимално платения абонамент + евтино архивиране** +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 + +
+
+
+### Example Playbooks (Integrated Use Cases)
+
+**Playbook A: Maximize paid subscription + cheap backup**
```txt
Combo: "maximize-claude"
@@ -625,7 +694,7 @@ Monthly cost: $20 + small backup spend
Outcome: higher quality, near-zero interruption
```
-**Playbook B: Стек за кодиране с нулеви разходи**
+**Playbook B: Zero-cost coding stack**
```txt
Combo: "free-forever"
@@ -637,7 +706,7 @@ Monthly cost: $0
Outcome: stable free coding workflow
```
-**Playbook C: 24/7 винаги включена резервна верига**
+**Playbook C: 24/7 always-on fallback chain**
```txt
Combo: "always-on"
@@ -650,37 +719,61 @@ Combo: "always-on"
Outcome: deep fallback depth for deadline-critical workloads
```
-**Playbook D: Операции на агент с MCP + A2A**
+**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/mcp and /dashboard/a2a
-4) Control incidents with resilience profile + task cancellation
+3) Observe via /dashboard/endpoint (MCP and A2A tabs)
+4) Toggle services via inline status controls
```
---
-## ⚡ Бърз старт
+## 🆓 Start Free — Zero Configuration Cost
-### 1) Инсталирайте и стартирайте
+> 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 **iFlow** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |
+| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |
+| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |
+| 5 | `/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).
+
+## Бърз старт
+
+### 1) Install and run
```bash
npm install -g omniroute
omniroute
```
-Таблото за управление се отваря на `http://localhost:20128` и основният URL адрес на API е `http://localhost:20128/v1`.
+> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:
+>
+> ```bash
+> pnpm install -g omniroute
+> pnpm approve-builds -g # Select all packages → approve
+> omniroute
+> ```
-| Команда | Описание |
-| ----------------------- | ---------------------------------------------------------------------------- |
-| `omniroute` | Стартиране на сървър (`PORT=20128`, API и табло за управление на същия порт) |
-| `omniroute --port 3000` | Задайте каноничен/API порт на 3000 |
-| `omniroute --mcp` | Стартирайте MCP сървър (stdio транспорт) |
-| `omniroute --no-open` | Без автоматично отваряне на браузъра |
-| `omniroute --help` | Показване на помощ |
+Dashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.
-Допълнителен режим на разделен порт:
+| 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
@@ -688,13 +781,13 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
# Dashboard: http://localhost:20129
```
-### 2) Свържете доставчици и създайте своя API ключ
+### 2) Connect providers and create your API key
-1. Отворете таблото за управление → `Providers` и свържете поне един доставчик (OAuth или API ключ).
-2. Отворете таблото за управление → `Endpoint` и създайте API ключ.
-3. (По избор) Отворете таблото за управление → `Combos` и задайте вашата резервна верига.
+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) Насочете вашия инструмент за кодиране към OmniRoute
+### 3) Point your coding tool to OmniRoute
```txt
Base URL: http://localhost:20128/v1
@@ -702,22 +795,22 @@ API Key: [copy from Endpoint page]
Model: if/kimi-k2-thinking (or any provider/model prefix)
```
-Работи с Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode и OpenAI-съвместими SDK.
+Works with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.
-### 4) Активиране и валидиране на протоколи (v2.0)
+### 4) Enable and validate protocols (v2.0)
-**MCP (за операции, управлявани от инструмент):**
+**MCP (for tool-driven operations):**
```bash
omniroute --mcp
```
-След това свържете вашия MCP клиент през `stdio` и тествайте инструменти като:
+Then connect your MCP client over `stdio` and test tools like:
- `omniroute_get_health`
- `omniroute_list_combos`
-**A2A (за работни процеси от агент към агент):**
+**A2A (for agent-to-agent workflows):**
```bash
curl http://localhost:20128/.well-known/agent.json
@@ -729,15 +822,15 @@ curl -X POST http://localhost:20128/a2a \
-d '{"jsonrpc":"2.0","id":"quickstart","method":"message/send","params":{"skill":"quota-management","messages":[{"role":"user","content":"Give me a short quota summary."}]}}'
```
-### 5) Валидирайте всичко от край до край (препоръчително)
+### 5) Validate everything end-to-end (recommended)
```bash
npm run test:protocols:e2e
```
-Този пакет валидира реални MCP и A2A клиентски потоци срещу работещо приложение.
+This suite validates real MCP and A2A client flows against a running app.
-### Алтернатива: стартирайте от източника
+### Alternative: run from source
```bash
cp .env.example .env
@@ -747,11 +840,11 @@ PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm
---
-## 🐳 Докер
+## 🐳 Docker
-OmniRoute се предлага като публично изображение на Docker в [Docker Hub] (https://hub.docker.com/r/diegosouzapw/omniroute).
+OmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
-**Бързо бягане:**
+**Quick run:**
```bash
docker run -d \
@@ -762,7 +855,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**С файл на средата:**
+**With environment file:**
```bash
# Copy and edit .env first
@@ -777,7 +870,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Използване на Docker Compose:**
+**Using Docker Compose:**
```bash
# Base profile (no CLI tools)
@@ -787,22 +880,61 @@ docker compose --profile base up -d
docker compose --profile cli up -d
```
-| Изображение | Етикет | Размер | Описание |
-| ------------------------ | -------- | ------ | -------------------------- |
-| `diegosouzapw/omniroute` | `latest` | ~250MB | Най-новата стабилна версия |
-| `diegosouzapw/omniroute` | `1.0.3` | ~250MB | Текуща версия |
+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.
+- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.
+- 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` | `1.0.3` | ~250MB | Current version |
---
-## 🖥️
+## 🖥️ Desktop App — Offline & Always-On
-Стартирайте OmniRoute като самостоятелно настолно приложение — без терминал, без браузър, без интернет, необходим за локалните модели. Базираното на Electron приложение включва:
+> 🆕 **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.
-- 🖥️ **Собствен прозорец** — Специален прозорец на приложението с интеграция в системната област
-- 🔄 **Автоматично стартиране** — Стартирайте OmniRoute при влизане в системата
-- 🔔 **Нативни известия** — Получавайте сигнали за изчерпване на квотата или проблеми с доставчика
-- ⚡ **Инсталиране с едно щракване** — NSIS (Windows), DMG (macOS), AppImage (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
### Бърз старт
@@ -817,136 +949,348 @@ npm run electron:build:mac # macOS (.dmg) — x64 & arm64
npm run electron:build:linux # Linux (.AppImage)
```
-### Системна област
+### System Tray
-Когато е минимизиран, OmniRoute живее в системната област с бързи действия:
+When minimized, OmniRoute lives in your system tray with quick actions:
-- Отворете таблото
-- Промяна на сървърния порт
-- Излезте от приложението
+- Open dashboard
+- Change server port
+- Quit application
-📖 Пълна документация: [`electron/README.md`](electron/README.md)
+📖 Full documentation: [`electron/README.md`](electron/README.md)
---
-## 💰 Ценообразуването с един поглед
+## 💰 Pricing at a Glance
-| Ниво | Доставчик | Цена | Нулиране на квота | Най-добро за |
-| ------------------ | ----------------- | ---------------------------- | ----------------------- | ------------------------- |
-| **💳 АБОНАМЕНТ** | Claude Code (Pro) | $20/месец | 5 часа + седмично | Вече сте абонирани |
-| | Codex (Plus/Pro) | $20-200/месец | 5 часа + седмично | Потребители на OpenAI |
-| | Gemini CLI | **БЕЗПЛАТНО** | 180K/месец + 1K/ден | всички! |
-| | Копилот на GitHub | $10-19/месец | Месечно | Потребители на GitHub |
-| **🔑 КЛЮЧ ЗА API** | NVIDIA NIM | **БЕЗПЛАТНО** (1000 кредита) | Еднократно | Безплатно ниво тестване |
-| | DeepSeek | Плащане при използване | Няма | Най-добра цена/качество |
-| | Groq | Безплатно ниво + платено | Ограничена скорост | Свръхбърз извод |
-| | xAI (Grok) | Плащане при използване | Няма | Grok модели |
-| | Мистрал | Безплатно ниво + платено | Ограничена скорост | Европейски AI |
-| | OpenRouter | Плащане при използване | Няма | 100+ модела |
-| **💰 ЕВТИНО** | GLM-4.7 | $0,6/1 милион | Ежедневно 10 сутринта | Резервно копие на бюджета |
-| | MiniMax M2.1 | $0,2/1 милион | 5-часово търкаляне | Най-евтиният вариант |
-| | Кими К2 | $9/месец апартамент | 10 милиона токена/месец | Предвидими разходи |
-| **🆓 БЕЗПЛАТНО** | iFlow | $0 | Неограничен | 8 модела безплатно |
-| | Куен | $0 | Неограничен | 3 модела безплатно |
-| | Киро | $0 | Неограничен | Клод безплатно |
+| 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 |
+| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |
+| | 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** | iFlow | **$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 |
-**💡 Професионален съвет:** Започнете с Gemini CLI (180K безплатно/месец) + iFlow (неограничено безплатно) комбинация = $0 цена!
+> 🆕 **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
+iFlow (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.
---
-## 💡 Основни характеристики
+---
-OmniRoute v2.0 е създаден като операционна платформа, а не просто релейно прокси.
+## 🆓 Free Models — What You Actually Get
-### 🤖 Операции на агент и протокол (v2.0)| Характеристика | Какво прави |
+> 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.
-| ------------------------------------ | -------------------------------------------------------------------------------- |
-| 🔧 **MCP сървър (16 инструмента)** | Инструментите за IDE/агент контролират маршрутизиране, здраве, комбинации, ограничения и операции | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`)
-| 🤝 **A2A сървър (JSON-RPC + SSE)** | Изпълнение на задачи от агент към агент със синхронизиране и поточно предаване |
-| 🧭 **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** | Реално състояние на процеса (pid, време на работа, възраст на сърдечния ритъм, транспорт, режим на обхвата) |
-| 📋 **MCP одитна пътека** | Филтрируеми журнали за одит с успех/неуспех и ключово приписване |
-| 🔐 **Прилагане на обхват на MCP** | 9 подробни разрешения за обхват за контролиран достъп до инструменти |
-| 📡 **A2A Управление на жизнения цикъл на задачите** | Списък/филтриране на задачи, проверка на събития/артефакти, отмяна на изпълнявани задачи |
-| 📋 **Откриване на карта на агент** | `/.well-known/agent.json` за автоматично откриване на клиент |
-| 🧪 **Протокол E2E Тестова система** | Истински MCP SDK + A2A клиентски потоци в `test:protocols:e2e` |
-| ⚙️ **Оперативни контроли** | Превключете комбо, приложете профили на устойчивост, нулирайте прекъсвачите от една контролна повърхност |
+### 🔵 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 |
-| Характеристика | Какво прави |
-| ----------------------------------------------- | ---------------------------------------------------------------------------- |
-| 🎯 **Интелигентен 4-степенен резервен вариант** | Автоматичен маршрут: Абонамент → API ключ → Евтини → Безплатно |
-| 📊 **Проследяване на квоти в реално време** | Брой токени на живо + нулиране на обратното броене на доставчик |
-| 🔄 **Форматиране на превода** | OpenAI ↔ Claude ↔ Gemini ↔ Отговори с безопасни за схема преобразувания |
-| 👥 **Поддръжка за множество акаунти** | Няколко акаунта на доставчик с интелигентен избор |
-| 🔄 **Автоматично опресняване на токени** | OAuth токените се опресняват автоматично с повторен опит |
-| 🎨 **Персонализирани комбинации** | 6 стратегии за балансиране + резервен контрол на веригата |
-| 🌐 **Wildcard Router** | `provider/*` динамично маршрутизиране |
-| 🧠 **Мислене за контрол на бюджета** | Лимити за преминаване, автоматични, персонализирани и адаптивни разсъждения |
-| 🔀 **Псевдоними на модели** | Вграден + персонализиран псевдоним на модела и безопасност на миграцията |
-| ⚡ **Влошаване на фона** | Насочване на фонови задачи с нисък приоритет към по-евтини модели |
-| 💬 **Системно бързо инжектиране** | Глобални контроли на поведението, прилагани последователно |
-| 📄 **Съвместимост с API за отговори** | Пълна `/v1/responses` поддръжка за Codex и разширени агентни работни процеси |
+### 🟢 IFLOW MODELS (Free OAuth — No Credit Card)
-### 🎵 Мултимодални API
+| 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 |
-| Характеристика | Какво прави || -------------------------- | ------------------------------------------------------------ |
-| 🖼️ **Генериране на изображения** | `/v1/images/generations` с облак и локален бекенд |
-| 📐 **Вграждания** | `/v1/embeddings` за търсене и RAG тръбопроводи |
-| 🎤 **Аудио транскрипция** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |
-| 🔊 **Текст към говор** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) |
-| 🎬 **Видео генериране** | `/v1/videos/generations` (работни процеси ComfyUI + SD WebUI) |
-| 🎵 **Музикално поколение** | `/v1/music/generations` (работни процеси на ComfyUI) |
-| 🛡️ **Модерации** | `/v1/moderations` проверки за безопасност |
-| 🔀 **Прекласиране** | `/v1/rerank` за оценка на уместността |
+### 🟡 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) |
-| Характеристика | Какво прави |
-| -------------------------------------------- | -------------------------------------------------------------------------------------- |
-| 🔌 **Прекъсвачи** | Пътуване/възстановяване на ниво доставчик с прагови контроли |
-| 🛡️ **Anti-Thundering Herd** | Защита на Mutex + семафор при събития за повторен опит/скорост |
-| 🧠 **Семантичен + кеш на подписа** | Намаляване на разходите/закъснението с два кеш слоя |
-| ⚡ **Искане на идемпотентност** | Дублиран защитен прозорец |
-| 🔒 **TLS Fingerprint Spoofing** | По-добра съвместимост с доставчици, филтрирани срещу бот |
-| 🔏 **CLI Fingerprint Matching** | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP** |
-| 🌐 **IP филтриране** | Списък с разрешени/списъци с блокирани контроли за открити внедрявания |
-| 📊 **Редактируеми ограничения на скоростта** | Конфигурируеми глобални/на ниво доставчик ограничения с постоянство |
-| 🔑 **API Key Management + Scoping** | Сигурно издаване/ротация на ключове и контроли на модел/доставчик |
-| 🛡️ **Защитен `/models`** | Опционално удостоверяване и скриване на доставчик за каталог на модели |
+### 🟣 GEMINI CLI (Google OAuth)
-### 📊 Наблюдаемост и анализ
+| Model | Prefix | Limit | Rate Limit |
+| ------------------------ | ------ | --------------------------- | ------------- |
+| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |
+| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |
-| Характеристика | Какво прави |
-| ---------------------------------------------------------------- | ------------------------------------------------------------------------ |
-| 📝 **Заявка + Регистриране на прокси сървър** | Пълно регистриране на заявка/отговор и прокси |
-| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |
-| 📋 **Табло за управление на унифицирани регистрационни файлове** | Изгледи на заявка, прокси, одит и конзола на една страница |
-| 🔍 **Заявка за телеметрия** | p50/p95/p99 латентност и проследяване на заявки |
-| 🏥 **Здравно табло** | Време на работа, състояния на прекъсване, блокировки, статистика на кеша |
-| 💰 **Проследяване на разходите** | Контрол на бюджета и видимост на ценообразуването за модел |
-| 📈 **Аналитични визуализации** | Прозрения за използването на модел/доставчик и изгледи на тенденции |
-| 🧪 **Рамка за оценка** | Тестване на златен набор с конфигурируеми стратегии за мач |
+### ⚫ 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 |
-| Характеристика | Какво прави |
-| ----------------------------------------- | ------------------------------------------------------------------------- | --- | ----------------------------- | ------------------------------------------------------ |
-| 🌐 **Разполагане навсякъде** | Localhost, VPS, Docker, облачни среди | | 💾 **Синхронизиране в облак** | Синхронизиране на конфигурацията чрез облачен работник |
-| 🔄 **Архивиране/Възстановяване** | Експорт/импорт и потоци за възстановяване след бедствие |
-| 🧙 **Съветник за присъединяване** | Насочвана настройка при първо стартиране |
-| 🔧 **CLI Tools Dashboard** | Настройка с едно щракване за популярни инструменти за кодиране |
-| 🌐 **i18n (30 езика)** | Пълно табло за управление + езикова поддръжка на документи с RTL покритие |
-| 🧹 **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 |
-| 📂 **Директория с персонализирани данни** | `DATA_DIR` отмяна за място за съхранение |
+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`
-### Функция Deep Dive
+### ⚪ 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
+> iFlow (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 v2.0 is built as an operational platform, not just a relay proxy.
+
+### 🆕 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 Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |
+| 🤖 **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 (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) |
+| 🤝 **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** | 9 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 combo, apply resilience profiles, reset breakers from one control surface |
+
+### 🧠 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** | 6 balancing strategies + fallback chain control |
+| 🌐 **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) |
+| 💬 **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 |
+| ----------------------------------- | -------------------------------------------------------------------------------------- |
+| 🔌 **Circuit Breakers** | Per-model trip/recover with threshold controls |
+| 🎯 **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 |
+| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |
+| 🔑 **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 |
+
+### 📊 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 |
+| 📋 **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 |
+
+### ☁️ Deployment & Platform
+
+| Feature | What It Does |
+| ----------------------------- | --------------------------------------------------------- |
+| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |
+| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |
+| 💾 **Cloud Sync** | Configuration sync via cloud worker |
+| 🔄 **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 |
+
+### Feature Deep Dive
+
+#### Smart fallback with practical cost control
```txt
Combo: "my-coding-stack"
@@ -956,73 +1300,73 @@ Combo: "my-coding-stack"
4. if/kimi-k2-thinking
```
-Когато квотата, скоростта или здравето са неуспешни, OmniRoute автоматично преминава към следващия кандидат без ръчно превключване.
+When quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.
-#### Управление на протоколи, което е видимо и работещо
+#### Protocol management that is visible and operable
-- MCP + A2A са откриваеми в UI и документи (не са скрити)
-- API за състояние на протокола разкриват оперативни данни на живо (`/api/mcp/*`, `/api/a2a/*`)
-- Таблата за управление включват действия за операции от ден 2 (комбо превключвания, нулиране на прекъсвача, анулиране на задача)
+- 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)
-#### Преводач + работен процес за валидиране
+#### Translator + validation workflow
-Зоната за преводач включва:
+The Translator area includes:
-- **Playground**: поискайте проверки за трансформация
-- **Chat Tester**: пълна заявка/отговор двупосочно
-- **Тестова стенда**: множество случаи в едно изпълнение
-- **Монитор на живо**: изглед на трафика в реално време
+- **Playground**: request transformation checks
+- **Chat Tester**: full request/response round-trip
+- **Test Bench**: multiple cases in one run
+- **Live Monitor**: real-time traffic view
-Плюс валидиране на протокол с реални клиенти чрез `npm run test:protocols:e2e`.
+Plus protocol validation with real clients via `npm run test:protocols:e2e`.
-> 📖 **[MCP Server README](open-sse/mcp-server/README.md)** — Справка за инструмента, IDE конфигурации и примери за клиенти
+> 📖 **[MCP Server README](open-sse/mcp-server/README.md)** — Tool reference, IDE configs, and client examples
>
-> 📖 **[A2A Server README](src/lib/a2a/README.md)** — Умения, JSON-RPC методи, поточно предаване и жизнен цикъл на задачите
+> 📖 **[A2A Server README](src/lib/a2a/README.md)** — Skills, JSON-RPC methods, streaming, and task lifecycle
-## 🧪 Оценки (Evals)
+## 🧪 Evaluations (Evals)
-OmniRoute включва вградена рамка за оценка за тестване на качеството на отговора на LLM спрямо златен набор. Достъп до него чрез **Analytics → 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
-Предварително зареденият "OmniRoute Golden Set" съдържа тестови случаи за:
+The pre-loaded "OmniRoute Golden Set" contains test cases for:
-- Поздрави, математика, география, генериране на код
-- Съответствие с JSON формат, превод, генериране на маркдаун
-- Отказ за безопасност (вредно съдържание), броене, булева логика
+- Greetings, math, geography, code generation
+- JSON format compliance, translation, markdown generation
+- Safety refusal (harmful content), counting, boolean logic
-### Стратегии за оценка
+### Evaluation Strategies
-| Стратегия | Описание | Пример |
-| ---------- | ----------------------------------------------------------------------- | -------------------------------- |
-| `exact` | Изходът трябва да съвпада точно | `"4"` |
-| `contains` | Изходът трябва да съдържа подниз (без значение за малки и големи букви) | `"Paris"` |
-| `regex` | Изходът трябва да съответства на модела на регулярен израз | `"1.*2.*3"` |
-| `custom` | Персонализираната JS функция връща true/false | `(output) => output.length > 10` |
+| 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
-### Настройка на протокол (MCP + A2A)
+### Protocol Setup (MCP + A2A)
🚀 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) + +
-
-🧩 Настройка на MCP (протокол на контекста на модела)
+🧩 MCP Setup (Model Context Protocol)
-Стартирайте MCP транспорт в режим stdio: +Start MCP transport in stdio mode: ```bash omniroute --mcp ``` -Препоръчителен поток за валидиране: +Recommended validation flow: -1. Свържете вашия MCP клиент през stdio. -2. Стартирайте `omniroute_get_health`. -3. Стартирайте `omniroute_list_combos`. -4. Отворете `/dashboard/mcp`, за да потвърдите сърдечен ритъм, активност и проверка. +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. -Полезни API за автоматизация: +Useful APIs for automation: - `GET /api/mcp/status` - `GET /api/mcp/tools` @@ -1031,15 +1375,16 @@ omniroute --mcp🤝 Настройка на A2A (Agent2Agent)
+
+
🤝 A2A Setup (Agent2Agent)
-Открийте агента: +Discover the agent: ```bash curl http://localhost:20128/.well-known/agent.json ``` -Изпратете задача: +Send a task: ```bash curl -X POST http://localhost:20128/a2a \ @@ -1047,38 +1392,38 @@ curl -X POST http://localhost:20128/a2a \ -d '{"jsonrpc":"2.0","id":"setup-a2a","method":"message/send","params":{"skill":"quota-management","messages":[{"role":"user","content":"Summarize quota status."}]}}' ``` -Управление на жизнения цикъл: +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` за видимост на задача/състояние/поток и димни действия +- `/dashboard/a2a` for task/state/stream observability and smoke actions
-
🧪 Проверка на протокол от край до край
+🧪 End-to-end protocol validation
-Валидирайте и двата протокола с реални клиенти: +Validate both protocols with real clients: ```bash npm run test:protocols:e2e ``` -Това потвърждава: +This verifies: -- MCP SDK клиент за свързване/списък/обаждане -- A2A откриване/изпращане/поток/получаване/отказ -- Кръстосана проверка на данни в MCP одит и API за управление на задачи A2A +- 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) @@ -1093,7 +1438,7 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Професионален съвет:** Използвайте Opus за сложни задачи, Sonnet за скорост. OmniRoute проследява квота за модел! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! ### OpenAI Codex (Plus/Pro) @@ -1107,7 +1452,24 @@ Models: cx/gpt-5.1-codex-max ``` -### Gemini CLI (БЕЗПЛАТНО 180K/месец!) +#### 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). + +### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -1119,9 +1481,9 @@ Models: gc/gemini-2.5-pro ``` -**Най-добра стойност:** Огромно безплатно ниво! Използвайте това преди платените нива. +**Best Value:** Huge free tier! Use this before paid tiers. -### Копилот на GitHub +### GitHub Copilot ```bash Dashboard → Providers → Connect GitHub @@ -1137,103 +1499,103 @@ Models:
-
🔑 API ключови доставчици
+🔑 API Key Providers
-### NVIDIA NIM (БЕЗПЛАТНИ 1000 кредита!) +### NVIDIA NIM (FREE developer access — 70+ models) -1. Регистрирайте се: [build.nvidia.com](https://build.nvidia.com) -2. Вземете безплатен API ключ (включени 1000 кредита за изводи) -3. Табло → Добавяне на доставчик → NVIDIA NIM: - - API ключ: `nvapi-your-key` +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` -**Модели:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct` и още 50+ +**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more -**Професионален съвет:** OpenAI-съвместим API — работи безпроблемно с превода на формати на OmniRoute! +**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation! ### DeepSeek -1. Регистрирайте се: [platform.deepseek.com](https://platform.deepseek.com) -2. Вземете API ключ -3. Табло → Добавяне на доставчик → DeepSeek +1. Sign up: [platform.deepseek.com](https://platform.deepseek.com) +2. Get API key +3. Dashboard → Add Provider → DeepSeek -**Модели:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` +**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` -### Groq (налично безплатно ниво!) +### Groq (Free Tier Available!) -1. Регистрирайте се: [console.groq.com](https://console.groq.com) -2. Вземете API ключ (включено безплатно ниво) -3. Табло → Добавяне на доставчик → Groq +1. Sign up: [console.groq.com](https://console.groq.com) +2. Get API key (free tier included) +3. Dashboard → Add Provider → Groq -**Модели:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` +**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` -**Професионален съвет:** Изключително бърз извод — най-добър за кодиране в реално време! +**Pro Tip:** Ultra-fast inference — best for real-time coding! -### OpenRouter (100+ модела) +### OpenRouter (100+ Models) -1. Регистрирайте се: [openrouter.ai](https://openrouter.ai) -2. Вземете API ключ -3. Табло → Добавяне на доставчик → OpenRouter +1. Sign up: [openrouter.ai](https://openrouter.ai) +2. Get API key +3. Dashboard → Add Provider → OpenRouter -**Модели:** Достъп до 100+ модела от всички основни доставчици чрез един API ключ. +**Models:** Access 100+ models from all major providers through a single API key.
-
💰 Евтини доставчици (резервни)
+💰 Cheap Providers (Backup)
-### GLM-4.7 (Ежедневно нулиране, $0,6/1 млн.) +### GLM-4.7 (Daily reset, $0.6/1M) -1. Регистрирайте се: [Zhipu AI](https://open.bigmodel.cn/) -2. Вземете API ключ от Coding Plan -3. Табло → Добавяне на API ключ: - - Доставчик: `glm` - - API ключ: `your-key` +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` -**Използване:** `glm/glm-4.7` +**Use:** `glm/glm-4.7` -**Професионален съвет:** Планът за кодиране предлага 3× квота на цена 1/7! Нулирайте всеки ден в 10:00 ч. +**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -### MiniMax M2.1 (5 часа нулиране, $0,20/1 млн.) +### MiniMax M2.1 (5h reset, $0.20/1M) -1. Регистрирайте се: [MiniMax](https://www.minimax.io/) -2. Вземете API ключ -3. Табло → Добавяне на API ключ +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key +3. Dashboard → Add API Key -**Използване:** `minimax/MiniMax-M2.1` +**Use:** `minimax/MiniMax-M2.1` -**Професионален съвет:** Най-евтината опция за дълъг контекст (1M токени)! +**Pro Tip:** Cheapest option for long context (1M tokens)! -### Kimi K2 ($9/месец фиксиран) +### Kimi K2 ($9/month flat) -1. Абонирайте се: [Moonshot AI](https://platform.moonshot.ai/) -2. Вземете API ключ -3. Табло → Добавяне на API ключ +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key +3. Dashboard → Add API Key -**Използване:** `kimi/kimi-latest` +**Use:** `kimi/kimi-latest` -**Професионален съвет:** Фиксирани $9/месец за 10 милиона токена = $0,90/1 милион ефективна цена! +**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
-
🆓 БЕЗПЛАТНИ доставчици (Спешно архивиране)
+🆓 FREE Providers (Emergency Backup)
-### iFlow (8 БЕЗПЛАТНИ модела)```bash +### iFlow (5 FREE models via OAuth) +```bash Dashboard → Connect iFlow → iFlow OAuth login → Unlimited usage Models: -if/kimi-k2-thinking -if/qwen3-coder-plus -if/glm-4.7 -if/minimax-m2 -if/deepseek-r1 + if/kimi-k2-thinking + if/qwen3-coder-plus + if/glm-4.7 + if/minimax-m2 + if/deepseek-r1 +``` -```` - -### Qwen (3 БЕЗПЛАТНИ модела) +### Qwen (4 FREE models via Device Code) ```bash Dashboard → Connect Qwen @@ -1243,9 +1605,9 @@ Dashboard → Connect Qwen Models: qw/qwen3-coder-plus qw/qwen3-coder-flash -```` +``` -### Киро (Клод БЕЗПЛАТНО) +### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro @@ -1260,9 +1622,9 @@ Models:
-
🎨 Създаване на комбинации
+🎨 Create Combos
-### Пример 1: Увеличаване на абонамента → Евтино архивиране +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -1276,7 +1638,7 @@ Models: Use in CLI: premium-coding ``` -### Пример 2: Само безплатно (нулева цена) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -1291,9 +1653,9 @@ Cost: $0 forever!
-
---
-## 🐛 Отстраняване на неизправности
+## Отстраняване на проблеми
🔧 CLI интеграция
+🔧 CLI Integration
-### Курсор IDE +### Cursor IDE ``` Settings → Models → Advanced: @@ -1302,9 +1664,9 @@ Settings → Models → Advanced: Model: cc/claude-opus-4-6 ``` -### Клод Код +### Claude Code -Използвайте страницата **CLI Tools** в таблото за управление за конфигурация с едно кликване или редактирайте `~/.claude/settings.json` ръчно. +Use the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually. ### Codex CLI @@ -1317,13 +1679,13 @@ codex "your prompt" ### OpenClaw -**Вариант 1 — Табло (препоръчително):** +**Option 1 — Dashboard (recommended):** ``` Dashboard → CLI Tools → OpenClaw → Select Model → Apply ``` -**Опция 2 — Ръчно:** Редактиране на `~/.openclaw/openclaw.json`: +**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`: ```json { @@ -1339,9 +1701,9 @@ Dashboard → CLI Tools → OpenClaw → Select Model → Apply } ``` -> **Забележка:** OpenClaw работи само с локален OmniRoute. Използвайте `127.0.0.1` вместо `localhost`, за да избегнете проблеми с разрешаването на IPv6. +> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues. -### Cline / Продължи / RooCode +### Cline / Continue / RooCode ``` Settings → API Configuration: @@ -1353,7 +1715,7 @@ Settings → API Configuration: ### OpenCode -**Стъпка 1:** Добавете OmniRoute като персонализиран доставчик: +**Step 1:** Add OmniRoute as a custom provider: ```bash opencode @@ -1361,7 +1723,7 @@ opencode # Select "Other" → Enter ID: "omniroute" → Enter your OmniRoute API key ``` -**Стъпка 2:** Създайте/редактирайте `opencode.json` в корена на вашия проект: +**Step 2:** Create/edit `opencode.json` in your project root: ```json { @@ -1383,120 +1745,213 @@ opencode } ``` -**Стъпка 3:** Изберете модела в OpenCode: +**Step 3:** Select the model in OpenCode: ```bash /models # Select any OmniRoute model from the list ``` -> **Съвет:** Добавете всеки модел, наличен във вашата крайна точка OmniRoute `/v1/models`, към секцията `models`. Използвайте формата `provider/model-id` от таблото за управление на OmniRoute. +> **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.
-
+
+## 🛠️ Tech Stack
Щракнете, за да разширите ръководството за отстраняване на неизправности
+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** -- Изчерпване на квотата за абонамент → Резервно връщане към GLM/MiniMax -- Добавяне на комбинация: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Subscription quota out → Fallback to GLM/MiniMax +- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -**OAuth токенът е изтекъл** +**OAuth token expired** -- Автоматично опресняване от OmniRoute -- Ако проблемите продължават: Табло → Доставчик → Повторно свързване +- Auto-refreshed by OmniRoute +- If issues persist: Dashboard → Provider → Reconnect -**Високи разходи** +**High costs** -- Проверете статистическите данни за използването в Табло → Разходи -- Превключете основния модел към GLM/MiniMax -- Използвайте безплатно ниво (Gemini CLI, iFlow) за некритични задачи +- Check usage stats in Dashboard → Costs +- Switch primary model to GLM/MiniMax +- Use free tier (Gemini CLI, iFlow) for non-critical tasks -**Портовете на таблото/API са грешни** +**Dashboard/API ports are wrong** -- `PORT` е каноничният базов порт (и API порт по подразбиране) -- `API_PORT` отменя само OpenAI-съвместим API слушател -- `DASHBOARD_PORT` отменя само слушателя на таблото за управление/Next.js -- Задайте `NEXT_PUBLIC_BASE_URL` на вашето табло за управление/публичен URL (за OAuth обратни извиквания) +- `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** -- Проверете дали `BASE_URL` сочи към вашия работещ екземпляр -- Уверете се, че `CLOUD_URL` сочи към вашата очаквана крайна точка в облака -- Поддържайте стойностите на `NEXT_PUBLIC_*` в съответствие със стойностите от страна на сървъра +- 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** -- Проверете `INITIAL_PASSWORD` в `.env` -- Ако не е зададена, резервната парола е `123456` +- Check `INITIAL_PASSWORD` in `.env` +- If unset, fallback password is `123456` -**Няма регистрационни файлове за заявки** +**No request logs** -- Задайте `ENABLE_REQUEST_LOGS=true` в `.env` +- Set `ENABLE_REQUEST_LOGS=true` in `.env` -**Тестът за връзка показва „Невалидно“ за OpenAI-съвместими доставчици** +**Connection test shows "Invalid" for OpenAI-compatible providers** -- Много доставчици не излагат крайна точка `/models` -- OmniRoute v1.0.6+ включва резервно валидиране чрез завършвания на чат -- Уверете се, че основният URL адрес включва суфикс `/v1` +- 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 +### 🔐 OAuth on a Remote Server + -> **⚠️ ВАЖНО за ползване на OmniRoute em VPS/Docker/servidor remoto** +> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server** -#### OAuth +#### Why does Antigravity / Gemini CLI OAuth fail on remote servers? -Като удостоверение за OAuth не е OmniRoute estão cadastradas **apenas para `localhost`**. Ако имате достъп до OmniRoute в дистанционния сървър (напр.: `https://omniroute.meuservidor.com`), или Google rejeita a autenticação com: +The **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console. + +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 ``` -#### Решение: Конфигурирайте собствените си права за удостоверяване на OAuth +#### Solution: Configure your own OAuth credentials -Изпишете точно **OAuth 2.0 Client ID** без Google Cloud Console чрез URI на вашия сървър. +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 + +# For Gemini CLI: +GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com +GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +``` + +**6. Restart OmniRoute** + +```bash +# npm: +npm run dev + +# Docker: +docker restart omniroute +``` + +**7. Try connecting again** + +Dashboard → Providers → Antigravity (or Gemini CLI) → OAuth + +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. + +--- + +
+
---
-## 🛠️
+🇧🇷 Versão em Português
+ +#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos? + +Os provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo. + +As credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticação com: + +``` +Error 400: redirect_uri_mismatch +``` + +#### Solução: Configure suas próprias credenciais OAuth + +Você precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor. #### Passo a passo -**1. Достъп до Google Cloud Console** +**1. Acesse o Google Cloud Console** Abra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) **2. Crie um novo OAuth 2.0 Client ID** -- Кликнете върху **"+ Създаване на идентификационни данни"** → **"OAuth клиентски идентификатор"** -- Tipo de aplicativo: **"Уеб приложение"** -- Име: escolha qualquer nome (напр.: `OmniRoute Remote`) +- Clique em **"+ Create Credentials"** → **"OAuth client ID"** +- Tipo de aplicativo: **"Web application"** +- Nome: escolha qualquer nome (ex: `OmniRoute Remote`) -**3. Adicione като оторизирани URI адреси за пренасочване** +**3. Adicione as Authorized Redirect URIs** -Без поле **„Оторизирани URI адреси за пренасочване“**, добавете: +No campo **"Authorized redirect URIs"**, adicione: ``` https://seu-servidor.com/callback ``` -> Замяна на `seu-servidor.com` pelo domínio или IP на вашия сървър (включително необходим порт, напр.: `http://45.33.32.156:20128/callback`). +> Substitua `seu-servidor.com` pelo domínio ou IP do seu servidor (inclua a porta se necessário, ex: `http://45.33.32.156:20128/callback`). **4. Salve e copie as credenciais** -Например, Google показва **Клиентски идентификатор** и **Клиентска тайна**. +Após criar, o Google mostrará o **Client ID** e o **Client Secret**. -**5. Конфигуриране като variáveis de ambiente** +**5. Configure as variáveis de ambiente** -Нямате `.env` (или нашите варианти на околната среда на Docker): +No seu `.env` (ou nas variáveis de ambiente do Docker): ```bash # Para Antigravity: @@ -1521,110 +1976,114 @@ docker restart omniroute **7. Tente conectar novamente** -Табло → Доставчици → Антигравитация (или Gemini CLI) → OAuth +Dashboard → Providers → Antigravity (ou Gemini CLI) → OAuth -Agora или Google пренасочва корекции за `https://seu-servidor.com/callback` и функционира автентичност. +Agora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará. --- -#### Временно заобиколно решение (само за конфигуриране на удостоверения) +#### Workaround temporário (sem configurar credenciais próprias) Se não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**: -1. O OmniRoute премахва URL адрес за авторизация от Google -2. Ако не сте авторизирани, пренасочването на Google е пренасочено за `localhost` (което не е отдалечено от сървъра) -3. **Копирайте пълния URL адрес** от страницата, която искате да прехвърлите в своя браузър (mesmo que a página não carregue) +1. O OmniRoute abrirá a URL de autorização do Google +2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto) +3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue) 4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute -5. Щракнете върху **"Свързване"** +5. Clique em **"Connect"** -> Това заобиколно решение функционира, ако кодът на авторизацията на URL е валиден независимо от пренасочването към пренасочване или не. +> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.
-
---
-## 📖 Документация
+## Документация
-| Документ | Описание |
-| ------------------------------------------------------------- | -------------------------------------------------------------- |
-| [Ръководство на потребителя](docs/USER_GUIDE.md) | Доставчици, комбинации, CLI интеграция, внедряване |
-| [API справка] (docs/API_REFERENCE.md) | Всички крайни точки с примери |
-| [MCP сървър] (open-sse/mcp-server/README.md) | 16 MCP инструмента, IDE конфигурации, Python/TS/Go клиенти |
-| [A2A сървър] (src/lib/a2a/README.md) | JSON-RPC 2.0 протокол, умения, стрийминг, управление на задачи |
-| [Автоматичен комбиниран двигател] (docs/auto-combo.md) | 6-факторно оценяване, пакети с режими, самолечение |
-| [Отстраняване на неизправности](docs/TROUBLESHOOTING.md) | Често срещани проблеми и решения |
-| [Архитектура] (docs/ARCHITECTURE.md) | Системна архитектура и вътрешност |
-| [Принос] (CONTRIBUTING.md) | Настройка и насоки за разработка |
-| [Спецификация на OpenAPI] (docs/openapi.yaml) | Спецификация на OpenAPI 3.0 |
-| [Правила за сигурност](SECURITY.md) | Отчитане на уязвимости и практики за сигурност |
-| [Внедряване на VM] (docs/VM_DEPLOYMENT_GUIDE.md) | Пълно ръководство: Настройка на VM + nginx + Cloudflare |
-| [Галерия с функции](docs/FEATURES.md) | Визуална обиколка на таблото с екранни снимки |
-| [Списък за проверка на изданието] (docs/RELEASE_CHECKLIST.md) | Стъпки за валидиране преди пускане |
+| Document | Description |
+| ---------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 16 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/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
+| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
-## 🗺️
+## 🗺️ Roadmap
-OmniRoute има **планирани 210+ функции** в множество фази на разработка. Ето основните области:
+OmniRoute has **210+ features planned** across multiple development phases. Here are the key areas:
-| Категория | Планирани функции | Акценти |
-| ----------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| 🧠 **Маршрутизиране и разузнаване** | 25+ | Маршрутизиране с най-ниска латентност, маршрутизиране на базата на маркери, предварителен полет на квота, избор на P2C акаунт |
-| 🔒 **Сигурност и съответствие** | 20+ | SSRF укрепване, прикриване на идентификационни данни, ограничение на скоростта за крайна точка, обхват на ключ за управление |
-| 📊 **Наблюдаемост** | 15+ | OpenTelemetry интеграция, мониторинг на квоти в реално време, проследяване на разходите за модел |
-| 🔄 **Интеграции на доставчици** | 20+ | Регистър на динамичен модел, изчакване на доставчика, Codex за множество акаунти, анализ на квота на Copilot |
-| ⚡ **Изпълнение** | 15+ | Слой с двоен кеш, кеш за подкани, кеш за отговор, поддържане на активността при поточно предаване, партиден API |
-| 🌐 **Екосистема** | 10+ | WebSocket API, горещо презареждане на конфигурация, разпределено хранилище за конфигурация, търговски режим |
+| Category | Planned Features | Highlights |
+| ----------------------------- | ---------------- | -------------------------------------------------------------------------------------- |
+| 🧠 **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, P2C account selection |
+| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |
+| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |
+| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider 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 |
-### 🔜 Очаквайте скоро- 🔗 **OpenCode Integration** — Поддръжка на родния доставчик за IDE за кодиране OpenCode AI
+### 🔜 Coming Soon
-- 🔗 **TRAE Integration** — Пълна поддръжка за рамката за разработка на TRAE AI
-- 📦 **Batch API** — Асинхронна групова обработка за групови заявки
-- 🎯 **Маршрутизиране на базата на етикети** — Маршрутизирайте заявки въз основа на персонализирани тагове и метаданни
-- 💰 **Стратегия с най-ниска цена** — Автоматично изберете най-евтиния наличен доставчик
+- 🔗 **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
-> 📝 Пълните спецификации на функциите са налични в [`docs/new-features/`](docs/new-features/) (217 подробни спецификации)
+> 📝 Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)
---
-## 👥 Сътрудници
+## 👥 Contributors
-[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
+[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
-### Как да допринесете
+### How to Contribute
-1. Разклонете хранилището
-2. Създайте своя клон на функция (`git checkout -b feature/amazing-feature`)
-3. Задайте вашите промени (`git commit -m 'Add amazing feature'`)
-4. Натиснете до клона (`git push origin feature/amazing-feature`)
-5. Отворете заявка за изтегляне
+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
-Вижте [CONTRIBUTING.md](CONTRIBUTING.md) за подробни насоки.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
-### Пускане на нова версия
+### Releasing a New Version
```bash
# Create a release — npm publish happens automatically
@@ -1633,28 +2092,28 @@ gh release create v2.0.0 --title "v2.0.0" --generate-notes
---
-## 📊 Звездна история
+## 📊 Star History
## Stargazers over time
## [](https://starchart.cc/diegosouzapw/OmniRoute)
-## 🙏 Благодарности
+## 🙏 Acknowledgments
-Специални благодарности на **[9router](https://github.com/decolua/9router)** от **[decolua](https://github.com/decolua)** — оригиналният проект, който вдъхнови това разклонение. OmniRoute се основава на тази невероятна основа с допълнителни функции, мултимодални API и пълно пренаписване на TypeScript.
+Special thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.
-Специални благодарности на **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — оригиналната реализация на Go, която вдъхнови този JavaScript порт.
+Special thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.
---
-## 📄 Лиценз
+## Лиценз
-Лиценз на MIT – вижте [ЛИЦЕНЗ](LICENSE) за подробности.
+MIT License - see [LICENSE](LICENSE) for details.
---
Щракнете, за да разширите подробностите за технически стек
+Click to expand tech stack details
-- **Време на изпълнение**: Node.js 18–22 LTS (⚠️ Node.js 24+ **не се поддържа** — родните двоични файлове на `better-sqlite3` са несъвместими) -- **Език**: TypeScript 5.9 — **100% TypeScript** в `src/` и `open-sse/` (нула `any` в основните модули от v2.0) +- **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 -- **База данни**: LowDB (JSON) + SQLite (състояние на домейна + регистрационни файлове на прокси + MCP одит + решения за маршрутизиране) -- **Схеми**: Zod (валидиране на I/O инструмент за MCP, API договори) -- **Протоколи**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE) -- **Поточно предаване**: Изпратени от сървъра събития (SSE) -- **Auth**: OAuth 2.0 (PKCE) + JWT + API ключове + MCP оторизация с обхват -- **Тестване**: Node.js тестов инструмент + Vitest (900+ теста, включително модул, интеграция, E2E)- **CI/CD**: Действия на GitHub (автоматично публикуване на npm + Docker Hub при пускане) -- **Уебсайт**: [omniroute.online](https://omniroute.online) -- **Пакет**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute) +- **Database**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions) +- **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) -- **Устойчивост**: прекъсвач, експоненциално отдръпване, анти-гръмотевично стадо, TLS подправяне, автоматично комбинирано самолечение +- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing
- Създаден с ❤️ за разработчици, които кодират 24/7
+ Built with ❤️ for developers who code 24/7
omniroute.online
diff --git a/docs/i18n/bg/docs/FEATURES.md b/docs/i18n/bg/docs/FEATURES.md
new file mode 100644
index 0000000000..8280fb588d
--- /dev/null
+++ b/docs/i18n/bg/docs/FEATURES.md
@@ -0,0 +1,145 @@
+# OmniRoute — Dashboard Features Gallery (Български)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/FEATURES.md) · 🇪🇸 [es](../../es/docs/FEATURES.md) · 🇫🇷 [fr](../../fr/docs/FEATURES.md) · 🇩🇪 [de](../../de/docs/FEATURES.md) · 🇮🇹 [it](../../it/docs/FEATURES.md) · 🇷🇺 [ru](../../ru/docs/FEATURES.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FEATURES.md) · 🇯🇵 [ja](../../ja/docs/FEATURES.md) · 🇰🇷 [ko](../../ko/docs/FEATURES.md) · 🇸🇦 [ar](../../ar/docs/FEATURES.md) · 🇮🇳 [in](../../in/docs/FEATURES.md) · 🇹🇭 [th](../../th/docs/FEATURES.md) · 🇻🇳 [vi](../../vi/docs/FEATURES.md) · 🇮🇩 [id](../../id/docs/FEATURES.md) · 🇲🇾 [ms](../../ms/docs/FEATURES.md) · 🇳🇱 [nl](../../nl/docs/FEATURES.md) · 🇵🇱 [pl](../../pl/docs/FEATURES.md) · 🇸🇪 [sv](../../sv/docs/FEATURES.md) · 🇳🇴 [no](../../no/docs/FEATURES.md) · 🇩🇰 [da](../../da/docs/FEATURES.md) · 🇫🇮 [fi](../../fi/docs/FEATURES.md) · 🇵🇹 [pt](../../pt/docs/FEATURES.md) · 🇷🇴 [ro](../../ro/docs/FEATURES.md) · 🇭🇺 [hu](../../hu/docs/FEATURES.md) · 🇧🇬 [bg](../../bg/docs/FEATURES.md) · 🇸🇰 [sk](../../sk/docs/FEATURES.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FEATURES.md) · 🇮🇱 [he](../../he/docs/FEATURES.md) · 🇵🇭 [phi](../../phi/docs/FEATURES.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FEATURES.md)
+
+---
+
+Visual guide to every section of the OmniRoute dashboard.
+
+---
+
+## 🔌 Providers
+
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
+
+
+
+---
+
+## 🎨 Combos
+
+Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
+
+
+
+---
+
+## 📊 Analytics
+
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
+
+
+
+---
+
+## 🏥 System Health
+
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+
+
+
+---
+
+## 🔧 Translator Playground
+
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
+
+
+
+---
+
+## 🎮 Model Playground _(v2.0.9+)_
+
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
+
+---
+
+## 🎨 Themes _(v2.0.5+)_
+
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
+
+## ⚙️ Settings
+
+Comprehensive settings panel with tabs:
+
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning
+- **Advanced** — Configuration overrides
+
+
+
+---
+
+## 🔧 CLI Tools
+
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
+
+
+
+---
+
+## 🤖 CLI Agents _(v2.0.11+)_
+
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
+
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
+
+---
+
+## 🖼️ Media _(v2.0.3+)_
+
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
+
+## 📝 Request Logs
+
+Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
+
+
+
+---
+
+## 🌐 API Endpoint
+
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
+
+
+
+---
+
+## 🔑 API Key Management
+
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
+
+---
+
+## 📋 Audit Log
+
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
+
+---
+
+## 🖥️ Desktop Application
+
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
+
+Key features:
+
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
+
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.
diff --git a/docs/i18n/da/README.md b/docs/i18n/da/README.md
index 3a0b5f928b..19b745d4e8 100644
--- a/docs/i18n/da/README.md
+++ b/docs/i18n/da/README.md
@@ -1,16 +1,89 @@
-# 🚀 OmniRoute — Den gratis AI-gateway
+# 🚀 OmniRoute — The Free AI Gateway (Dansk)
-### Stop aldrig med at kode. Smart routing til **GRATIS og billige AI-modeller** med automatisk fallback.
-
-_Din universelle API-proxy — ét slutpunkt, 36+ udbydere, ingen nedetid. Nu med **MCP & A2A** agentorkestrering._
-
-**Chatafslutninger • Indlejringer • Billedgenerering • Video • Musik • Lyd • Genrangering • MCP-server • A2A-protokol • 100 % TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Gratis AI-udbyder til dine foretrukne kodningsagenter
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Tilslut ethvert AI-drevet IDE- eller CLI-værktøj gennem OmniRoute - gratis API-gateway til ubegrænset kodning._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+omniroute.online
+
+[](https://www.npmjs.com/package/omniroute)
+[](https://www.npmjs.com/package/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
+[](https://omniroute.online)
+[](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)
+
+
+
+🌐 **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)
+
+---
+
+## 🆕 What's New in v3.0.0
+
+> **Upgrading from v2.9.5?** — See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes.
+
+| Area | Change |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection remediation |
+| ✅ **Route Validation** | All 176 API routes now validated with Zod schemas + `validateBody()` — CI `check:route-validation:t06` passes |
+| 🐛 **omniModel Tag Leak** | Internal `
+
+
+
+---
+
+## 📸 Dashboard Preview
+
+
+
+
+
+---
+
+### 🤖 Free AI Provider for your favorite coding agents
+
+_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._
Click to see dashboard screenshots
+ +| Page | Screenshot | +| -------------- | ------------------------------------------------- | +| **Providers** |  | +| **Combos** |  | +| **Analytics** |  | +| **Health** |  | +| **Translator** |  | +| **Settings** |  | +| **CLI Tools** |  | +| **Usage Logs** |  | +| **Endpoints** |  | + +
 NanoBot - ⭐ 20,9K + ⭐ 20.9K |
@@ -39,7 +113,7 @@ _Tilslut ethvert AI-drevet IDE- eller CLI-værktøj gennem OmniRoute - gratis AP
ZeroClaw - ⭐ 9,9K + ⭐ 9.9K |
@@ -67,7 +141,7 @@ _Tilslut ethvert AI-drevet IDE- eller CLI-værktøj gennem OmniRoute - gratis AP |
- Claude Kode + Claude Code ⭐ 67.3K |
@@ -81,76 +155,59 @@ _Tilslut ethvert AI-drevet IDE- eller CLI-værktøj gennem OmniRoute - gratis AP
- Kilo-kode + Kilo Code - ⭐ 15,5K + ⭐ 15.5K |
http://localhost:20128/v1 eller http://cloud.omniroute.online/v1XQZPH00 og unlimited model conf. quota
+📡 All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 — one config, unlimited models and quota
---
-### 🆕 What's New in v3.0.0
+## 🤔 Why OmniRoute?
-| Area | Change |
-| ------------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal ` Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal ` Abonnementskontingent udløber ubrugt hver måned
-- Hastighedsgrænser stopper dig med midtkodning
-- Dyre API'er ($20-50/måned pr. udbyder)
-- Manuel skift mellem udbydere
-
-**OmniRoute løser dette:**
-
-- ✅ **Maksimer abonnementer** - Spor kvote, brug hver bit før nulstilling
-- ✅ **Automatisk fallback** - Abonnement → API-nøgle → Billig → Gratis, ingen nedetid
-- ✅ **Multi-konto** - Round-robin mellem konti pr. udbyder
-- ✅ **Universal** - Virker med Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, ethvert CLI-værktøj
-
----
-
-## 📧 Support> 💬 **Tilmeld dig vores fællesskab!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Få hjælp, del tips, og hold dig opdateret.
-
-- **Websted**: [omniroute.online](https://omniroute.online)
+- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Problemer**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **WhatsApp**: [Fællesskabsgruppe](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Bidrager**: Se [CONTRIBUTING.md](CONTRIBUTING.md), åbn en PR, eller vælg en `good first issue`
-- **Originalt projekt**: [9router af decolua](https://github.com/decolua/9router)
+- **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`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 Sådan virker det
+## 🔄 How It Works
```
┌─────────────┐
@@ -179,442 +236,453 @@ Result: Never stop coding, minimal cost
---
-## 🎯 Hvad OmniRoute løser — 30 rigtige smertepunkter og brugssager
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **Alle udviklere, der bruger AI-værktøjer, står over for disse problemer dagligt.** OmniRoute blev bygget til at løse dem alle - fra omkostningsoverskridelser til regionale blokke, fra ødelagte OAuth-flows til protokoloperationer og observerbarhed i virksomheden.
+> **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.
-
💸 1. "Jeg betaler for et dyrt abonnement, men bliver stadig afbrudt af grænser"
+💸 1. "I pay for an expensive subscription but still get interrupted by limits"
-Udviklere betaler $20-200/måned for Claude Pro, Codex Pro eller GitHub Copilot. Selv ved betaling har kvoten et loft - 5 timers brug, ugentlige grænser eller satsgrænser pr. minut. Mid-coding session, udbyderen holder op med at svare, og udvikleren mister flow og produktivitet. +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. -**Sådan løser OmniRoute det:** +**How OmniRoute solves it:** -- **Smart 4-Tier Fallback** — Hvis abonnementskvoten løber ud, omdirigeres automatisk til API Key → Billig → Gratis uden manuel indgriben -- **Kvotesporing i realtid** — Viser tokenforbrug i realtid med nulstillingsnedtælling (5 timer, dagligt, ugentligt) -- **Multi-Account Support** - Flere konti pr. udbyder med automatisk round-robin - når den ene løber tør, skifter til den næste -- **Custom Combos** — Tilpasselige fallback-kæder med 6 balanceringsstrategier (fill-first, round-robin, P2C, tilfældig, mindst brugt, omkostningsoptimeret) -- **Codex Business Quotas** — Business/Team Workspace kvoteovervågning direkte i dashboardet +- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention +- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly) +- **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 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
-`-blokke fra modeller som DeepSeek R1 til standardiseret `reasoning_content`
-- **Structured Output for Gemini** — `json_schema` → `responseMimeType`/`responseSchema` automatisk konvertering
-- **`stream` er som standard `false`** — Justerer med OpenAI-specifikationer, og undgår uventede SSE i Python/Rust/Go SDK'er
-
-🔌 2. "Jeg skal bruge flere udbydere, men hver har en forskellig API"
+🔌 2. "I need to use multiple providers but each has a different API"
-OpenAI bruger et format, Claude (Antropisk) bruger et andet, Gemini endnu et andet. Hvis en udvikler ønsker at teste modeller fra forskellige udbydere eller fallback mellem dem, skal de omkonfigurere SDK'er, ændre slutpunkter, håndtere inkompatible formater. Tilpassede udbydere (FriendLI, NIM) har ikke-standardmodelslutpunkter. +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. -**Sådan løser OmniRoute det:** +**How OmniRoute solves it:** -- **Unified Endpoint** — En enkelt `http://localhost:20128/v1` fungerer som proxy for alle 36+ udbydere -- **Formatoversættelse** — Automatisk og gennemsigtig: OpenAI ↔ Claude ↔ Gemini ↔ Responses API -- **Responssanering** — Fjerner ikke-standardfelter (`x_groq`, `usage_breakdown`, `service_tier`), der bryder OpenAI SDK v1.83+ -- **Rollenormalisering** — Konverterer `developer` → `system` for ikke-OpenAI-udbydere; `system` → `user` til GLM/ERNIE -- **Think Tag Extraction** — Udtrækker `
-` 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
🌐 3. "Min AI-udbyder blokerer mit område/land"
- -Udbydere som OpenAI/Codex blokerer adgang fra visse geografiske områder. Brugere får fejl som `unsupported_country_region_territory` under OAuth- og API-forbindelser. Dette er især frustrerende for udviklere fra udviklingslande. - -**Sådan løser OmniRoute det:** - -- **3-Level Proxy Config** — Konfigurerbar proxy på 3 niveauer: global (al trafik), pr. udbyder (kun én udbyder) og pr. forbindelse/nøgle -- **Farvekodede proxy-badges** — Visuelle indikatorer: 🟢 global proxy, 🟡 udbyder proxy, 🔵 forbindelsesproxy, viser altid IP'en -- **OAuth-tokenudveksling gennem proxy** — OAuth-flowet går også gennem proxyen og løser `unsupported_country_region_territory` -- **Forbindelsestest via proxy** — Forbindelsestest bruger den konfigurerede proxy (ikke mere direkte omgåelse) -- **SOCKS5-understøttelse** — Fuld SOCKS5-proxy-understøttelse til udgående routing -- **TLS Fingerprint Spoofing** — Browserlignende TLS-fingeraftryk via `wreq-js` for at omgå botdetektion +- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 67+ 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 `
-
+
+🆓 4. "Jeg vil bruge AI til kodning, men jeg har ingen penge"
+🌐 3. "My AI provider blocks my region/country"
-Ikke alle kan betale $20-200/måned for AI-abonnementer. Studerende, udviklere fra vækstlande, hobbyfolk og freelancere har brug for adgang til kvalitetsmodeller uden omkostninger. +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. -**Sådan løser OmniRoute det:** +**How OmniRoute solves it:** -- **Free Tier Providers Indbygget** — Indbygget support for 100 % gratis udbydere: iFlow (8 ubegrænsede modeller), Qwen (3 ubegrænsede modeller), Kiro (Claude gratis), Gemini CLI (180K/måned gratis) +- **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 + +
+` prefix
-- **Kun gratis kombinationer** — Kæde `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/måned uden nedetid
-- **NVIDIA NIM gratis kreditter** — 1000 gratis kreditter integreret
-- **Cost Optimized Strategy** — Routingstrategi, der automatisk vælger den billigste tilgængelige udbyder
+- **Free-Only Combos** — Chain `gc/gemini-3-flash → 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
🆓 4. "I want to use AI for coding but I have no money"
+ +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. + +**How OmniRoute solves it:** + +- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free) - **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/
-
🔒 5. "Jeg skal beskytte min AI-gateway mod uautoriseret adgang"
+🔒 5. "I need to protect my AI gateway from unauthorized access"
-Når en AI-gateway eksponeres for netværket (LAN, VPS, Docker), kan enhver med adressen forbruge udviklerens tokens/kvote. Uden beskyttelse er API'er sårbare over for misbrug, hurtig injektion og misbrug. +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. -**Sådan løser OmniRoute det:** +**How OmniRoute solves it:** -- **API Key Management** — Generering, rotation og scoping pr. udbyder med en dedikeret `/dashboard/api-manager` side -- **Tilladelser på modelniveau** — Begræns API-nøgler til specifikke modeller (`openai/*`, jokertegnmønstre) med Tillad alt/Begræns-skift -- **API Endpoint Protection** — Kræv en nøgle til `/v1/models` og bloker specifikke udbydere fra fortegnelsen -- **Auth Guard + CSRF Protection** — Alle dashboard-ruter beskyttet med `withAuth` middleware + CSRF-tokens -- **Rate Limiter** — Per-IP hastighedsbegrænsning med konfigurerbare vinduer -- **IP-filtrering** — Tilladelsesliste/blokeringsliste til adgangskontrol -- **Prompt Injection Guard** — Sanering mod ondsindede promptmønstre -- **AES-256-GCM-kryptering** — Legitimationsoplysninger krypteret i hvile +- **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. "Min udbyder gik ned, og jeg mistede mit kodningsflow"
AI-udbydere kan blive ustabile, returnere 5xx-fejl eller ramme midlertidige hastighedsgrænser. Hvis en udvikler afhænger af en enkelt udbyder, bliver de afbrudt. Uden strømafbrydere kan gentagne genforsøg crashe programmet. +🛑 6. "My provider went down and I lost my coding flow"
-**Sådan løser OmniRoute det:** +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. -- **Circuit Breaker pr. udbyder** — Automatisk åbning/lukning med konfigurerbare tærskler og nedkøling (lukket/åbent/halvt åbent) - | 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format | -- **Eksponentiel backoff** — Progressive forsinkelser af genforsøg -- **Anti-tordenbesætning** — Mutex + semaforbeskyttelse mod samtidige genforsøgsstorme -- **Combo Fallback Chains** — Hvis den primære udbyder fejler, falder den automatisk gennem kæden uden indgriben -- **Combo Circuit Breaker** - Deaktiverer automatisk fejlende udbydere i en kombinationskæde - | 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format | -- **Health Dashboard** — Oppetidsovervågning, strømafbrydertilstande, lockouts, cachestatistik, p50/p95/p99 latency +**How OmniRoute solves it:** + +- **Circuit Breaker per-model** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks +- **Exponential Backoff** — Progressive retry delays +- **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 +- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain +- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
-
🔧 7. "Konfiguration af hvert AI-værktøj er trættende og gentagende"
+🔧 7. "Configuring each AI tool is tedious and repetitive"
-Udviklere bruger Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Hvert værktøj har brug for en anden konfiguration (API-endepunkt, nøgle, model). At omkonfigurere, når du skifter udbyder eller model, er spild af tid. +Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time. -**Sådan løser OmniRoute det:** +**How OmniRoute solves it:** -- **CLI Tools Dashboard** — Dedikeret side med et-klik opsætning til Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline -- **GitHub Copilot Config Generator** — Genererer `chatLanguageModels.json` til VS-kode med bulk modelvalg -- **Onboarding Wizard** — Guidet 4-trins opsætning for førstegangsbrugere -- **Ét slutpunkt, alle modeller** — Konfigurer `http://localhost:20128/v1` én gang, få adgang til 36+ udbydere +- **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 67+ providers
-
🔑 8. "Administration af OAuth-tokens fra flere udbydere er et helvede"
+🔑 8. "Managing OAuth tokens from multiple providers is hell"
-Claude Code, Codex, Gemini CLI, Copilot - alle bruger OAuth 2.0 med udløbende tokens. Udviklere skal re-godkende konstant, håndtere `client_secret is missing`, `redirect_uri_mismatch` og fejl på fjernservere. OAuth på LAN/VPS er særligt problematisk. +Claude Code, Codex, Gemini CLI, 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. -**Sådan løser OmniRoute det:** +**How OmniRoute solves it:** -- **Automatisk tokenopdatering** — OAuth-tokens opdateres i baggrunden før udløb -- **OAuth 2.0 (PKCE) Indbygget** — Automatisk flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow -- **Multi-Account OAuth** — Flere konti pr. udbyder via JWT/ID-tokenudtrækning -- **OAuth LAN/Remote Fix** — Privat IP-detektion for `redirect_uri` + manuel URL-tilstand til fjernservere -- **OAuth Behind Nginx** — Bruger `window.location.origin` til omvendt proxykompatibilitet -- **Remote OAuth Guide** — Trin-for-trin guide til Google Cloud-legitimationsoplysninger på VPS/Docker +- **Auto Token Refresh** — OAuth tokens refresh in background before expiration +- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow +- **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. "Jeg ved ikke, hvor meget jeg bruger eller hvor"
+📊 9. "I don't know how much I'm spending or where"
-Udviklere bruger flere betalte udbydere, men har ikke noget samlet syn på udgifter. Hver udbyder har sit eget faktureringsdashboard, men der er ingen konsolideret visning. Uventede omkostninger kan hobe sig op. +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. -**Sådan løser OmniRoute det:** +**How OmniRoute solves it:** -- **Dashboard for omkostningsanalyse** — omkostningssporing pr. token og budgetstyring pr. udbyder -- **Budgetgrænser pr. niveau** — Udgiftsloft pr. niveau, der udløser automatisk fallback -- **Priskonfiguration pr. model** — Konfigurerbare priser pr. model- **Brugsstatistik pr. API-nøgle** — Antal anmodninger og sidst anvendte tidsstempel pr. nøgle -- **Analytics Dashboard** — Statiske kort, modelbrugsdiagram, udbydertabel med succesrater og latens +- **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. "Jeg kan ikke diagnosticere fejl og problemer i AI-opkald"
+🐛 10. "I can't diagnose errors and problems in AI calls"
-Når et opkald mislykkes, ved udvikleren ikke, om det var en takstgrænse, udløbet token, forkert format eller udbyderfejl. Fragmenterede logfiler på tværs af forskellige terminaler. Uden observerbarhed er fejlfinding trial-and-error. +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. -**Sådan løser OmniRoute det:** +**How OmniRoute solves it:** -- **Unified Logs Dashboard** — 4 faner: Request Logs, Proxy Logs, Audit Logs, Console -- **Console Log Viewer** — Realtidsterminal-fremviser med farvekodede niveauer, automatisk rulning, søg, filtrer -- **SQLite Proxy Logs** — Vedvarende logfiler, der overlever servergenstarter -- **Oversætterlegeplads** — 4 fejlfindingstilstande: Legeplads (formatoversættelse), Chattester (rundtur), Testbænk (batch), Live Monitor (realtid) -- **Request Telemetri** — p50/p95/p99 latency + X-Request-Id-sporing -- **Filbaseret logning med rotation** — Konsolinterceptor fanger alt til JSON-log med størrelsesbaseret rotation +- **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 Proxy Logs** — Persistent logs that survive server restarts +- **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 Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation +- **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. "Deployering og vedligeholdelse af gatewayen er kompleks"
+🏗️ 11. "Deploying and maintaining the gateway is complex"
-Installation, konfiguration og vedligeholdelse af en AI-proxy på tværs af forskellige miljøer (lokalt, VPS, Docker, cloud) er arbejdskrævende. Problemer som hårdkodede stier, `EACCES` på mapper, portkonflikter og cross-platform builds tilføjer friktion. +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. -**Sådan løser OmniRoute det:** +**How OmniRoute solves it:** -- **npm global installation** — `npm install -g omniroute && omniroute` — udført +- **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` (ingen CLI-værktøjer) og `cli` (med Claude Code, Codex, OpenClaw) -- **Electron Desktop App** — Indbygget app til Windows/macOS/Linux med systembakke, autostart, offlinetilstand -- **Split-Port Mode** — API og Dashboard på separate porte til avancerede scenarier (omvendt proxy, containernetværk) -- **Cloud Sync** — Konfigurer synkronisering på tværs af enheder via Cloudflare Workers -- **DB Backups** — Automatisk backup, gendannelse, eksport og import af alle indstillinger +- **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
-
-
-🌍 12. "Grænsefladen er kun engelsk, og mit team taler ikke engelsk"
+🌍 12. "The interface is English-only and my team doesn't speak English"
-Hold i ikke-engelsktalende lande, især i Latinamerika, Asien og Europa, kæmper med grænseflader, der kun er på engelsk. Sprogbarrierer reducerer adoption og øger konfigurationsfejl. +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. -**Sådan løser OmniRoute det:** +**How OmniRoute solves it:** -- **Dashboard i18n — 30 sprog** — Alle 500+ taster oversat, inklusive arabisk, bulgarsk, dansk, tysk, spansk, finsk, fransk, hebraisk, hindi, ungarsk, indonesisk, italiensk, japansk, koreansk, malaysisk, hollandsk, norsk, polsk, portugisisk (PT/BR), rumænsk, russisk, ukrainsk, kinesisk, ukrainsk, kinesisk, kinesisk, ukrainsk, kinesisk, ukrainsk, kinesisk, ukrainsk, svensk, Vietnam, Vietnam -- **RTL-understøttelse** — Højre-til-venstre-understøttelse for arabisk og hebraisk -- **Multi-Language READMEs** — 30 komplette dokumentationsoversættelser -- **Sprogvælger** — Globusikon i overskriften til skift i realtid
-
🔄 13. "Jeg har brug for mere end chat — jeg har brug for indlejringer, billeder, lyd"
- -AI er ikke kun fuldførelse af chat. Udviklere skal generere billeder, transskribere lyd, oprette indlejringer til RAG, omrangere dokumenter og moderere indhold. Hver API har et andet slutpunkt og format. - -**Sådan løser OmniRoute det:** - -- **Indlejringer** — `/v1/embeddings` med 6 udbydere og 9+ modeller -- **Billedgenerering** — `/v1/images/generations` med 10 udbydere og 20+ modeller (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI) -- **Tekst-til-video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) og SD WebUI -- **Tekst-til-musik** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen) -- **Lydtransskription** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3 -- **Tekst-til-tale** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, Inworld, Cartesia, PlayHT, + eksisterende udbydere -- **Moderationer** — `/v1/moderations` — Indholdssikkerhedstjek -- **Omrangering** — `/v1/rerank` — Omrangering af dokumentrelevans -- **Responses API** — Fuld `/v1/responses`-understøttelse af Codex +- **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
-
🧪 14. "Jeg har ingen måde at teste og sammenligne kvalitet på tværs af modeller"
+🔄 13. "I need more than chat — I need embeddings, images, audio"
-Udviklere vil gerne vide, hvilken model der er bedst til deres brug - kode, oversættelse, ræsonnement - men manuel sammenligning er langsom. Der findes ingen integrerede evalueringsværktøjer. +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. -**Sådan løser OmniRoute det:** +**How OmniRoute solves it:** -- **LLM-evalueringer** — Gyldne sæt-test med 10 forudindlæste cases, der dækker hilsner, matematik, geografi, kodegenerering, JSON-overholdelse, oversættelse, markdown, sikkerhedsafvisning -- **4 matchstrategier** — `exact`, `contains`, `regex`, `custom` (JS-funktion) -- **Translator Playground Test Bench** — Batchtest med flere input og forventede output, sammenligning på tværs af udbydere -- **Chattester** — Fuld rundtur med visuel responsgengivelse -- **Live Monitor** — Realtidsstream af alle anmodninger, der flyder gennem proxyen +- **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
-
📈 15. "Jeg har brug for at skalere uden at miste ydeevne"
+🧪 14. "I have no way to test and compare quality across models"
-Efterhånden som forespørgselsvolumen vokser, genererer de samme spørgsmål duplikerede omkostninger uden cache. Uden idempotens, dublerede anmodninger om affaldsbehandling. Takstgrænser pr. udbyder skal overholdes. +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. -**Sådan løser OmniRoute det:** +**How OmniRoute solves it:** -- **Semantisk cache** — To-lags cache (signatur + semantisk) reducerer omkostninger og latens -- **Request Idempotency** — 5s deduplikeringsvindue for identiske anmodninger -- **Detektion af hastighedsgrænse** — RPM pr. udbyder, min. gap og maks. samtidig sporing -- **Redigerbare hastighedsgrænser** — Konfigurerbare standardindstillinger i Indstillinger → Modstandsdygtighed med vedholdenhed -- **API Key Validation Cache** — 3-lags cache til produktionsydeevne -- **Health Dashboard med telemetri** — p50/p95/p99 latency, cachestatistik, oppetid +- **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
-
🤖 16. "Jeg vil kontrollere modeladfærd globalt"
Udviklere, der ønsker alle svar på et bestemt sprog, med en bestemt tone, eller ønsker at begrænse ræsonnementstokens. Det er upraktisk at konfigurere dette i hvert værktøj/anmodning. +📈 15. "I need to scale without losing performance"
-**Sådan løser OmniRoute det:** +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. -- **System Prompt Injection** — Global prompt anvendt på alle anmodninger -- **Thinking Budget Validation** — Reasoning token allocation control pr. anmodning (passthrough, auto, custom, adaptive) -- **6 Routing Strategies** — Globale strategier, der bestemmer, hvordan anmodninger distribueres -- **Wildcard-router** — `provider/*`-mønstre ruter dynamisk til enhver udbyder -- **Kombo Aktiver/Deaktiver Til/fra** — Skift kombinationer direkte fra dashboardet -- **Tilskiftning af udbyder** — Aktiver/deaktiver alle forbindelser for en udbyder med et enkelt klik -- **Blokerede udbydere** — Ekskluder specifikke udbydere fra `/v1/models`-fortegnelsen +**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 +- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence +- **API Key Validation Cache** — 3-tier cache for production performance +- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
-
🧰 17. "Jeg har brug for MCP-værktøjer som førsteklasses produktegenskaber"
+🤖 16. "I want to control model behavior globally"
-Mange AI-gateways afslører kun MCP som en skjult implementeringsdetalje. Teams har brug for et synligt, overskueligt operationslag. +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. -**Sådan løser OmniRoute det:** +**How OmniRoute solves it:** -- MCP vises på fanen dashboardnavigation og endepunktsprotokol -- Dedikeret MCP-administrationsside med proces, værktøjer, omfang og revision -- Indbygget hurtigstart til `omniroute --mcp` og klient onboarding +- **System Prompt Injection** — Global prompt applied to all requests +- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive) +- **6 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 +- **Provider Toggle** — Enable/disable all connections for a provider with one click +- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
-
🧠 18. "Jeg har brug for A2A-orkestrering med synkronisering + streamopgavestier"
+🧰 17. "I need MCP tools as first-class product capabilities"
-Agentarbejdsgange kræver både direkte svar og langvarig streamet udførelse med livscykluskontrol. +Many AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer. -**Sådan løser OmniRoute det:** +**How OmniRoute solves it:** -- A2A JSON-RPC slutpunkt (`POST /a2a`) med `message/send` og `message/stream` -- SSE-streaming med udbredelse af terminaltilstand -- Task lifecycle API'er til `tasks/get` og `tasks/cancel` +- 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
-
🛰️ 19. "Jeg har brug for ægte MCP-processundhed, ikke gættet status"
+🧠 18. "I need A2A orchestration with sync + stream task paths"
-Operationelle teams skal vide, om MCP faktisk er i live, ikke kun om en API er tilgængelig. +Agent workflows need both direct replies and long-running streamed execution with lifecycle control. -**Sådan løser OmniRoute det:** +**How OmniRoute solves it:** -- Runtime-hjerteslagsfil med PID, tidsstempler, transport, værktøjstælling og omfangstilstand -- MCP status API, der kombinerer hjerteslag + seneste aktivitet -- UI-statuskort til proces/oppetid/hjerteslagsfriskhed +- 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`
-
📋 20. "Jeg har brug for revisionsbar MCP-værktøjsudførelse"
+🛰️ 19. "I need real MCP process health, not guessed status"
-Når værktøjer muterer konfiguration eller udløser ops-handlinger, har teams brug for retsmedicinsk sporbarhed. +Operational teams need to know if MCP is actually alive, not just whether an API is reachable. -**Sådan løser OmniRoute det:** +**How OmniRoute solves it:** -- SQLite-støttet revisionslogning for MCP-værktøjsopkald -- Filtrerer efter værktøj, succes/fiasko, API-nøgle og paginering -- Dashboard revisionstabel + statistik slutpunkter til automatisering +- 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
-
-
-🔐 21. "Jeg har brug for scoped MCP-tilladelser pr. integration"
+📋 20. "I need auditable MCP tool execution"
-Forskellige klienter bør have mindst privilegeret adgang til værktøjskategorier. +When tools mutate config or trigger ops actions, teams need forensic traceability. -**Sådan løser OmniRoute det:** +**How OmniRoute solves it:** -- 9 granulære MCP-skoper til kontrolleret værktøjsadgang -- Håndhævelse af omfang og synlighed i MCP management UI -- Sikker standardstilling for operationelt værktøj - -⚙️ 22. "Jeg har brug for operationelle kontroller uden omfordeling"
- -Teams har brug for hurtige runtime-ændringer under hændelser eller omkostningsbegivenheder. - -**Sådan løser OmniRoute det:** - -- Skift kombinationsaktivering direkte fra MCP-dashboard -- Anvend modstandsdygtighedsprofiler fra foruddefinerede politikpakker -- Nulstil strømafbrydertilstand fra det samme betjeningspanel +- SQLite-backed audit logging for MCP tool calls +- Filters by tool, success/failure, API key, and pagination +- Dashboard audit table + stats endpoints for automation
-
🔄 23. "Jeg har brug for live A2A opgave livscyklus synlighed og annullering"
+🔐 21. "I need scoped MCP permissions per integration"
-Uden livscyklussynlighed bliver opgavehændelser svære at triage. +Different clients should have least-privilege access to tool categories. -**Sådan løser OmniRoute det:** +**How OmniRoute solves it:** -- Opgaveliste/filtrering efter tilstand/færdighed med paginering -- Drill-down på opgavemetadata, hændelser og artefakter -- Slutpunkt for annullering af opgave og UI-handling med bekræftelse +- 9 granular MCP scopes for controlled tool access +- Scope enforcement and visibility in MCP management UI +- Safe default posture for operational tooling
-
🌊 24. "Jeg har brug for aktive stream-metrics for A2A-indlæsning"
+⚙️ 22. "I need operational controls without redeploying"
-Streaming-arbejdsgange kræver operationel indsigt i samtidighed og live-forbindelser. +Teams need quick runtime changes during incidents or cost events. -**Sådan løser OmniRoute det:** +**How OmniRoute solves it:** -- Aktive stream-tællere integreret i A2A-status -- Tidsstempel for sidste opgave og tæller pr. stat -- A2A dashboard-kort til operationsovervågning i realtid +- Switch combo activation directly from MCP dashboard +- Apply resilience profiles from pre-defined policy packs +- Reset circuit breaker state from the same operations panel
-
🪪 25. "Jeg har brug for standardagentopdagelse til klienter"
+🔄 23. "I need live A2A task lifecycle visibility and cancellation"
-Eksterne klienter og orkestratorer har brug for maskinlæsbare metadata til onboarding. +Without lifecycle visibility, task incidents become hard to triage. -**Sådan løser OmniRoute det:** +**How OmniRoute solves it:** -- Agentkort afsløret på `/.well-known/agent.json` -- Evner og færdigheder vist i ledelsens brugergrænseflade -- A2A status API inkluderer opdagelsesmetadata til automatisering +- Task listing/filtering by state/skill with pagination +- Drill-down on task metadata, events, and artifacts +- Task cancellation endpoint and UI action with confirmation
-
🧭 26. "Jeg har brug for protokolsynlighed i produktets UX"
+🌊 24. "I need active stream metrics for A2A load"
-Hvis brugere ikke kan opdage protokoloverflader, falder kvaliteten af adoption og support. +Streaming workflows require operational insight into concurrency and live connections. -**Sådan løser OmniRoute det:** +**How OmniRoute solves it:** -- Sidebar-indgange til MCP og A2A -- Endpoint-siden Protokoller-fane med hurtig start og status -- Links fra oversigt til dedikerede ledelsesdashboards +- Active stream counters integrated into A2A status +- Last task timestamp and per-state counts +- A2A dashboard cards for real-time ops monitoring
-
🧪 27. "Jeg har brug for end-to-end protokolvalidering med rigtige klienter"
+🪪 25. "I need standard agent discovery for clients"
-Mock-tests er ikke nok til at validere protokolkompatibilitet før frigivelse. +External clients and orchestrators need machine-readable metadata for onboarding. -**Sådan løser OmniRoute det:** +**How OmniRoute solves it:** -- E2E-pakke, der starter app og bruger ægte MCP SDK-klienttransport -- A2A klient tester for opdagelse, send, stream, hent og annuller flows -- Krydstjek påstande mod MCP-revision og A2A-opgaver API'er +- Agent Card exposed at `/.well-known/agent.json` +- Capabilities and skills shown in management UI +- A2A status API includes discovery metadata for automation
-
📡 28. "Jeg har brug for samlet observerbarhed på tværs af alle grænseflader"
+🧭 26. "I need protocol discoverability in the product UX"
-Opdeling af observerbarhed efter protokol skaber blinde pletter og længere MTTR. +If users cannot discover protocol surfaces, adoption and support quality drop. -**Sådan løser OmniRoute det:** +**How OmniRoute solves it:** -- Samlede dashboards/logfiler/analyse i ét produkt -- Health + audit + request telemetri på tværs af OpenAI, MCP og A2A lag -- Operationelle API'er til status og automatisering +- 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
-
💼 29. "Jeg har brug for én køretid til proxy + værktøjer + agentorkestrering"
+🧪 27. "I need end-to-end protocol validation with real clients"
-At køre mange separate tjenester øger driftsomkostninger og fejltilstande. +Mock tests are not enough to validate protocol compatibility before release. -**Sådan løser OmniRoute det:**- OpenAI-kompatibel proxy, MCP-server og A2A-server i én stak +**How OmniRoute solves it:** -- Delt godkendelse, robusthed, datalager og observerbarhed -- Ensartet politikmodel på tværs af alle interaktionsflader +- 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
-
-### Eksempler på Playbooks
+🚀 30. "Jeg har brug for at sende agentiske arbejdsgange uden limkodesprawl"
+📡 28. "I need unified observability across all interfaces"
-Hold mister hastighed, når de sammensætter flere ad-hoc-tjenester og scripts. +Splitting observability by protocol creates blind spots and longer MTTR. -**Sådan løser OmniRoute det:** +**How OmniRoute solves it:** -- Ensartet slutpunktsstrategi for kunder og agenter -- Indbygget protokolstyring UI'er og røgvalideringsstier -- Produktionsklare fundamenter (sikkerhed, logning, robusthed, backup) +- 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"
-**Playbook A: Maksimer betalt abonnement + billig backup** +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 + +
+
+
+### Example Playbooks (Integrated Use Cases)
+
+**Playbook A: Maximize paid subscription + cheap backup**
```txt
Combo: "maximize-claude"
@@ -626,7 +694,7 @@ Monthly cost: $20 + small backup spend
Outcome: higher quality, near-zero interruption
```
-**Playbook B: Gratis kodningsstak**
+**Playbook B: Zero-cost coding stack**
```txt
Combo: "free-forever"
@@ -638,7 +706,7 @@ Monthly cost: $0
Outcome: stable free coding workflow
```
-**Playbook C: 24/7 altid aktiv reservekæde**
+**Playbook C: 24/7 always-on fallback chain**
```txt
Combo: "always-on"
@@ -651,37 +719,61 @@ Combo: "always-on"
Outcome: deep fallback depth for deadline-critical workloads
```
-**Playbook D: Agent ops med MCP + A2A**
+**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/mcp and /dashboard/a2a
-4) Control incidents with resilience profile + task cancellation
+3) Observe via /dashboard/endpoint (MCP and A2A tabs)
+4) Toggle services via inline status controls
```
---
-## ⚡ Hurtig start
+## 🆓 Start Free — Zero Configuration Cost
-### 1) Installer og kør
+> 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 **iFlow** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |
+| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |
+| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |
+| 5 | `/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).
+
+## Kom hurtigt i gang
+
+### 1) Install and run
```bash
npm install -g omniroute
omniroute
```
-Dashboard åbner ved `http://localhost:20128`, og API-base-URL er `http://localhost:20128/v1`.
+> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:
+>
+> ```bash
+> pnpm install -g omniroute
+> pnpm approve-builds -g # Select all packages → approve
+> omniroute
+> ```
-| Kommando | Beskrivelse |
+Dashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.
+
+| Command | Description |
| ----------------------- | ----------------------------------------------------------- |
-| `omniroute` | Start server (`PORT=20128`, API og dashboard på samme port) |
-| `omniroute --port 3000` | Indstil kanonisk/API-port til 3000 |
-| `omniroute --mcp` | Start MCP-server (stdio-transport) |
-| `omniroute --no-open` | Åbn ikke browseren automatisk |
-| `omniroute --help` | Vis hjælp |
+| `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 |
-Valgfri split-port-tilstand:
+Optional split-port mode:
```bash
PORT=20128 DASHBOARD_PORT=20129 omniroute
@@ -689,13 +781,13 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
# Dashboard: http://localhost:20129
```
-### 2) Tilslut udbydere og opret din API-nøgle
+### 2) Connect providers and create your API key
-1. Åbn Dashboard → `Providers` og tilslut mindst én udbyder (OAuth- eller API-nøgle).
-2. Åbn Dashboard → `Endpoint` og opret en API-nøgle.
-3. (Valgfrit) Åbn Dashboard → `Combos` og indstil din reservekæde.
+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) Peg dit kodningsværktøj til OmniRoute
+### 3) Point your coding tool to OmniRoute
```txt
Base URL: http://localhost:20128/v1
@@ -703,22 +795,22 @@ API Key: [copy from Endpoint page]
Model: if/kimi-k2-thinking (or any provider/model prefix)
```
-Fungerer med Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode og OpenAI-kompatible SDK'er.
+Works with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.
-### 4) Aktiver og valider protokoller (v2.0)
+### 4) Enable and validate protocols (v2.0)
-**MCP (til værktøjsdrevne operationer):**
+**MCP (for tool-driven operations):**
```bash
omniroute --mcp
```
-Tilslut derefter din MCP-klient over `stdio` og test værktøjer som:
+Then connect your MCP client over `stdio` and test tools like:
- `omniroute_get_health`
- `omniroute_list_combos`
-**A2A (for agent-til-agent arbejdsgange):**
+**A2A (for agent-to-agent workflows):**
```bash
curl http://localhost:20128/.well-known/agent.json
@@ -730,15 +822,15 @@ curl -X POST http://localhost:20128/a2a \
-d '{"jsonrpc":"2.0","id":"quickstart","method":"message/send","params":{"skill":"quota-management","messages":[{"role":"user","content":"Give me a short quota summary."}]}}'
```
-### 5) Valider alt ende-til-ende (anbefales)
+### 5) Validate everything end-to-end (recommended)
```bash
npm run test:protocols:e2e
```
-Denne suite validerer rigtige MCP- og A2A-klientstrømme mod en kørende app.
+This suite validates real MCP and A2A client flows against a running app.
-### Alternativ: Kør fra kilden
+### Alternative: run from source
```bash
cp .env.example .env
@@ -750,9 +842,9 @@ PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm
## 🐳 Docker
-OmniRoute er tilgængelig som et offentligt Docker-billede på [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
+OmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
-**Hurtigt løb:**
+**Quick run:**
```bash
docker run -d \
@@ -763,7 +855,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Med miljøfil:**
+**With environment file:**
```bash
# Copy and edit .env first
@@ -778,7 +870,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Brug af Docker Compose:**
+**Using Docker Compose:**
```bash
# Base profile (no CLI tools)
@@ -788,24 +880,63 @@ docker compose --profile base up -d
docker compose --profile cli up -d
```
-| Billede | Tag | Størrelse | Beskrivelse |
-| ------------------------ | -------- | --------- | ------------------------- |
-| `diegosouzapw/omniroute` | `latest` | ~250MB | Seneste stabile udgivelse |
-| `diegosouzapw/omniroute` | `1.0.3` | ~250MB | Nuværende version |
+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.
+- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.
+- 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` | `1.0.3` | ~250MB | Current version |
---
-## 🖥️
+## 🖥️ Desktop App — Offline & Always-On
-Kør OmniRoute som en selvstændig desktop-app - ingen terminal, ingen browser, intet internet påkrævet for lokale modeller. Den elektronbaserede app inkluderer:
+> 🆕 **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.
-- 🖥️ **Native Window** — Dedikeret appvindue med systembakkeintegration
-- 🔄 **Auto-Start** — Start OmniRoute ved systemlogin
-- 🔔 **Native notifikationer** — Få advarsler om kvoteopbrugt eller udbyderproblemer
+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-tilstand** — Fungerer fuldt ud offline med medfølgende server
+- 🌐 **Offline Mode** — Works fully offline with bundled server
-### Hurtig start
+### Kom hurtigt i gang
```bash
# Development mode
@@ -818,136 +949,348 @@ npm run electron:build:mac # macOS (.dmg) — x64 & arm64
npm run electron:build:linux # Linux (.AppImage)
```
-### Systembakke
+### System Tray
-Når den er minimeret, lever OmniRoute i din procesbakke med hurtige handlinger:
+When minimized, OmniRoute lives in your system tray with quick actions:
-- Åbn instrumentbrættet
-- Skift serverport
-- Afslut programmet
+- Open dashboard
+- Change server port
+- Quit application
-📖 Fuld dokumentation: [`electron/README.md`](electron/README.md)
+📖 Full documentation: [`electron/README.md`](electron/README.md)
---
-## 💰 Prissætning på et øjeblik
+## 💰 Pricing at a Glance
-| Tier | Udbyder | Omkostninger | Kvote nulstil | Bedst til |
-| ----------------- | ----------------- | --------------------------- | ------------------ | -------------------------- |
-| **💳 ABONNEMENT** | Claude Code (Pro) | 20 USD/md. | 5 timer + ugentlig | Allerede abonneret |
-| | Codex (Plus/Pro) | $20-200/md. | 5 timer + ugentlig | OpenAI-brugere |
-| | Gemini CLI | **GRATIS** | 180K/md + 1K/dag | Alle sammen! |
-| | GitHub Copilot | $10-19/md. | Månedlig | GitHub-brugere |
-| **🔑 API NØGLE** | NVIDIA NIM | **GRATIS** (1000 kreditter) | Engangs | Gratis tier test |
-| | DeepSeek | Betal pr. brug | Ingen | Bedste pris/kvalitet |
-| | Groq | Gratis niveau + betalt | Sats begrænset | Ultrahurtig slutning |
-| | xAI (Grok) | Betal pr. brug | Ingen | Grok modeller |
-| | Mistral | Gratis niveau + betalt | Sats begrænset | Europæisk AI |
-| | OpenRouter | Betal pr. brug | Ingen | 100+ modeller |
-| **💰 BILLIG** | GLM-4.7 | 0,6 USD/1 mio. | Dagligt 10:00 | Budget backup |
-| | MiniMax M2.1 | $0,2/1 mio. | 5-timers rullende | Billigste mulighed |
-| | Kimi K2 | 9 USD/md. lejlighed | 10M tokens/md. | Forudsigelige omkostninger |
-| **🆓 GRATIS** | iFlow | $0 | Ubegrænset | 8 modeller gratis |
-| | Qwen | $0 | Ubegrænset | 3 modeller gratis |
-| | Kiro | $0 | Ubegrænset | Claude gratis |
+| 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 |
+| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |
+| | 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** | iFlow | **$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 |
-**💡 Pro-tip:** Start med Gemini CLI (180K gratis/måned) + iFlow (ubegrænset gratis) combo = $0 omkostninger!
+> 🆕 **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
+iFlow (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.
---
-## 💡 Nøglefunktioner
+---
-OmniRoute v2.0 er bygget som en operationel platform, ikke kun en relæ-proxy.
+## 🆓 Free Models — What You Actually Get
-### 🤖 Agent- og protokoloperationer (v2.0)| Funktion | Hvad det gør |
+> 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.
-| ------------------------------------ | ---------------------------------------------------------------------------------- |
-| 🔧 **MCP-server (16 værktøjer)** | IDE/agent-værktøjer kontrollerer routing, sundhed, kombinationer, grænser og operationer | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`)
-| 🤝 **A2A-server (JSON-RPC + SSE)** | Agent-til-agent opgaveudførelse med synkronisering og streaming flows |
-| 🧭 **Consolidated Endpoints Page** | Dedikerede administrationssider (`/dashboard/mcp`, `/dashboard/a2a`) |
-| 🎚️ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |
-| 🛰️ **MCP Runtime Heartbeat** | Reel processtatus (pid, oppetid, hjerteslagsalder, transport, omfangstilstand) |
-| 📋 **MCP Audit Trail** | Filtrerbare revisionslogfiler med succes/fejl og nøgletilskrivning |
-| 🔐 **MCP Scope Enforcement** | 9 granulære omfangstilladelser til kontrolleret værktøjsadgang |
-| 📡 **A2A Task Lifecycle Management** | Liste/filtrere opgaver, inspicere hændelser/artefakter, annullere kørende opgaver |
-| 📋 **Agent Card Discovery** | `/.well-known/agent.json` til klientens automatiske opdagelse |
-| 🧪 **Protokol E2E testsele** | Ægte MCP SDK + A2A klientstrømme i `test:protocols:e2e` |
-| ⚙️ **Driftskontrol** | Switch combo, påfør elasticitetsprofiler, nulstil afbrydere fra én kontrolflade |
+### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)
-### 🧠 Routing og intelligens
+| 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 |
-| Funktion | Hvad det gør |
-| ----------------------------------- | ------------------------------------------------------------------------------- |
-| 🎯 **Smart 4-lags fallback** | Auto-rute: Abonnement → API-nøgle → Billig → Gratis |
-| 📊 **Kvotesporing i realtid** | Live token count + nulstil nedtælling pr. udbyder |
-| 🔄 **Formatoversættelse** | OpenAI ↔ Claude ↔ Gemini ↔ Svar med skemasikre konverteringer |
-| 👥 **Multi-Account Support** | Flere konti pr. udbyder med intelligent valg |
-| 🔄 **Automatisk token-opdatering** | OAuth-tokens opdateres automatisk med genforsøg |
-| 🎨 **Tilpassede kombinationer** | 6 balanceringsstrategier + fallback kædekontrol |
-| 🌐 **Wildcard-router** | `provider/*` dynamisk routing |
-| 🧠 **Tænker på budgetkontrol** | Grænser for gennemstrømning, automatisk, brugerdefineret og adaptiv ræsonnement |
-| 🔀 **Modelaliaser** | Indbygget + brugerdefineret model aliasing og migration sikkerhed |
-| ⚡ **Baggrundsforringelse** | Send baggrundsopgaver med lav prioritet til billigere modeller |
-| 💬 **System Prompt Injection** | Globale adfærdskontroller anvendes konsekvent |
-| 📄 **Responses API-kompatibilitet** | Fuld `/v1/responses`-understøttelse af Codex og avancerede agentarbejdsgange |
+### 🟢 IFLOW MODELS (Free OAuth — No Credit Card)
-### 🎵 Multi-Modal API'er
+| 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 |
-| Funktion | Hvad det gør || -------------------------- | -------------------------------------------------------------------- |
-| 🖼️ **Billedgenerering** | `/v1/images/generations` med cloud og lokale backends |
-| 📐 **Indlejringer** | `/v1/embeddings` til søgning og RAG-rørledninger |
-| 🎤 **Lydtransskription** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |
-| 🔊 **Tekst-til-tale** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) |
-| 🎬 **Videogenerering** | `/v1/videos/generations` (ComfyUI + SD WebUI-arbejdsgange) |
-| 🎵 **Music Generation** | `/v1/music/generations` (ComfyUI-arbejdsgange) |
-| 🛡️ **Moderationer** | `/v1/moderations` sikkerhedstjek |
-| 🔀 **Omrangering** | `/v1/rerank` for relevansscoring |
+### 🟡 QWEN MODELS (Device Code Auth)
-### 🛡️ Resiliens, sikkerhed og styring
+| 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) |
-| Funktion | Hvad det gør |
+### 🟣 GEMINI CLI (Google OAuth)
+
+| Model | Prefix | Limit | Rate Limit |
+| ------------------------ | ------ | --------------------------- | ------------- |
+| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |
+| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |
+
+### ⚫ 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
+> iFlow (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 v2.0 is built as an operational platform, not just a relay proxy.
+
+### 🆕 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 Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |
+| 🤖 **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 (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) |
+| 🤝 **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** | 9 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 combo, apply resilience profiles, reset breakers from one control surface |
+
+### 🧠 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** | 6 balancing strategies + fallback chain control |
+| 🌐 **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) |
+| 💬 **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 |
| ----------------------------------- | -------------------------------------------------------------------------------------- |
-| 🔌 **Maksimalafbrydere** | Trip/recover på udbyderniveau med tærskelkontrol |
-| 🛡️ **Anti-tordenbesætning** | Mutex + semaforbeskyttelse ved genforsøg/rate hændelser |
-| 🧠 **Semantisk + signaturcache** | Reduktion af omkostninger/latens med to cachelag |
-| ⚡ **Anmod om idempotens** | Dobbelt beskyttelsesvindue |
-| 🔒 **TLS Fingerprint Spoofing** | Bedre kompatibilitet med anti-bot-filtrerede udbydere |
+| 🔌 **Circuit Breakers** | Per-model trip/recover with threshold controls |
+| 🎯 **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-filtrering** | Tilladelsesliste/blokeringslistekontrol for udsatte implementeringer |
-| 📊 **Redigerbare satsgrænser** | Konfigurerbare grænser på globalt niveau/udbyderniveau med persistens |
-| 🔑 **API Key Management + Scoping** | Sikker nøgleudstedelse/rotation og model-/leverandørkontrol |
-| 🛡️ **Beskyttet `/models`** | Valgfri godkendelse og udbyderskjul til modelkatalog |
+| 🌐 **IP Filtering** | Allowlist/blocklist control for exposed deployments |
+| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |
+| 🔑 **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 |
-### 📊 Observerbarhed og analyse
+### 📊 Observability & Analytics
-| Funktion | Hvad det gør |
-| ---------------------------------- | ------------------------------------------------------ |
-| 📝 **Forespørgsel + Proxylogning** | Fuld anmodning/svar og proxy-logning |
-| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |
-| 📋 **Unified Logs Dashboard** | Anmodning, proxy, revision og konsolvisning på én side |
-| 🔍 **Anmod om telemetri** | p50/p95/p99 latens og anmodningssporing |
-| 🏥 **Sundhedskontrolpanel** | Oppetid, breaker-tilstande, lockouts, cache-statistik |
-| 💰 **Omkostningssporing** | Budgetkontrol og prisfastsættelse pr. model |
-| 📈 **Analytiske visualiseringer** | Model-/udbyderbrugsindsigt og trendvisninger |
-| 🧪 **Evalueringsramme** | Gyldne sæt-test med konfigurerbare matchstrategier |
+| Feature | What It Does |
+| -------------------------------- | ----------------------------------------------------- |
+| 📝 **Request + Proxy Logging** | Full request/response and proxy logging |
+| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |
+| 📋 **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 |
-### ☁️ Implementering og platform
+### ☁️ Deployment & Platform
-| Funktion | Hvad det gør |
-| -------------------------------------- | -------------------------------------------------------------- | --- | ----------------- | ------------------------------------------------ |
-| 🌐 **Deploy hvor som helst** | Localhost, VPS, Docker, Cloud-miljøer | | 💾 **Cloud Sync** | Synkronisering af konfiguration via cloud worker |
-| 🔄 **Sikkerhedskopiering/gendannelse** | Eksport/import og gendannelsesstrømme |
-| 🧙 **Onboarding Wizard** | Første kørsel guidet opsætning |
-| 🔧 **CLI Tools Dashboard** | Et-klik opsætning til populære kodningsværktøjer |
-| 🌐 **i18n (30 sprog)** | Fuldt dashboard + understøttelse af docs-sprog med RTL-dækning |
-| 🧹 **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 |
-| 📂 **Tilpasset datakatalog** | `DATA_DIR` tilsidesættelse af lagerplacering |
+| Feature | What It Does |
+| ----------------------------- | --------------------------------------------------------- |
+| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |
+| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |
+| 💾 **Cloud Sync** | Configuration sync via cloud worker |
+| 🔄 **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 |
### Feature Deep Dive
-#### Smart fallback med praktisk omkostningskontrol
+#### Smart fallback with practical cost control
```txt
Combo: "my-coding-stack"
@@ -957,73 +1300,73 @@ Combo: "my-coding-stack"
4. if/kimi-k2-thinking
```
-Når kvote, sats eller sundhed svigter, flytter OmniRoute automatisk til den næste kandidat uden manuel skift.
+When quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.
-#### Protokolstyring, der er synlig og funktionsdygtig
+#### Protocol management that is visible and operable
-- MCP + A2A kan findes i brugergrænsefladen og dokumenter (ikke skjult)
-- Protokolstatus API'er afslører live driftsdata (`/api/mcp/*`, `/api/a2a/*`)
-- Dashboards inkluderer handlinger for dag-2 operationer (kombinationsskift, nulstilling af breaker, annullering af opgave)
+- 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)
-#### Oversætter + valideringsarbejdsgang
+#### Translator + validation workflow
-Oversætterområdet omfatter:
+The Translator area includes:
-- **Legeplads**: anmod om transformationstjek
-- **Chattester**: fuld anmodning/svar tur/retur
-- **Testbænk**: flere sager på én gang
-- **Live Monitor**: trafikvisning i realtid
+- **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 protokolvalidering med rigtige klienter via `npm run test:protocols:e2e`.
+Plus protocol validation with real clients via `npm run test:protocols:e2e`.
-> 📖 **[MCP Server README](open-sse/mcp-server/README.md)** — Værktøjsreference, IDE-konfigurationer og klienteksempler
+> 📖 **[MCP Server README](open-sse/mcp-server/README.md)** — Tool reference, IDE configs, and client examples
>
-> 📖 **[A2A Server README](src/lib/a2a/README.md)** — Færdigheder, JSON-RPC-metoder, streaming og opgavelivscyklus
+> 📖 **[A2A Server README](src/lib/a2a/README.md)** — Skills, JSON-RPC methods, streaming, and task lifecycle
-## 🧪 Evalueringer (evalueringer)
+## 🧪 Evaluations (Evals)
-OmniRoute inkluderer en indbygget evalueringsramme til at teste LLM-svarkvaliteten mod et gyldent sæt. Få adgang til det via **Analytics → Evals** i dashboardet.
+OmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics → Evals** in the dashboard.
-### Indbygget gyldent sæt
+### Built-in Golden Set
-Det forudindlæste "OmniRoute Golden Set" indeholder testcases til:
+The pre-loaded "OmniRoute Golden Set" contains test cases for:
-- Hilsen, matematik, geografi, kodegenerering
-- JSON format compliance, oversættelse, markdown generation
-- Sikkerhedsafvisning (skadeligt indhold), optælling, boolsk logik
+- Greetings, math, geography, code generation
+- JSON format compliance, translation, markdown generation
+- Safety refusal (harmful content), counting, boolean logic
-### Evalueringsstrategier
+### Evaluation Strategies
-| Strategi | Beskrivelse | Eksempel |
-| ---------- | ----------------------------------------------------------------------- | -------------------------------- |
-| `exact` | Output skal matche nøjagtigt | `"4"` |
-| `contains` | Output skal indeholde understreng (uafhængig af store og små bogstaver) | `"Paris"` |
-| `regex` | Output skal matche regex-mønster | `"1.*2.*3"` |
-| `custom` | Brugerdefineret JS-funktion returnerer sand/falsk | `(output) => output.length > 10` |
+| 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` |
---
-## 📖 Opsætningsvejledning
+## 📖 Setup Guide
-### Protokolopsætning (MCP + A2A)
+### Protocol Setup (MCP + A2A)
🚀 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) + +
-
-🧩 MCP-opsætning (modelkontekstprotokol)
+🧩 MCP Setup (Model Context Protocol)
-Start MCP-transport i stdio-tilstand: +Start MCP transport in stdio mode: ```bash omniroute --mcp ``` -Anbefalet valideringsflow: +Recommended validation flow: -1. Tilslut din MCP-klient via stdio. -2. Kør `omniroute_get_health`. -3. Kør `omniroute_list_combos`. -4. Åbn `/dashboard/mcp` for at bekræfte hjerteslag, aktivitet og audit. +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. -Nyttige API'er til automatisering: +Useful APIs for automation: - `GET /api/mcp/status` - `GET /api/mcp/tools` @@ -1032,15 +1375,16 @@ Nyttige API'er til automatisering:🤝 A2A-opsætning (Agent2Agent)
+
+
🤝 A2A Setup (Agent2Agent)
-Opdag agenten: +Discover the agent: ```bash curl http://localhost:20128/.well-known/agent.json ``` -Send en opgave: +Send a task: ```bash curl -X POST http://localhost:20128/a2a \ @@ -1048,38 +1392,38 @@ curl -X POST http://localhost:20128/a2a \ -d '{"jsonrpc":"2.0","id":"setup-a2a","method":"message/send","params":{"skill":"quota-management","messages":[{"role":"user","content":"Summarize quota status."}]}}' ``` -Administrer livscyklus: +Manage lifecycle: - `GET /api/a2a/status` - `GET /api/a2a/tasks` - `GET /api/a2a/tasks/:id` - `POST /api/a2a/tasks/:id/cancel` -Operationel UI: +Operational UI: -- `/dashboard/a2a` til observerbarhed af opgave/tilstand/strøm og røghandlinger +- `/dashboard/a2a` for task/state/stream observability and smoke actions
-
🧪 End-to-end protokolvalidering
+🧪 End-to-end protocol validation
-Valider begge protokoller med rigtige klienter: +Validate both protocols with real clients: ```bash npm run test:protocols:e2e ``` -Dette verificerer: +This verifies: -- MCP SDK-klient forbinde/liste/opkald -- A2A opdagelse/send/stream/hent/annuller -- Krydstjek data i MCP-audit og A2A opgavestyring API'er +- MCP SDK client connect/list/call +- A2A discovery/send/stream/get/cancel +- Cross-check data in MCP audit and A2A task management APIs
-
💳 Abonnementsudbydere
+💳 Subscription Providers
### Claude Code (Pro/Max) @@ -1094,7 +1438,7 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Prof tip:** Brug Opus til komplekse opgaver, Sonnet for hurtighed. OmniRoute sporer kvote pr. model! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! ### OpenAI Codex (Plus/Pro) @@ -1108,7 +1452,24 @@ Models: cx/gpt-5.1-codex-max ``` -### Gemini CLI (GRATIS 180K/måned!) +#### 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). + +### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -1120,7 +1481,7 @@ Models: gc/gemini-2.5-pro ``` -**Bedste værdi:** Kæmpe gratis niveau! Brug dette før betalte niveauer. +**Best Value:** Huge free tier! Use this before paid tiers. ### GitHub Copilot @@ -1138,103 +1499,103 @@ Models:
-
🔑 API nøgleudbydere
+🔑 API Key Providers
-### NVIDIA NIM (GRATIS 1000 kreditter!) +### NVIDIA NIM (FREE developer access — 70+ models) -1. Tilmeld dig: [build.nvidia.com](https://build.nvidia.com) -2. Få gratis API-nøgle (1000 slutningskreditter inkluderet) -3. Dashboard → Tilføj udbyder → NVIDIA NIM: - - API-nøgle: `nvapi-your-key` +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` -**Modeller:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct` og 50+ flere +**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more -**Prof tip:** OpenAI-kompatibel API — fungerer problemfrit med OmniRoutes formatoversættelse! +**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation! ### DeepSeek -1. Tilmeld dig: [platform.deepseek.com](https://platform.deepseek.com) -2. Hent API-nøgle -3. Dashboard → Tilføj udbyder → DeepSeek +1. Sign up: [platform.deepseek.com](https://platform.deepseek.com) +2. Get API key +3. Dashboard → Add Provider → DeepSeek -**Modeller:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` +**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` -### Groq (gratis niveau tilgængelig!) +### Groq (Free Tier Available!) -1. Tilmeld dig: [console.groq.com](https://console.groq.com) -2. Få API-nøgle (gratis niveau inkluderet) -3. Dashboard → Tilføj udbyder → Groq +1. Sign up: [console.groq.com](https://console.groq.com) +2. Get API key (free tier included) +3. Dashboard → Add Provider → Groq -**Modeller:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` +**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` -**Prof tip:** Ultrahurtig slutning — bedst til realtidskodning! +**Pro Tip:** Ultra-fast inference — best for real-time coding! -### OpenRouter (100+ modeller) +### OpenRouter (100+ Models) -1. Tilmeld dig: [openrouter.ai](https://openrouter.ai) -2. Hent API-nøgle -3. Dashboard → Tilføj udbyder → OpenRouter +1. Sign up: [openrouter.ai](https://openrouter.ai) +2. Get API key +3. Dashboard → Add Provider → OpenRouter -**Modeller:** Få adgang til mere end 100 modeller fra alle større udbydere via en enkelt API-nøgle. +**Models:** Access 100+ models from all major providers through a single API key.
-
💰 Billige udbydere (backup)
+💰 Cheap Providers (Backup)
-### GLM-4.7 (Daglig nulstilling, $0,6/1 mio.) +### GLM-4.7 (Daily reset, $0.6/1M) -1. Tilmeld dig: [Zhipu AI](https://open.bigmodel.cn/) -2. Hent API-nøgle fra Coding Plan -3. Dashboard → Tilføj API-nøgle: - - Udbyder: `glm` - - API-nøgle: `your-key` +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` -**Brug:** `glm/glm-4.7` +**Use:** `glm/glm-4.7` -**Pro-tip:** Coding Plan tilbyder 3× kvote til 1/7 pris! Nulstil dagligt 10:00. +**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -### MiniMax M2.1 (5 timers nulstilling, $0,20/1 mio.) +### MiniMax M2.1 (5h reset, $0.20/1M) -1. Tilmeld dig: [MiniMax](https://www.minimax.io/) -2. Hent API-nøgle -3. Dashboard → Tilføj API-nøgle +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key +3. Dashboard → Add API Key -**Brug:** `minimax/MiniMax-M2.1` +**Use:** `minimax/MiniMax-M2.1` -**Prof tip:** Billigste mulighed for lang sammenhæng (1M tokens)! +**Pro Tip:** Cheapest option for long context (1M tokens)! -### Kimi K2 ($9/måned lejlighed) +### Kimi K2 ($9/month flat) -1. Abonner: [Moonshot AI](https://platform.moonshot.ai/) -2. Hent API-nøgle -3. Dashboard → Tilføj API-nøgle +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key +3. Dashboard → Add API Key -**Brug:** `kimi/kimi-latest` +**Use:** `kimi/kimi-latest` -**Prof tip:** Fast $9/måned for 10M tokens = $0,90/1M effektive omkostninger! +**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
-
🆓 GRATIS udbydere (nødbackup)
+🆓 FREE Providers (Emergency Backup)
-### iFlow (8 GRATIS modeller)```bash +### iFlow (5 FREE models via OAuth) +```bash Dashboard → Connect iFlow → iFlow OAuth login → Unlimited usage Models: -if/kimi-k2-thinking -if/qwen3-coder-plus -if/glm-4.7 -if/minimax-m2 -if/deepseek-r1 + if/kimi-k2-thinking + if/qwen3-coder-plus + if/glm-4.7 + if/minimax-m2 + if/deepseek-r1 +``` -```` - -### Qwen (3 GRATIS modeller) +### Qwen (4 FREE models via Device Code) ```bash Dashboard → Connect Qwen @@ -1244,9 +1605,9 @@ Dashboard → Connect Qwen Models: qw/qwen3-coder-plus qw/qwen3-coder-flash -```` +``` -### Kiro (Claude GRATIS) +### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro @@ -1261,9 +1622,9 @@ Models:
-
🎨 Opret kombinationer
+🎨 Create Combos
-### Eksempel 1: Maksimer abonnement → Billig backup +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -1277,7 +1638,7 @@ Models: Use in CLI: premium-coding ``` -### Eksempel 2: Kun gratis (nul omkostninger) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -1292,9 +1653,9 @@ Cost: $0 forever!
-
---
-## 🐛 Fejlfinding
+## Fejlfinding
🔧 CLI-integration
+🔧 CLI Integration
-### Markør IDE +### Cursor IDE ``` Settings → Models → Advanced: @@ -1305,7 +1666,7 @@ Settings → Models → Advanced: ### Claude Code -Brug siden **CLI Tools** i dashboardet til konfiguration med et enkelt klik, eller rediger `~/.claude/settings.json` manuelt. +Use the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually. ### Codex CLI @@ -1318,13 +1679,13 @@ codex "your prompt" ### OpenClaw -**Mulighed 1 — Dashboard (anbefalet):** +**Option 1 — Dashboard (recommended):** ``` Dashboard → CLI Tools → OpenClaw → Select Model → Apply ``` -**Mulighed 2 — Manuel:** Rediger `~/.openclaw/openclaw.json`: +**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`: ```json { @@ -1340,9 +1701,9 @@ Dashboard → CLI Tools → OpenClaw → Select Model → Apply } ``` -> **Bemærk:** OpenClaw fungerer kun med lokale OmniRoute. Brug `127.0.0.1` i stedet for `localhost` for at undgå problemer med IPv6-opløsning. +> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues. -### Cline / Fortsæt / RooCode +### Cline / Continue / RooCode ``` Settings → API Configuration: @@ -1354,7 +1715,7 @@ Settings → API Configuration: ### OpenCode -**Trin 1:** Tilføj OmniRoute som en tilpasset udbyder: +**Step 1:** Add OmniRoute as a custom provider: ```bash opencode @@ -1362,7 +1723,7 @@ opencode # Select "Other" → Enter ID: "omniroute" → Enter your OmniRoute API key ``` -**Trin 2:** Opret/rediger `opencode.json` i dit projektrod: +**Step 2:** Create/edit `opencode.json` in your project root: ```json { @@ -1384,120 +1745,213 @@ opencode } ``` -**Trin 3:** Vælg modellen i OpenCode: +**Step 3:** Select the model in OpenCode: ```bash /models # Select any OmniRoute model from the list ``` -> **Tip:** Tilføj enhver tilgængelig model i dit OmniRoute `/v1/models`-endepunkt til `models`-sektionen. Brug formatet `provider/model-id` fra dit OmniRoute-dashboard. +> **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.
-
+
+## 🛠️ Tech Stack
Klik for at udvide fejlfindingsvejledning
+Click to expand troubleshooting guide
-**"Sprogmodellen leverede ikke beskeder"** +**"Language model did not provide messages"** -- Udbyderkvote opbrugt → Tjek dashboardkvotesporing -- Løsning: Brug combo fallback eller skift til et billigere niveau +- Provider quota exhausted → Check dashboard quota tracker +- Solution: Use combo fallback or switch to cheaper tier -**Satsbegrænsende** +**Rate limiting** -- Abonnementskontingent ude → Fallback til GLM/MiniMax -- Tilføj kombination: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Subscription quota out → Fallback to GLM/MiniMax +- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -**OAuth-token er udløbet** +**OAuth token expired** -- Automatisk genopfrisket af OmniRoute -- Hvis problemerne fortsætter: Dashboard → Udbyder → Genopret forbindelse +- Auto-refreshed by OmniRoute +- If issues persist: Dashboard → Provider → Reconnect -**Høje omkostninger** +**High costs** -- Tjek brugsstatistik i Dashboard → Omkostninger -- Skift primær model til GLM/MiniMax -- Brug gratis niveau (Gemini CLI, iFlow) til ikke-kritiske opgaver +- Check usage stats in Dashboard → Costs +- Switch primary model to GLM/MiniMax +- Use free tier (Gemini CLI, iFlow) for non-critical tasks -**Dashboard/API-porte er forkerte** +**Dashboard/API ports are wrong** -- `PORT` er den kanoniske basisport (og API-port som standard) -- `API_PORT` tilsidesætter kun OpenAI-kompatibel API-lytter -- `DASHBOARD_PORT` tilsidesætter kun dashboard/Next.js-lytter -- Indstil `NEXT_PUBLIC_BASE_URL` til dit dashboard/offentlige URL (til OAuth-tilbagekald) +- `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) -**Skysynkroniseringsfejl** +**Cloud sync errors** -- Bekræft, at `BASE_URL` peger på din kørende instans -- Bekræft `CLOUD_URL`-punkter til dit forventede cloud-endepunkt -- Hold `NEXT_PUBLIC_*`-værdier på linje med værdier på serversiden +- 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 -**Første login virker ikke** +**First login not working** -- Tjek `INITIAL_PASSWORD` i `.env` -- Hvis den ikke er indstillet, er reserveadgangskoden `123456` +- Check `INITIAL_PASSWORD` in `.env` +- If unset, fallback password is `123456` -**Ingen anmodningslogfiler** +**No request logs** -- Indstil `ENABLE_REQUEST_LOGS=true` i `.env` +- Set `ENABLE_REQUEST_LOGS=true` in `.env` -**Forbindelsestest viser "Ugyldig" for OpenAI-kompatible udbydere** +**Connection test shows "Invalid" for OpenAI-compatible providers** -- Mange udbydere eksponerer ikke et `/models`-endepunkt -- OmniRoute v1.0.6+ inkluderer fallback-validering via chatafslutninger -- Sørg for, at basis-URL inkluderer `/v1` suffiks +- 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 +### 🔐 OAuth on a Remote Server + -> **⚠️ VIGTIGT til brugere af OmniRoute med VPS/Docker/server-fjernbetjening** +> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server** -#### OAuth +#### Why does Antigravity / Gemini CLI OAuth fail on remote servers? -Som credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google afviser en autenticação com: +The **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console. + +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 ``` -#### Løsning: Konfigurer OAuth-tilgængelighed +#### Solution: Configure your own OAuth credentials -Você precisa criar um **OAuth 2.0 Client ID** ingen Google Cloud Console med en URI, der udfører denne service. +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 + +# For Gemini CLI: +GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com +GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +``` + +**6. Restart OmniRoute** + +```bash +# npm: +npm run dev + +# Docker: +docker restart omniroute +``` + +**7. Try connecting again** + +Dashboard → Providers → Antigravity (or Gemini CLI) → OAuth + +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. + +--- + +
+
---
-## 🛠️
+🇧🇷 Versão em Português
+ +#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos? + +Os provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo. + +As credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticação com: + +``` +Error 400: redirect_uri_mismatch +``` + +#### Solução: Configure suas próprias credenciais OAuth + +Você precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor. #### Passo a passo -**1. Adgang til Google Cloud Console** +**1. Acesse o Google Cloud Console** Abra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) **2. Crie um novo OAuth 2.0 Client ID** -- Klik på dem **"+ Opret legitimationsoplysninger"** → **"OAuth-klient-id"** -- Tipo de aplicativo: **"Webapplikation"** -- Navn: escolha qualquer nome (eks.: `OmniRoute Remote`) +- Clique em **"+ Create Credentials"** → **"OAuth client ID"** +- Tipo de aplicativo: **"Web application"** +- Nome: escolha qualquer nome (ex: `OmniRoute Remote`) -**3. Adicione som autoriseret omdirigerings-URI** +**3. Adicione as Authorized Redirect URIs** -Ingen campo **"Autoriseret omdirigerings-URI'er"**, adicione: +No campo **"Authorized redirect URIs"**, adicione: ``` https://seu-servidor.com/callback ``` -> Substitua `seu-servidor.com` pelo domínio eller IP do seu servidor (inklusive en porta se necessário, ex: `http://45.33.32.156:20128/callback`). +> Substitua `seu-servidor.com` pelo domínio ou IP do seu servidor (inclua a porta se necessário, ex: `http://45.33.32.156:20128/callback`). -**4. Salve e copy as credenciais** +**4. Salve e copie as credenciais** Após criar, o Google mostrará o **Client ID** e o **Client Secret**. -**5. Konfigurer som variáveis de ambiente** +**5. Configure as variáveis de ambiente** -Ingen seu `.env` (denne variáveis de ambiente do Docker): +No seu `.env` (ou nas variáveis de ambiente do Docker): ```bash # Para Antigravity: @@ -1522,110 +1976,114 @@ docker restart omniroute **7. Tente conectar novamente** -Dashboard → Udbydere → Antigravity (ou Gemini CLI) → OAuth +Dashboard → Providers → Antigravity (ou Gemini CLI) → OAuth -Agora eller Google redirecionará corretamente para `https://seu-servidor.com/callback` og autenticação funcionará. +Agora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará. --- -#### Midlertidig løsning (som konfigureret tiltrods próprias) +#### Workaround temporário (sem configurar credenciais próprias) Se não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**: -1. O OmniRoute abrirá en URL de autorização til Google +1. O OmniRoute abrirá a URL de autorização do Google 2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto) -3. **Kopier en URL komplet** da barra de endereço do sin browser (mesmo que a página não carregue) +3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue) 4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute -5. Klik på **"Forbind"** +5. Clique em **"Connect"** -> Este workaround funciona porque or código de autorização na URL é válido independente do redirect ter carregado or não. +> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.
-
---
-## 📖 Dokumentation
+## Dokumentation
-| Dokument | Beskrivelse |
-| ------------------------------------------------ | ------------------------------------------------------------ |
-| [Brugervejledning](docs/USER_GUIDE.md) | Udbydere, kombinationer, CLI-integration, implementering |
-| [API-reference](docs/API_REFERENCE.md) | Alle endepunkter med eksempler |
-| [MCP-server](open-sse/mcp-server/README.md) | 16 MCP-værktøjer, IDE-konfigurationer, Python/TS/Go-klienter |
-| [A2A-server](src/lib/a2a/README.md) | JSON-RPC 2.0 protokol, færdigheder, streaming, opgavestyring |
-| [Auto-kombimotor](docs/auto-combo.md) | 6-faktor scoring, tilstandspakker, selvhelbredende |
-| [Fejlfinding](docs/TROUBLESHOOTING.md) | Almindelige problemer og løsninger |
-| [Arkitektur](docs/ARCHITECTURE.md) | Systemarkitektur og indre |
-| [Bidrager](CONTRIBUTING.md) | Udviklingsopsætning og retningslinjer |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0-specifikation |
-| [Sikkerhedspolitik](SECURITY.md) | Sårbarhedsrapportering og sikkerhedspraksis |
-| [VM-implementering](docs/VM_DEPLOYMENT_GUIDE.md) | Komplet guide: VM + nginx + Cloudflare opsætning |
-| [Feature Gallery](docs/FEATURES.md) | Visuel dashboard-rundvisning med skærmbilleder |
-| [Udgivelsestjekliste](docs/RELEASE_CHECKLIST.md) | Pre-release valideringstrin |
+| Document | Description |
+| ---------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 16 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/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
+| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
-## 🗺️
+## 🗺️ Roadmap
-OmniRoute har **210+ funktioner planlagt** på tværs af flere udviklingsfaser. Her er nøgleområderne:
+OmniRoute has **210+ features planned** across multiple development phases. Here are the key areas:
-| Kategori | Planlagte funktioner | Højdepunkter |
-| -------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------- |
-| 🧠 **Routing & intelligens** | 25+ | Routing med laveste latens, tag-baseret routing, kvote preflight, valg af P2C-konto |
-| 🔒 **Sikkerhed og overholdelse** | 20+ | SSRF-hærdning, tilsløring af legitimationsoplysninger, hastighedsgrænse pr. slutpunkt, styringsnøgleomfang |
-| 📊 **Observabilitet** | 15+ | OpenTelemetry-integration, kvoteovervågning i realtid, omkostningssporing pr. model |
-| 🔄 **Udbyderintegrationer** | 20+ | Dynamisk modelregistrering, leverandørnedkøling, multi-konto Codex, Copilot-kvoteparsing |
-| ⚡ **Ydeevne** | 15+ | Dobbelt cachelag, promptcache, svarcache, streaming keepalive, batch API |
-| 🌐 **Økosystem** | 10+ | WebSocket API, config hot-reload, distribueret config butik, kommerciel tilstand |
+| Category | Planned Features | Highlights |
+| ----------------------------- | ---------------- | -------------------------------------------------------------------------------------- |
+| 🧠 **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, P2C account selection |
+| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |
+| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |
+| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider 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 |
-### 🔜 Kommer snart- 🔗 **OpenCode-integration** — Native udbyderunderstøttelse af OpenCode AI-kodnings-IDE
+### 🔜 Coming Soon
-- 🔗 **TRAE-integration** — Fuld understøttelse af TRAE AI-udviklingsrammen
-- 📦 **Batch API** — Asynkron batchbehandling til masseanmodninger
-- 🎯 **Tag-baseret Routing** — Ruteanmodninger baseret på tilpassede tags og metadata
-- 💰 **Laveste omkostningsstrategi** — Vælg automatisk den billigste tilgængelige udbyder
+- 🔗 **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
-> 📝 Fuld funktionsspecifikationer tilgængelige i [`docs/new-features/`](docs/new-features/) (217 detaljerede specifikationer)
+> 📝 Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)
---
-## 👥 Bidragydere
+## 👥 Contributors
-[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
+[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
-### Sådan bidrager du
+### How to Contribute
-1. Fork depotet
-2. Opret din funktionsgren (`git checkout -b feature/amazing-feature`)
-3. Bekræft dine ændringer (`git commit -m 'Add amazing feature'`)
-4. Skub til grenen (`git push origin feature/amazing-feature`)
-5. Åbn en pull-anmodning
+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
-Se [CONTRIBUTING.md](CONTRIBUTING.md) for detaljerede retningslinjer.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
-### Frigiver en ny version
+### Releasing a New Version
```bash
# Create a release — npm publish happens automatically
@@ -1634,28 +2092,28 @@ gh release create v2.0.0 --title "v2.0.0" --generate-notes
---
-## 📊 Stjernehistorie
+## 📊 Star History
## Stargazers over time
## [](https://starchart.cc/diegosouzapw/OmniRoute)
-## 🙏 Tak
+## 🙏 Acknowledgments
-Særlig tak til **[9router](https://github.com/decolua/9router)** af **[decolua](https://github.com/decolua)** — det originale projekt, der inspirerede denne gaffel. OmniRoute bygger på det utrolige fundament med yderligere funktioner, multimodale API'er og en fuld TypeScript-omskrivning.
+Special thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.
-Særlig tak til **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — den originale Go-implementering, der inspirerede denne JavaScript-port.
+Special thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.
---
-## 📄 Licens
+## Licens
-MIT-licens - se [LICENS](LICENSE) for detaljer.
+MIT License - see [LICENSE](LICENSE) for details.
---
Klik for at udvide tekniske stakdetaljer
+Click to expand tech stack details
-- **Runtime**: Node.js 18–22 LTS (⚠️ Node.js 24+ er **ikke understøttet** — `better-sqlite3` native binære filer er inkompatible) -- **Sprog**: TypeScript 5.9 — **100 % TypeScript** på tværs af `src/` og `open-sse/` (nul `any` i kernemoduler siden v2.0) +- **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**: LowDB (JSON) + SQLite (domænetilstand + proxylogfiler + MCP-revision + routingbeslutninger) -- **Skemaer**: Zod (MCP-værktøj I/O-validering, API-kontrakter) -- **Protokoller**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE) -- **Streaming**: Server-sendte hændelser (SSE) -- **Auth**: OAuth 2.0 (PKCE) + JWT + API-nøgler + MCP Scoped Authorization -- **Test**: Node.js testløber + Vitest (900+ tests inklusive enhed, integration, E2E)- **CI/CD**: GitHub-handlinger (automatisk npm-udgivelse + Docker Hub ved udgivelse) -- **Websted**: [omniroute.online](https://omniroute.online) -- **Pakke**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute) +- **Database**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions) +- **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) -- **Resiliens**: Circuit breaker, eksponentiel backoff, anti-tordenbesætning, TLS spoofing, auto-combo selvhelbredelse +- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing
- Bygget med ❤️ for udviklere, der koder 24/7
+ Built with ❤️ for developers who code 24/7
omniroute.online
diff --git a/docs/i18n/da/docs/FEATURES.md b/docs/i18n/da/docs/FEATURES.md
new file mode 100644
index 0000000000..f994acabd9
--- /dev/null
+++ b/docs/i18n/da/docs/FEATURES.md
@@ -0,0 +1,145 @@
+# OmniRoute — Dashboard Features Gallery (Dansk)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/FEATURES.md) · 🇪🇸 [es](../../es/docs/FEATURES.md) · 🇫🇷 [fr](../../fr/docs/FEATURES.md) · 🇩🇪 [de](../../de/docs/FEATURES.md) · 🇮🇹 [it](../../it/docs/FEATURES.md) · 🇷🇺 [ru](../../ru/docs/FEATURES.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FEATURES.md) · 🇯🇵 [ja](../../ja/docs/FEATURES.md) · 🇰🇷 [ko](../../ko/docs/FEATURES.md) · 🇸🇦 [ar](../../ar/docs/FEATURES.md) · 🇮🇳 [in](../../in/docs/FEATURES.md) · 🇹🇭 [th](../../th/docs/FEATURES.md) · 🇻🇳 [vi](../../vi/docs/FEATURES.md) · 🇮🇩 [id](../../id/docs/FEATURES.md) · 🇲🇾 [ms](../../ms/docs/FEATURES.md) · 🇳🇱 [nl](../../nl/docs/FEATURES.md) · 🇵🇱 [pl](../../pl/docs/FEATURES.md) · 🇸🇪 [sv](../../sv/docs/FEATURES.md) · 🇳🇴 [no](../../no/docs/FEATURES.md) · 🇩🇰 [da](../../da/docs/FEATURES.md) · 🇫🇮 [fi](../../fi/docs/FEATURES.md) · 🇵🇹 [pt](../../pt/docs/FEATURES.md) · 🇷🇴 [ro](../../ro/docs/FEATURES.md) · 🇭🇺 [hu](../../hu/docs/FEATURES.md) · 🇧🇬 [bg](../../bg/docs/FEATURES.md) · 🇸🇰 [sk](../../sk/docs/FEATURES.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FEATURES.md) · 🇮🇱 [he](../../he/docs/FEATURES.md) · 🇵🇭 [phi](../../phi/docs/FEATURES.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FEATURES.md)
+
+---
+
+Visual guide to every section of the OmniRoute dashboard.
+
+---
+
+## 🔌 Providers
+
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
+
+
+
+---
+
+## 🎨 Combos
+
+Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
+
+
+
+---
+
+## 📊 Analytics
+
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
+
+
+
+---
+
+## 🏥 System Health
+
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+
+
+
+---
+
+## 🔧 Translator Playground
+
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
+
+
+
+---
+
+## 🎮 Model Playground _(v2.0.9+)_
+
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
+
+---
+
+## 🎨 Themes _(v2.0.5+)_
+
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
+
+## ⚙️ Settings
+
+Comprehensive settings panel with tabs:
+
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning
+- **Advanced** — Configuration overrides
+
+
+
+---
+
+## 🔧 CLI Tools
+
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
+
+
+
+---
+
+## 🤖 CLI Agents _(v2.0.11+)_
+
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
+
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
+
+---
+
+## 🖼️ Media _(v2.0.3+)_
+
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
+
+## 📝 Request Logs
+
+Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
+
+
+
+---
+
+## 🌐 API Endpoint
+
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
+
+
+
+---
+
+## 🔑 API Key Management
+
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
+
+---
+
+## 📋 Audit Log
+
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
+
+---
+
+## 🖥️ Desktop Application
+
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
+
+Key features:
+
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
+
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.
diff --git a/docs/i18n/de/README.md b/docs/i18n/de/README.md
index 1b6421132f..d3691ccfd1 100644
--- a/docs/i18n/de/README.md
+++ b/docs/i18n/de/README.md
@@ -1,16 +1,89 @@
-# 🚀 OmniRoute – Das kostenlose KI-Gateway
+# 🚀 OmniRoute — The Free AI Gateway (Deutsch)
-### Hören Sie nie auf zu programmieren. Intelligentes Routing zu **KOSTENLOSEN und kostengünstigen KI-Modellen** mit automatischem Fallback.
-
-_Ihr universeller API-Proxy – ein Endpunkt, mehr als 36 Anbieter, keine Ausfallzeiten. Jetzt mit **MCP & A2A** Agenten-Orchestrierung._
-
-**Chat-Abschlüsse • Einbettungen • Bildgenerierung • Video • Musik • Audio • Reranking • MCP-Server • A2A-Protokoll • 100 % TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Kostenloser KI-Anbieter für Ihre bevorzugten Programmieragenten
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Verbinden Sie jedes KI-gestützte IDE- oder CLI-Tool über OmniRoute – kostenloses API-Gateway für unbegrenzte Codierung._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+omniroute.online
+
+[](https://www.npmjs.com/package/omniroute)
+[](https://www.npmjs.com/package/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
+[](https://omniroute.online)
+[](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)
+
+
+
+🌐 **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)
+
+---
+
+## 🆕 What's New in v3.0.0
+
+> **Upgrading from v2.9.5?** — See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes.
+
+| Area | Change |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection remediation |
+| ✅ **Route Validation** | All 176 API routes now validated with Zod schemas + `validateBody()` — CI `check:route-validation:t06` passes |
+| 🐛 **omniModel Tag Leak** | Internal `
+
+
+
+---
+
+## 📸 Dashboard Preview
+
+
+
+
+
+---
+
+### 🤖 Free AI Provider for your favorite coding agents
+
+_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._
Click to see dashboard screenshots
+ +| Page | Screenshot | +| -------------- | ------------------------------------------------- | +| **Providers** |  | +| **Combos** |  | +| **Analytics** |  | +| **Health** |  | +| **Translator** |  | +| **Settings** |  | +| **CLI Tools** |  | +| **Usage Logs** |  | +| **Endpoints** |  | + +| @@ -81,76 +155,59 @@ _Verbinden Sie jedes KI-gestützte IDE- oder CLI-Tool über OmniRoute – kosten |
- Kilo-Code + Kilo Code ⭐ 15.5K |
http://localhost:20128/v1 oder quote
+📡 All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 — one config, unlimited models and quota
---
-### 🆕 What's New in v3.0.0
+## 🤔 Why OmniRoute?
-| Area | Change |
-| ------------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal ` Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal ` Das Abonnementkontingent läuft jeden Monat ungenutzt ab
-- Ratenbegrenzungen verhindern, dass Sie mitten in der Codierung sind
-- Teure APIs (20–50 $/Monat pro Anbieter)
-- Manueller Wechsel zwischen Anbietern
-
-**OmniRoute löst dieses Problem:**
-
-- ✅ **Abonnements maximieren** - Verfolgen Sie das Kontingent, nutzen Sie jedes Bit vor dem Zurücksetzen
-- ✅ **Auto-Fallback** – Abonnement → API-Schlüssel → Günstig → Kostenlos, keine Ausfallzeiten
-- ✅ **Mehrere Konten** – Round-Robin zwischen Konten pro Anbieter
-- ✅ **Universell** – Funktioniert mit Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw und jedem CLI-Tool
-
----
-
-## 📧 Unterstützung> 💬 **Treten Sie unserer Community bei!** [WhatsApp-Gruppe](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) – Holen Sie sich Hilfe, tauschen Sie Tipps aus und bleiben Sie auf dem Laufenden.
+> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.
- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Probleme**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **WhatsApp**: [Community-Gruppe](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Mitwirken**: Siehe [CONTRIBUTING.md](CONTRIBUTING.md), öffnen Sie eine PR oder wählen Sie eine `good first issue` aus
-- **Originalprojekt**: [9router von decolua](https://github.com/decolua/9router)
+- **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`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 Wie es funktioniert
+## 🔄 How It Works
```
┌─────────────┐
@@ -179,447 +236,453 @@ Result: Never stop coding, minimal cost
---
-## 🎯 Was OmniRoute löst – 30 echte Problempunkte und Anwendungsfälle
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **Jeder Entwickler, der KI-Tools verwendet, ist täglich mit diesen Problemen konfrontiert.** OmniRoute wurde entwickelt, um sie alle zu lösen – von Kostenüberschreitungen bis hin zu regionalen Blockaden, von unterbrochenen OAuth-Flüssen bis hin zu Protokollvorgängen und Unternehmensbeobachtbarkeit.
+> **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.
-
💸 1. „Ich bezahle ein teures Abonnement, werde aber trotzdem durch Limits unterbrochen“
+💸 1. "I pay for an expensive subscription but still get interrupted by limits"
-Entwickler zahlen 20–200 US-Dollar/Monat für Claude Pro, Codex Pro oder GitHub Copilot. Auch wenn das Kontingent bezahlt wird, gibt es eine Obergrenze – 5 Stunden Nutzung, wöchentliche Limits oder Tariflimits pro Minute. Während der Codierungssitzung reagiert der Anbieter nicht mehr und der Entwickler verliert an Fluss und Produktivität. +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. -**So löst OmniRoute das Problem:** +**How OmniRoute solves it:** -- **Intelligenter 4-Stufen-Fallback** – Wenn das Abonnementkontingent aufgebraucht ist, wird automatisch zu API Key → Günstig → Kostenlos weitergeleitet, ohne dass ein manueller Eingriff erforderlich ist -- **Kontingentverfolgung in Echtzeit** – Zeigt den Token-Verbrauch in Echtzeit mit Reset-Countdown an (5 Stunden, täglich, wöchentlich) -- **Unterstützung mehrerer Konten** – Mehrere Konten pro Anbieter mit automatischem Round-Robin – wenn eines aufgebraucht ist, wird zum nächsten gewechselt -- **Benutzerdefinierte Kombinationen** – Anpassbare Fallback-Ketten mit 6 Ausgleichsstrategien (Fill-First, Round-Robin, P2C, Random, Least-Used, Kostenoptimiert) -- **Codex Business Quotas** – Überwachung der Geschäfts-/Team-Arbeitsbereichskontingente direkt im Dashboard +- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention +- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly) +- **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 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
-`-Blöcke aus Modellen wie DeepSeek R1 in das standardisierte `reasoning_content`
-- **Strukturierte Ausgabe für Gemini** – `json_schema` → `responseMimeType`/`responseSchema` automatische Konvertierung
-- **`stream` ist standardmäßig `false`** – Entspricht der OpenAI-Spezifikation und vermeidet unerwartetes SSE in Python/Rust/Go-SDKs
-
-🔌 2. „Ich muss mehrere Anbieter verwenden, aber jeder hat eine andere API“
+🔌 2. "I need to use multiple providers but each has a different API"
-OpenAI verwendet ein Format, Claude (Anthropic) verwendet ein anderes, Gemini noch ein anderes. Wenn ein Entwickler Modelle verschiedener Anbieter testen oder zwischen ihnen wechseln möchte, muss er SDKs neu konfigurieren, Endpunkte ändern und mit inkompatiblen Formaten umgehen. Benutzerdefinierte Anbieter (FriendLI, NIM) verfügen über nicht standardmäßige Modellendpunkte. +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. -**So löst OmniRoute das Problem:** +**How OmniRoute solves it:** -- **Einheitlicher Endpunkt** – Ein einzelner `http://localhost:20128/v1` dient als Proxy für alle über 36 Anbieter -- **Formatübersetzung** – Automatisch und transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API -- **Antwortbereinigung** – Entfernt nicht standardmäßige Felder (`x_groq`, `usage_breakdown`, `service_tier`), die OpenAI SDK v1.83+ beschädigen -- **Rollennormalisierung** – Konvertiert `developer` → `system` für Nicht-OpenAI-Anbieter; `system` → `user` für GLM/ERNIE -- **Think Tag Extraction** – Extrahiert `
-` 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
🌐 3. „Mein KI-Anbieter blockiert meine Region/mein Land“
- -Anbieter wie OpenAI/Codex blockieren den Zugriff aus bestimmten geografischen Regionen. Benutzer erhalten bei OAuth- und API-Verbindungen Fehler wie `unsupported_country_region_territory`. Dies ist besonders frustrierend für Entwickler aus Entwicklungsländern. - -**So löst OmniRoute das Problem:** - -- **3-Level-Proxy-Konfiguration** – Konfigurierbarer Proxy auf 3 Ebenen: global (gesamter Datenverkehr), pro Anbieter (nur ein Anbieter) und pro Verbindung/Schlüssel -- **Farbcodierte Proxy-Abzeichen** – Visuelle Indikatoren: 🟢 globaler Proxy, 🟡 Anbieter-Proxy, 🔵 Verbindungs-Proxy, immer mit IP-Adresse -- **OAuth-Token-Austausch über Proxy** – Der OAuth-Fluss läuft auch über den Proxy und löst `unsupported_country_region_territory` -- **Verbindungstests über Proxy** – Verbindungstests verwenden den konfigurierten Proxy (keine direkte Umgehung mehr) -- **SOCKS5-Unterstützung** – Vollständige SOCKS5-Proxy-Unterstützung für ausgehendes Routing -- **TLS-Fingerabdruck-Spoofing** – Browserähnlicher TLS-Fingerabdruck über `wreq-js` zur Umgehung der Bot-Erkennung +- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 67+ 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 `
-
+
+🆓 4. „Ich möchte KI zum Codieren verwenden, habe aber kein Geld“
+🌐 3. "My AI provider blocks my region/country"
-Nicht jeder kann 20–200 $/Monat für KI-Abonnements bezahlen. Studenten, Entwickler aus Schwellenländern, Bastler und Freiberufler benötigen Zugang zu hochwertigen Modellen zum Nulltarif. +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. -**So löst OmniRoute das Problem:** +**How OmniRoute solves it:** -- **Integrierte kostenlose Anbieter** – Native Unterstützung für 100 % kostenlose Anbieter: iFlow (8 unbegrenzte Modelle), Qwen (3 unbegrenzte Modelle), Kiro (Claude kostenlos), Gemini CLI (180.000/Monat kostenlos) +- **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 + +
+` prefix
-- **Nur kostenlose Combos** – Kette `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = 0 $/Monat ohne Ausfallzeit
-- **NVIDIA NIM Free Credits** – 1000 kostenlose Credits integriert
-- **Kostenoptimierte Strategie** – Routing-Strategie, die automatisch den günstigsten verfügbaren Anbieter auswählt
+- **Free-Only Combos** — Chain `gc/gemini-3-flash → 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
🆓 4. "I want to use AI for coding but I have no money"
+ +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. + +**How OmniRoute solves it:** + +- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free) - **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/
-
🔒 5. „Ich muss mein KI-Gateway vor unbefugtem Zugriff schützen“
+🔒 5. "I need to protect my AI gateway from unauthorized access"
-Wenn ein KI-Gateway dem Netzwerk (LAN, VPS, Docker) zugänglich gemacht wird, kann jeder mit der Adresse die Token/Kontingente des Entwicklers verbrauchen. Ohne Schutz sind APIs anfällig für Missbrauch, sofortige Injektion und Missbrauch. +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. -**So löst OmniRoute das Problem:** +**How OmniRoute solves it:** -- **API-Schlüsselverwaltung** – Generierung, Rotation und Scoping pro Anbieter mit einer dedizierten `/dashboard/api-manager`-Seite -- **Berechtigungen auf Modellebene** – Beschränken Sie API-Schlüssel auf bestimmte Modelle (`openai/*`, Platzhaltermuster) mit der Umschaltfunktion „Alle zulassen/Einschränken“. -- **API Endpoint Protection** – Fordern Sie einen Schlüssel für `/v1/models` an und blockieren Sie bestimmte Anbieter aus der Liste -- **Auth Guard + CSRF-Schutz** – Alle Dashboard-Routen sind mit `withAuth`-Middleware + CSRF-Tokens geschützt -- **Ratenbegrenzer** – Ratenbegrenzung pro IP mit konfigurierbaren Fenstern -- **IP-Filterung** – Zulassungs-/Blockierungsliste für die Zugriffskontrolle -- **Prompt Injection Guard** – Bereinigung gegen bösartige Eingabeaufforderungsmuster -- **AES-256-GCM-Verschlüsselung** – Anmeldeinformationen im Ruhezustand verschlüsselt +- **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. „Mein Provider ist ausgefallen und ich habe meinen Codierungsfluss verloren“
KI-Anbieter können instabil werden, 5xx-Fehler zurückgeben oder vorübergehende Ratengrenzen erreichen. Wenn ein Entwickler von einem einzelnen Anbieter abhängig ist, wird er unterbrochen. Ohne Schutzschalter können wiederholte Versuche zum Absturz der Anwendung führen. +🛑 6. "My provider went down and I lost my coding flow"
-**So löst OmniRoute das Problem:** +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. -- **Leistungsschalter pro Anbieter** – Automatisches Öffnen/Schließen mit konfigurierbaren Schwellenwerten und Abklingzeit (geschlossen/offen/halb offen) -- **Exponentielles Backoff** – Progressive Wiederholungsverzögerungen -- **Anti-Thundering Herd** – Mutex + Semaphor-Schutz gegen gleichzeitige Wiederholungsstürme -- **Combo-Fallback-Ketten** – Wenn der primäre Anbieter ausfällt, fällt er automatisch durch die Kette, ohne dass ein Eingreifen erforderlich ist -- **Combo Circuit Breaker** – Deaktiviert automatisch ausgefallene Anbieter innerhalb einer Combo-Kette - | 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format | -- **Gesundheits-Dashboard** – Betriebszeitüberwachung, Leistungsschalterzustände, Sperren, Cache-Statistiken, p50/p95/p99-Latenz +**How OmniRoute solves it:** + +- **Circuit Breaker per-model** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks +- **Exponential Backoff** — Progressive retry delays +- **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 +- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain +- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
-
🔧 7. „Die Konfiguration jedes KI-Tools ist mühsam und repetitiv“
+🔧 7. "Configuring each AI tool is tedious and repetitive"
-Entwickler verwenden Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code ... Jedes Tool benötigt eine andere Konfiguration (API-Endpunkt, Schlüssel, Modell). Eine Neukonfiguration bei einem Anbieter- oder Modellwechsel ist Zeitverschwendung. +Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time. -**So löst OmniRoute das Problem:** +**How OmniRoute solves it:** -- **CLI Tools Dashboard** – Spezielle Seite mit Ein-Klick-Einrichtung für Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline -- **GitHub Copilot Config Generator** – Generiert `chatLanguageModels.json` für VS-Code mit Massenmodellauswahl -- **Onboarding-Assistent** – Geführte Einrichtung in 4 Schritten für Erstbenutzer -- **Ein Endpunkt, alle Modelle** – Konfigurieren Sie `http://localhost:20128/v1` einmal und greifen Sie auf über 36 Anbieter zu +- **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 67+ providers
-
🔑 8. „OAuth-Tokens von mehreren Anbietern zu verwalten ist die Hölle“
+🔑 8. "Managing OAuth tokens from multiple providers is hell"
-Claude Code, Codex, Gemini CLI, Copilot – alle verwenden OAuth 2.0 mit ablaufenden Token. Entwickler müssen sich ständig neu authentifizieren, sich mit `client_secret is missing`, `redirect_uri_mismatch` und Fehlern auf Remote-Servern auseinandersetzen. Besonders problematisch ist OAuth auf LAN/VPS. +Claude Code, Codex, Gemini CLI, 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. -**So löst OmniRoute das Problem:** +**How OmniRoute solves it:** -- **Automatische Token-Aktualisierung** – OAuth-Tokens werden vor Ablauf im Hintergrund aktualisiert -- **OAuth 2.0 (PKCE) integriert** – Automatischer Ablauf für Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow -- **Multi-Account OAuth** – Mehrere Konten pro Anbieter über JWT/ID-Token-Extraktion -- **OAuth LAN/Remote Fix** – Private IP-Erkennung für `redirect_uri` + manueller URL-Modus für Remote-Server -- **OAuth Behind Nginx** – Verwendet `window.location.origin` für Reverse-Proxy-Kompatibilität -- **Remote OAuth Guide** – Schritt-für-Schritt-Anleitung für Google Cloud-Anmeldeinformationen auf VPS/Docker +- **Auto Token Refresh** — OAuth tokens refresh in background before expiration +- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow +- **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. „Ich weiß nicht, wie viel ich ausgebe oder wo“
+📊 9. "I don't know how much I'm spending or where"
-Entwickler nutzen mehrere kostenpflichtige Anbieter, haben jedoch keine einheitliche Sicht auf die Ausgaben. Jeder Anbieter verfügt über ein eigenes Abrechnungs-Dashboard, es gibt jedoch keine konsolidierte Ansicht. Unerwartete Kosten können sich häufen. +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. -**So löst OmniRoute das Problem:** +**How OmniRoute solves it:** -- **Kostenanalyse-Dashboard** – Kostenverfolgung pro Token und Budgetverwaltung pro Anbieter -- **Budgetgrenzen pro Stufe** – Ausgabenobergrenze pro Stufe, die einen automatischen Fallback auslöst -- **Preiskonfiguration pro Modell** – Konfigurierbare Preise pro Modell- **Nutzungsstatistiken pro API-Schlüssel** – Anzahl der Anfragen und zuletzt verwendeter Zeitstempel pro Schlüssel -- **Analytics-Dashboard** – Statistikkarten, Modellnutzungsdiagramm, Anbietertabelle mit Erfolgsraten und Latenz +- **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. „Ich kann Fehler und Probleme bei KI-Anrufen nicht diagnostizieren“
+🐛 10. "I can't diagnose errors and problems in AI calls"
-Wenn ein Anruf fehlschlägt, weiß der Entwickler nicht, ob es sich um eine Ratenbegrenzung, ein abgelaufenes Token, ein falsches Format oder einen Anbieterfehler handelt. Fragmentierte Protokolle über verschiedene Terminals hinweg. Ohne Beobachtbarkeit ist das Debuggen ein Versuch und Irrtum. +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. -**So löst OmniRoute das Problem:** +**How OmniRoute solves it:** -- **Unified Logs Dashboard** – 4 Registerkarten: Anforderungsprotokolle, Proxy-Protokolle, Audit-Protokolle, Konsole -- **Console Log Viewer** – Echtzeit-Viewer im Terminal-Stil mit farbcodierten Ebenen, automatischem Scrollen, Suche und Filter -- **SQLite-Proxy-Protokolle** – Persistente Protokolle, die Serverneustarts überdauern -- **Translator Playground** – 4 Debugging-Modi: Playground (Formatübersetzung), Chat Tester (Round-Trip), Test Bench (Batch), Live Monitor (Echtzeit) -- **Telemetrie anfordern** – p50/p95/p99-Latenz + X-Request-Id-Ablaufverfolgung -- **Dateibasierte Protokollierung mit Rotation** – Der Konsolen-Interceptor erfasst alles im JSON-Protokoll mit größenbasierter Rotation +- **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 Proxy Logs** — Persistent logs that survive server restarts +- **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 Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation +- **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. „Die Bereitstellung und Wartung des Gateways ist komplex“
+🏗️ 11. "Deploying and maintaining the gateway is complex"
-Die Installation, Konfiguration und Wartung eines KI-Proxys in verschiedenen Umgebungen (lokal, VPS, Docker, Cloud) ist arbeitsintensiv. Probleme wie hartcodierte Pfade, `EACCES` in Verzeichnissen, Portkonflikte und plattformübergreifende Builds sorgen für zusätzliche Reibung. +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. -**So löst OmniRoute das Problem:** +**How OmniRoute solves it:** -- **npm globale Installation** – `npm install -g omniroute && omniroute` – fertig -- **Docker Multi-Platform** – AMD64 + ARM64 nativ (Apple Silicon, AWS Graviton, Raspberry Pi) -- **Docker Compose-Profile** – `base` (keine CLI-Tools) und `cli` (mit Claude Code, Codex, OpenClaw) -- **Electron Desktop App** – Native App für Windows/macOS/Linux mit Taskleiste, Autostart, Offline-Modus -- **Split-Port-Modus** – API und Dashboard auf separaten Ports für erweiterte Szenarien (Reverse-Proxy, Container-Netzwerk) -- **Cloud Sync** – Konfigurieren Sie die geräteübergreifende Synchronisierung über Cloudflare Workers -- **DB-Backups** – Automatische Sicherung, Wiederherstellung, Export und Import aller Einstellungen +- **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
-
-
-🌍 12. „Die Benutzeroberfläche ist nur auf Englisch verfügbar und mein Team spricht kein Englisch“
+🌍 12. "The interface is English-only and my team doesn't speak English"
-Teams in nicht englischsprachigen Ländern, insbesondere in Lateinamerika, Asien und Europa, haben Probleme mit rein englischsprachigen Benutzeroberflächen. Sprachbarrieren verringern die Akzeptanz und erhöhen die Zahl von Konfigurationsfehlern. +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. -**So löst OmniRoute das Problem:** +**How OmniRoute solves it:** -- **Dashboard i18n – 30 Sprachen** – Alle über 500 Tasten übersetzt, einschließlich Arabisch, Bulgarisch, Dänisch, Deutsch, Spanisch, Finnisch, Französisch, Hebräisch, Hindi, Ungarisch, Indonesisch, Italienisch, Japanisch, Koreanisch, Malaiisch, Niederländisch, Norwegisch, Polnisch, Portugiesisch (PT/BR), Rumänisch, Russisch, Slowakisch, Schwedisch, Thailändisch, Ukrainisch, Vietnamesisch, Chinesisch, Philippinisch, Englisch -- **RTL-Unterstützung** – Rechts-nach-links-Unterstützung für Arabisch und Hebräisch -- **Mehrsprachige READMEs** – 30 vollständige Dokumentationsübersetzungen -- **Sprachauswahl** – Globussymbol in der Kopfzeile zum Umschalten in Echtzeit
-
🔄 13. „Ich brauche mehr als nur Chat – ich brauche Einbettungen, Bilder, Audio“
- -KI ist nicht nur der Abschluss eines Chats. Entwickler müssen Bilder generieren, Audio transkribieren, Einbettungen für RAG erstellen, Dokumente neu einordnen und Inhalte moderieren. Jede API hat einen anderen Endpunkt und ein anderes Format. - -**So löst OmniRoute das Problem:** - -- **Einbettungen** – `/v1/embeddings` mit 6 Anbietern und 9+ Modellen -- **Bildgenerierung** – `/v1/images/generations` mit 10 Anbietern und über 20 Modellen (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI) -- **Text-zu-Video** – `/v1/videos/generations` – ComfyUI (AnimateDiff, SVD) und SD WebUI -- **Text-zu-Musik** – `/v1/music/generations` – ComfyUI (Stable Audio Open, MusicGen) -- **Audiotranskription** – `/v1/audio/transcriptions` – Whisper + Nvidia NIM, HuggingFace, Qwen3 -- **Text-to-Speech** – `/v1/audio/speech` – ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, Inworld, Cartesia, PlayHT, + bestehende Anbieter -- **Moderationen** – `/v1/moderations` – Überprüfung der Inhaltssicherheit -- **Neueinstufung** – `/v1/rerank` – Neueinstufung der Dokumentenrelevanz -- **Antwort-API** – Vollständige `/v1/responses`-Unterstützung für Codex +- **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
-
🧪 14. „Ich habe keine Möglichkeit, die Qualität verschiedener Modelle zu testen und zu vergleichen“
+🔄 13. "I need more than chat — I need embeddings, images, audio"
-Entwickler möchten wissen, welches Modell für ihren Anwendungsfall am besten geeignet ist – Code, Übersetzung, Argumentation –, aber ein manueller Vergleich ist langsam. Es sind keine integrierten Evaluierungstools vorhanden. +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. -**So löst OmniRoute das Problem:** +**How OmniRoute solves it:** -- **LLM-Bewertungen** – Golden-Set-Test mit 10 vorinstallierten Fällen zu Begrüßungen, Mathematik, Geografie, Codegenerierung, JSON-Konformität, Übersetzung, Markdown und Sicherheitsverweigerung -- **4 Match-Strategien** – `exact`, `contains`, `regex`, `custom` (JS-Funktion) -- **Translator Playground Test Bench** – Batch-Tests mit mehreren Eingaben und erwarteten Ausgaben, anbieterübergreifender Vergleich -- **Chat-Tester** – Vollständiger Roundtrip mit visueller Antwortwiedergabe -- **Live-Monitor** – Echtzeit-Stream aller Anfragen, die über den Proxy fließen +- **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
-
📈 15. „Ich muss skalieren, ohne an Leistung einzubüßen“
+🧪 14. "I have no way to test and compare quality across models"
-Wenn das Anfragevolumen wächst, verursachen dieselben Fragen ohne Zwischenspeicherung doppelte Kosten. Ohne Idempotenz verschwenden doppelte Anfragen die Verarbeitung. Die Tarifbegrenzungen pro Anbieter müssen eingehalten werden. +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. -**So löst OmniRoute das Problem:** +**How OmniRoute solves it:** -- **Semantischer Cache** – Zweistufiger Cache (Signatur + Semantik) reduziert Kosten und Latenz -- **Request Idempotency** – 5-Sekunden-Deduplizierungsfenster für identische Anfragen -- **Ratenbegrenzungserkennung** – Provider-RPM, minimale Lücke und maximale gleichzeitige Verfolgung -- **Bearbeitbare Ratengrenzen** – Konfigurierbare Standardeinstellungen unter Einstellungen → Ausfallsicherheit mit Persistenz -- **API Key Validation Cache** – 3-stufiger Cache für Produktionsleistung -- **Gesundheits-Dashboard mit Telemetrie** – p50/p95/p99-Latenz, Cache-Statistiken, Betriebszeit +- **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
-
🤖 16. „Ich möchte das Modellverhalten global steuern“
Entwickler, die alle Antworten in einer bestimmten Sprache oder mit einem bestimmten Ton wünschen oder die Argumentationstoken einschränken möchten. Dies in jedem Tool/jeder Anfrage zu konfigurieren, ist unpraktisch. +📈 15. "I need to scale without losing performance"
-**So löst OmniRoute das Problem:** +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. -- **System Prompt Injection** – Globale Eingabeaufforderung, die auf alle Anfragen angewendet wird -- **Thinking Budget Validation** – Reasoning-Token-Zuteilungskontrolle pro Anfrage (Passthrough, automatisch, benutzerdefiniert, adaptiv) -- **6 Routing-Strategien** – Globale Strategien, die bestimmen, wie Anfragen verteilt werden -- **Wildcard-Router** – `provider/*`-Muster leiten dynamisch an jeden Anbieter weiter -- **Combo-Aktivierung/Deaktivierung umschalten** – Combos direkt über das Dashboard umschalten -- **Provider Toggle** – Alle Verbindungen für einen Anbieter mit einem Klick aktivieren/deaktivieren -- **Blockierte Anbieter** – Bestimmte Anbieter aus der `/v1/models`-Liste ausschließen +**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 +- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence +- **API Key Validation Cache** — 3-tier cache for production performance +- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
-
🧰 17. „Ich brauche MCP-Tools als erstklassige Produktfunktionen“
+🤖 16. "I want to control model behavior globally"
-Viele KI-Gateways stellen MCP nur als verstecktes Implementierungsdetail zur Verfügung. Teams benötigen eine sichtbare, überschaubare Betriebsebene. +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. -**So löst OmniRoute das Problem:** +**How OmniRoute solves it:** -– MCP wird in der Dashboard-Navigation und auf der Registerkarte „Endpunktprotokoll“ angezeigt - -- Dedizierte MCP-Verwaltungsseite mit Prozess, Tools, Bereichen und Audit - – Integrierter Schnellstart für `omniroute --mcp` und Kunden-Onboarding +- **System Prompt Injection** — Global prompt applied to all requests +- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive) +- **6 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 +- **Provider Toggle** — Enable/disable all connections for a provider with one click +- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
-
🧠 18. „Ich benötige A2A-Orchestrierung mit Synchronisierungs- und Stream-Aufgabenpfaden“
+🧰 17. "I need MCP tools as first-class product capabilities"
-Agenten-Workflows erfordern sowohl direkte Antworten als auch eine lang andauernde gestreamte Ausführung mit Lebenszykluskontrolle. +Many AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer. -**So löst OmniRoute das Problem:** +**How OmniRoute solves it:** -– A2A JSON-RPC-Endpunkt (`POST /a2a`) mit `message/send` und `message/stream` - -- SSE-Streaming mit Terminal-State-Propagation - – Task-Lebenszyklus-APIs für `tasks/get` und `tasks/cancel` +- 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
-
🛰️ 19. „Ich benötige den echten Zustand des MCP-Prozesses, keinen erratenen Status“
+🧠 18. "I need A2A orchestration with sync + stream task paths"
-Betriebsteams müssen wissen, ob MCP tatsächlich aktiv ist, und nicht nur, ob eine API erreichbar ist. +Agent workflows need both direct replies and long-running streamed execution with lifecycle control. -**So löst OmniRoute das Problem:** +**How OmniRoute solves it:** -– Laufzeit-Heartbeat-Datei mit PID, Zeitstempeln, Transport, Werkzeuganzahl und Oszilloskopmodus - -- MCP-Status-API, die Heartbeat + aktuelle Aktivität kombiniert -- UI-Statuskarten für Prozess-/Verfügbarkeits-/Heartbeat-Aktualität +- 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`
-
📋 20. „Ich benötige eine überprüfbare MCP-Tool-Ausführung“
+🛰️ 19. "I need real MCP process health, not guessed status"
-Wenn Tools die Konfiguration verändern oder operative Aktionen auslösen, benötigen Teams forensische Rückverfolgbarkeit. +Operational teams need to know if MCP is actually alive, not just whether an API is reachable. -**So löst OmniRoute das Problem:** +**How OmniRoute solves it:** -– SQLite-gestützte Audit-Protokollierung für MCP-Tool-Aufrufe - -- Filtert nach Tool, Erfolg/Misserfolg, API-Schlüssel und Paginierung -- Dashboard-Audit-Tabelle + Statistik-Endpunkte für die Automatisierung +- 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
-
-
-🔐 21. „Ich benötige bereichsweise MCP-Berechtigungen pro Integration“
+📋 20. "I need auditable MCP tool execution"
-Verschiedene Clients sollten Zugriff auf die Werkzeugkategorien mit den geringsten Rechten haben. +When tools mutate config or trigger ops actions, teams need forensic traceability. -**So löst OmniRoute das Problem:** +**How OmniRoute solves it:** -- 9 granulare MCP-Bereiche für kontrollierten Werkzeugzugriff -- Geltungsbereichsdurchsetzung und Sichtbarkeit in der MCP-Management-Benutzeroberfläche -- Sichere Standardhaltung für Betriebswerkzeuge - -⚙️ 22. „Ich benötige Betriebskontrollen ohne erneute Bereitstellung“
- -Teams benötigen bei Vorfällen oder Kostenereignissen schnelle Laufzeitänderungen. - -**So löst OmniRoute das Problem:** - -- Schalten Sie die Combo-Aktivierung direkt über das MCP-Dashboard um -- Wenden Sie Ausfallsicherheitsprofile aus vordefinierten Richtlinienpaketen an -- Setzen Sie den Leistungsschalterstatus über dasselbe Bedienfeld zurück +- SQLite-backed audit logging for MCP tool calls +- Filters by tool, success/failure, API key, and pagination +- Dashboard audit table + stats endpoints for automation
-
🔄 23. „Ich benötige Live-Sichtbarkeit und Abbruch des A2A-Aufgabenlebenszyklus“
+🔐 21. "I need scoped MCP permissions per integration"
-Ohne Sichtbarkeit des Lebenszyklus wird es schwierig, Aufgabenvorfälle zu selektieren. +Different clients should have least-privilege access to tool categories. -**So löst OmniRoute das Problem:** +**How OmniRoute solves it:** -- Aufgabenliste/Filterung nach Bundesland/Fähigkeit mit Paginierung -- Drilldown zu Aufgabenmetadaten, Ereignissen und Artefakten -- Endpunkt zum Abbrechen von Aufgaben und UI-Aktion mit Bestätigung +- 9 granular MCP scopes for controlled tool access +- Scope enforcement and visibility in MCP management UI +- Safe default posture for operational tooling
-
🌊 24. „Ich benötige aktive Stream-Metriken für die A2A-Last“
+⚙️ 22. "I need operational controls without redeploying"
-Streaming-Workflows erfordern betriebliche Einblicke in Parallelität und Live-Verbindungen. +Teams need quick runtime changes during incidents or cost events. -**So löst OmniRoute das Problem:** +**How OmniRoute solves it:** -- Aktive Stream-Zähler im A2A-Status integriert -- Zeitstempel der letzten Aufgabe und Anzahl pro Status -- A2A-Dashboard-Karten für die Echtzeit-Betriebsüberwachung +- Switch combo activation directly from MCP dashboard +- Apply resilience profiles from pre-defined policy packs +- Reset circuit breaker state from the same operations panel
-
🪪 25. „Ich benötige Standard-Agent-Erkennung für Clients“
+🔄 23. "I need live A2A task lifecycle visibility and cancellation"
-Externe Kunden und Orchestratoren benötigen für das Onboarding maschinenlesbare Metadaten. +Without lifecycle visibility, task incidents become hard to triage. -**So löst OmniRoute das Problem:** +**How OmniRoute solves it:** -– Agentenkarte unter `/.well-known/agent.json` ausgestellt - -- Fähigkeiten und Fertigkeiten werden in der Management-Benutzeroberfläche angezeigt - – Die A2A-Status-API enthält Erkennungsmetadaten für die Automatisierung +- Task listing/filtering by state/skill with pagination +- Drill-down on task metadata, events, and artifacts +- Task cancellation endpoint and UI action with confirmation
-
🧭 26. „Ich benötige Protokollauffindbarkeit in der Produkt-UX“
+🌊 24. "I need active stream metrics for A2A load"
-Wenn Benutzer Protokolloberflächen nicht entdecken können, sinken Akzeptanz und Supportqualität. +Streaming workflows require operational insight into concurrency and live connections. -**So löst OmniRoute das Problem:** +**How OmniRoute solves it:** -- Seitenleisteneinträge für MCP und A2A -- Registerkarte „Protokolle“ auf der Endpunktseite mit Schnellstart und Status -- Links von der Übersicht zu speziellen Management-Dashboards +- Active stream counters integrated into A2A status +- Last task timestamp and per-state counts +- A2A dashboard cards for real-time ops monitoring
-
🧪 27. „Ich benötige eine End-to-End-Protokollvalidierung mit echten Clients“
+🪪 25. "I need standard agent discovery for clients"
-Probetests reichen nicht aus, um die Protokollkompatibilität vor der Veröffentlichung zu überprüfen. +External clients and orchestrators need machine-readable metadata for onboarding. -**So löst OmniRoute das Problem:** +**How OmniRoute solves it:** -– E2E-Suite, die die App startet und echten MCP SDK-Client-Transport verwendet - -- A2A-Clienttests für Erkennungs-, Sende-, Stream-, Get- und Abbruchflüsse -- Vergleichen Sie Behauptungen mit MCP-Audit- und A2A-Aufgaben-APIs +- Agent Card exposed at `/.well-known/agent.json` +- Capabilities and skills shown in management UI +- A2A status API includes discovery metadata for automation
-
📡 28. „Ich brauche eine einheitliche Beobachtbarkeit über alle Schnittstellen hinweg“
+🧭 26. "I need protocol discoverability in the product UX"
-Die Aufteilung der Beobachtbarkeit nach Protokoll führt zu blinden Flecken und einer längeren MTTR. +If users cannot discover protocol surfaces, adoption and support quality drop. -**So löst OmniRoute das Problem:** +**How OmniRoute solves it:** -- Einheitliche Dashboards/Protokolle/Analysen in einem Produkt -- Gesundheits-, Audit- und Anforderungstelemetrie über OpenAI-, MCP- und A2A-Ebenen hinweg -- Operative APIs für Status und Automatisierung +- 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
-
💼 29. „Ich benötige eine Laufzeit für Proxy + Tools + Agent-Orchestrierung“
+🧪 27. "I need end-to-end protocol validation with real clients"
-Die Ausführung vieler separater Dienste erhöht die Betriebskosten und erhöht die Fehlerhäufigkeit. +Mock tests are not enough to validate protocol compatibility before release. -**So löst OmniRoute das Problem:**- OpenAI-kompatibler Proxy, MCP-Server und A2A-Server in einem Stack -– Gemeinsame Authentifizierung, Ausfallsicherheit, Datenspeicher und Beobachtbarkeit +**How OmniRoute solves it:** -- Konsistentes Richtlinienmodell über alle Interaktionsoberflächen hinweg +- 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
-
-### Beispiel-Playbooks (Integrierte Anwendungsfälle)
+🚀 30. „Ich muss Agenten-Workflows ohne Glue-Code-Ausbreitung versenden“
+📡 28. "I need unified observability across all interfaces"
-Teams verlieren an Geschwindigkeit, wenn sie mehrere Ad-hoc-Dienste und -Skripte zusammenfügen. +Splitting observability by protocol creates blind spots and longer MTTR. -**So löst OmniRoute das Problem:** +**How OmniRoute solves it:** -- Einheitliche Endpunktstrategie für Kunden und Agenten -- Integrierte Protokollverwaltungs-Benutzeroberflächen und Rauchvalidierungspfade -- Produktionsreife Grundlagen (Sicherheit, Protokollierung, Ausfallsicherheit, Backup) +- 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"
-**Playbook A: Bezahltes Abonnement maximieren + günstiges Backup** +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 + +
+
+
+### Example Playbooks (Integrated Use Cases)
+
+**Playbook A: Maximize paid subscription + cheap backup**
```txt
Combo: "maximize-claude"
@@ -631,7 +694,7 @@ Monthly cost: $20 + small backup spend
Outcome: higher quality, near-zero interruption
```
-**Playbook B: Kostenfreier Codierungsstack**
+**Playbook B: Zero-cost coding stack**
```txt
Combo: "free-forever"
@@ -643,7 +706,7 @@ Monthly cost: $0
Outcome: stable free coding workflow
```
-**Playbook C: 24/7 Always-On-Fallback-Kette**
+**Playbook C: 24/7 always-on fallback chain**
```txt
Combo: "always-on"
@@ -656,37 +719,61 @@ Combo: "always-on"
Outcome: deep fallback depth for deadline-critical workloads
```
-**Playbook D: Agentenoperationen mit MCP + A2A**
+**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/mcp and /dashboard/a2a
-4) Control incidents with resilience profile + task cancellation
+3) Observe via /dashboard/endpoint (MCP and A2A tabs)
+4) Toggle services via inline status controls
```
---
-## ⚡ Schnellstart
+## 🆓 Start Free — Zero Configuration Cost
-### 1) Installieren und ausführen
+> 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 **iFlow** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |
+| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |
+| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |
+| 5 | `/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).
+
+## Schnellstart
+
+### 1) Install and run
```bash
npm install -g omniroute
omniroute
```
-Das Dashboard wird unter `http://localhost:20128` geöffnet und die API-Basis-URL lautet `http://localhost:20128/v1`.
+> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:
+>
+> ```bash
+> pnpm install -g omniroute
+> pnpm approve-builds -g # Select all packages → approve
+> omniroute
+> ```
-| Befehl | Beschreibung |
-| ----------------------- | ------------------------------------------------------------------- |
-| `omniroute` | Server starten (`PORT=20128`, API und Dashboard auf demselben Port) |
-| `omniroute --port 3000` | Setzen Sie den kanonischen/API-Port auf 3000 |
-| `omniroute --mcp` | Starten Sie den MCP-Server (STDIO-Transport) |
-| `omniroute --no-open` | Browser nicht automatisch öffnen |
-| `omniroute --help` | Hilfe anzeigen |
+Dashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.
-Optionaler Split-Port-Modus:
+| 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
@@ -694,13 +781,13 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute
# Dashboard: http://localhost:20129
```
-### 2) Verbinden Sie Anbieter und erstellen Sie Ihren API-Schlüssel
+### 2) Connect providers and create your API key
-1. Öffnen Sie Dashboard → `Providers` und verbinden Sie mindestens einen Anbieter (OAuth oder API-Schlüssel).
-2. Öffnen Sie Dashboard → `Endpoint` und erstellen Sie einen API-Schlüssel.
-3. (Optional) Öffnen Sie Dashboard → `Combos` und legen Sie Ihre Fallback-Kette fest.
+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) Richten Sie Ihr Codierungstool auf OmniRoute
+### 3) Point your coding tool to OmniRoute
```txt
Base URL: http://localhost:20128/v1
@@ -708,22 +795,22 @@ API Key: [copy from Endpoint page]
Model: if/kimi-k2-thinking (or any provider/model prefix)
```
-Funktioniert mit Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode und OpenAI-kompatiblen SDKs.
+Works with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.
-### 4) Protokolle aktivieren und validieren (v2.0)
+### 4) Enable and validate protocols (v2.0)
-**MCP (für werkzeuggesteuerte Vorgänge):**
+**MCP (for tool-driven operations):**
```bash
omniroute --mcp
```
-Verbinden Sie dann Ihren MCP-Client über `stdio` und testen Sie Tools wie:
+Then connect your MCP client over `stdio` and test tools like:
- `omniroute_get_health`
- `omniroute_list_combos`
-**A2A (für Agent-zu-Agent-Workflows):**
+**A2A (for agent-to-agent workflows):**
```bash
curl http://localhost:20128/.well-known/agent.json
@@ -735,15 +822,15 @@ curl -X POST http://localhost:20128/a2a \
-d '{"jsonrpc":"2.0","id":"quickstart","method":"message/send","params":{"skill":"quota-management","messages":[{"role":"user","content":"Give me a short quota summary."}]}}'
```
-### 5) Alles durchgängig validieren (empfohlen)
+### 5) Validate everything end-to-end (recommended)
```bash
npm run test:protocols:e2e
```
-Diese Suite validiert echte MCP- und A2A-Client-Flows anhand einer laufenden App.
+This suite validates real MCP and A2A client flows against a running app.
-### Alternative: Von der Quelle ausführen
+### Alternative: run from source
```bash
cp .env.example .env
@@ -755,9 +842,9 @@ PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm
## 🐳 Docker
-OmniRoute ist als öffentliches Docker-Image auf [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute) verfügbar.
+OmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
-**Schneller Lauf:**
+**Quick run:**
```bash
docker run -d \
@@ -768,7 +855,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Mit Umgebungsdatei:**
+**With environment file:**
```bash
# Copy and edit .env first
@@ -783,7 +870,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Verwendung von Docker Compose:**
+**Using Docker Compose:**
```bash
# Base profile (no CLI tools)
@@ -793,22 +880,61 @@ docker compose --profile base up -d
docker compose --profile cli up -d
```
-| Bild | Tag | Größe | Beschreibung |
-| ------------------------ | -------- | ------- | ----------------------- |
-| `diegosouzapw/omniroute` | `latest` | ~250 MB | Neueste stabile Version |
-| `diegosouzapw/omniroute` | `1.0.3` | ~250 MB | Aktuelle Version |
+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.
+- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.
+- 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` | `1.0.3` | ~250MB | Current version |
---
-## 🖥️
+## 🖥️ Desktop App — Offline & Always-On
-Führen Sie OmniRoute als eigenständige Desktop-App aus – kein Terminal, kein Browser, keine Internetverbindung für lokale Modelle erforderlich. Die Electron-basierte App umfasst:
+> 🆕 **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.
-- 🖥️ **Natives Fenster** – Spezielles App-Fenster mit Integration in die Taskleiste
-- 🔄 **Auto-Start** – OmniRoute bei der Systemanmeldung starten
-- 🔔 **Native Benachrichtigungen** – Erhalten Sie Benachrichtigungen bei Kontingentausschöpfung oder Anbieterproblemen
-- ⚡ **One-Click-Installation** – NSIS (Windows), DMG (macOS), AppImage (Linux)
-- 🌐 **Offline-Modus** – Funktioniert vollständig offline mit dem gebündelten Server
+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
### Schnellstart
@@ -823,135 +949,348 @@ npm run electron:build:mac # macOS (.dmg) — x64 & arm64
npm run electron:build:linux # Linux (.AppImage)
```
-### Systemablage
+### System Tray
-Wenn OmniRoute minimiert ist, befindet es sich mit schnellen Aktionen in Ihrer Taskleiste:
+When minimized, OmniRoute lives in your system tray with quick actions:
-- Dashboard öffnen
-- Server-Port ändern
-- Anwendung beenden
+- Open dashboard
+- Change server port
+- Quit application
-📖 Vollständige Dokumentation: [`electron/README.md`](electron/README.md)
+📖 Full documentation: [`electron/README.md`](electron/README.md)
---
-## 💰 Preise im Überblick
+## 💰 Pricing at a Glance
-| Stufe | Anbieter | Kosten | Kontingent zurücksetzen | Am besten für |
-| -------------------- | ----------------- | ---------------------------------------- | ------------------------- | ---------------------- |
-| **💳 ABO** | Claude Code (Pro) | 20 $/Monat | 5h + wöchentlich | Bereits abonniert |
-| | Codex (Plus/Pro) | 20–200 $/Monat | 5h + wöchentlich | OpenAI-Benutzer |
-| | Gemini CLI | **KOSTENLOS** | 180.000/Monat + 1.000/Tag | Alle! |
-| | GitHub-Copilot | 10–19 $/Monat | Monatlich | GitHub-Benutzer |
-| **🔑 API-SCHLÜSSEL** | NVIDIA NIM | **KOSTENLOS** (1000 Credits) | Einmalig | Kostenlose Tier-Tests |
-| | DeepSeek | Pay-per-Use | Keine | Bestes Preis/Qualität |
-| | Groq | Kostenloses Kontingent + kostenpflichtig | Tarif begrenzt | Ultraschnelle Inferenz |
-| | xAI (Grok) | Pay-per-Use | Keine | Grok-Modelle |
-| | Mistral | Kostenloses Kontingent + kostenpflichtig | Tarif begrenzt | Europäische KI |
-| | OpenRouter | Pay-per-Use | Keine | Über 100 Modelle |
-| **💰 GÜNSTIG** | GLM-4.7 | 0,6 $/1 Mio. | Täglich 10 Uhr | Budgetsicherung |
-| | MiniMax M2.1 | 0,2 $/1 Mio. | 5-Stunden-Rollen | Günstigste Option |
-| | Kimi K2 | $9/Monat pauschal | 10 Millionen Token/Monat | Vorhersehbare Kosten |
-| **🆓 KOSTENLOS** | iFlow | $0 | Unbegrenzt | 8 Modelle kostenlos |
-| | Qwen | $0 | Unbegrenzt | 3 Modelle kostenlos |
-| | Kiro | $0 | Unbegrenzt | Claude frei |
+| 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 |
+| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |
+| | 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** | iFlow | **$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 |
-**💡 Profi-Tipp:** Beginnen Sie mit der Kombination Gemini CLI (180.000 kostenlos/Monat) + iFlow (unbegrenzt kostenlos) = 0 $ Kosten!
+> 🆕 **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
+iFlow (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.
---
-## 💡 Hauptfunktionen
+---
-OmniRoute v2.0 ist als Betriebsplattform konzipiert und nicht nur als Relay-Proxy.
+## 🆓 Free Models — What You Actually Get
-### 🤖 Agenten- und Protokolloperationen (v2.0)| Funktion | Was es tut |
+> 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.
-| ------------------------------------ | -------------------------------------------------------------------------------- |
-| 🔧 **MCP-Server (16 Tools)** | IDE-/Agent-Tools steuern Routing, Zustand, Kombinationen, Grenzwerte und Vorgänge | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`)
-| 🤝 **A2A-Server (JSON-RPC + SSE)** | Ausführung von Agent-zu-Agent-Aufgaben mit Synchronisierungs- und Streaming-Flows |
-| 🧭 **Consolidated Endpoints Page** | Dedizierte Verwaltungsseiten (`/dashboard/mcp`, `/dashboard/a2a`) |
-| 🎚️ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) |
-| 🛰️ **MCP Runtime Heartbeat** | Echter Prozessstatus (PID, Betriebszeit, Heartbeat-Alter, Transport, Scope-Modus) |
-| 📋 **MCP Audit Trail** | Filterbare Audit-Protokolle mit Erfolg/Misserfolg und Schlüsselzuordnung |
-| 🔐 **Durchsetzung des MCP-Geltungsbereichs** | 9 granulare Umfangsberechtigungen für kontrollierten Werkzeugzugriff |
-| 📡 **A2A Task Lifecycle Management** | Aufgaben auflisten/filtern, Ereignisse/Artefakte prüfen, laufende Aufgaben abbrechen |
-| 📋 **Agentenkartenerkennung** | `/.well-known/agent.json` für die automatische Client-Erkennung |
-| 🧪 **Protokoll-E2E-Testkabel** | Echtes MCP SDK + A2A-Client fließt in `test:protocols:e2e` |
-| ⚙️ **Betriebskontrollen** | Schaltkombination, Anwenden von Resilienzprofilen, Zurücksetzen von Leistungsschaltern über eine Bedienoberfläche |
+### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)
-### 🧠 Routing und Intelligenz
+| 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 |
-| Funktion | Was es tut |
-| ---------------------------------------- | ------------------------------------------------------------------------------------- |
-| 🎯 **Intelligenter 4-Stufen-Fallback** | Automatische Route: Abonnement → API-Schlüssel → Günstig → Kostenlos |
-| 📊 **Kontingentverfolgung in Echtzeit** | Live-Token-Zählung + Reset-Countdown pro Anbieter |
-| 🔄 **Formatübersetzung** | OpenAI ↔ Claude ↔ Gemini ↔ Antworten mit schemasicheren Konvertierungen |
-| 👥 **Unterstützung mehrerer Konten** | Mehrere Konten pro Anbieter mit intelligenter Auswahl |
-| 🔄 **Automatische Token-Aktualisierung** | OAuth-Token werden bei Wiederholung automatisch aktualisiert |
-| 🎨 **Benutzerdefinierte Kombinationen** | 6 Ausgleichsstrategien + Fallback-Kettenkontrolle |
-| 🌐 **Wildcard-Router** | `provider/*` dynamisches Routing |
-| 🧠 **Budgetkontrollen denken** | Passthrough-, automatische, benutzerdefinierte und adaptive Reasoning-Grenzwerte |
-| 🔀 **Modell-Aliase** | Integrierte + benutzerdefinierte Modell-Aliasing- und Migrationssicherheit |
-| ⚡ **Hintergrundverschlechterung** | Hintergrundaufgaben mit niedriger Priorität an günstigere Modelle weiterleiten |
-| 💬 **System-Prompt-Injektion** | Globale Verhaltenskontrollen werden konsequent angewendet |
-| 📄 **Antwort-API-Kompatibilität** | Vollständige `/v1/responses`-Unterstützung für Codex und erweiterte Agenten-Workflows |
+### 🟢 IFLOW MODELS (Free OAuth — No Credit Card)
-### 🎵 Multimodale APIs
+| 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 |
-| Funktion | Was es tut || -------------------------- | ------------------------------------------------------------- |
-| 🖼️ **Bilderzeugung** | `/v1/images/generations` mit Cloud- und lokalen Backends |
-| 📐 **Einbettungen** | `/v1/embeddings` für Such- und RAG-Pipelines |
-| 🎤 **Audio-Transkription** | `/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) |
-| 🎬 **Videogenerierung** | `/v1/videos/generations` (ComfyUI + SD WebUI-Workflows) |
-| 🎵 **Musikgeneration** | `/v1/music/generations` (ComfyUI-Workflows) |
-| 🛡️ **Moderationen** | `/v1/moderations` Sicherheitsprüfungen |
-| 🔀 **Neueinstufung** | `/v1/rerank` für Relevanzbewertung |
+### 🟡 QWEN MODELS (Device Code Auth)
-### 🛡️ Resilienz, Sicherheit und Governance
+| 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) |
-| Funktion | Was es tut |
-| ---------------------------------------- | ------------------------------------------------------------------------------ |
-| 🔌 **Leistungsschalter** | Auslösung/Wiederherstellung auf Anbieterebene mit Schwellenwertkontrollen |
-| 🛡️ **Anti-Donnerende Herde** | Mutex- und Semaphorschutz bei Wiederholungs-/Ratenereignissen |
-| 🧠 **Semantik + Signatur-Cache** | Kosten-/Latenzreduzierung mit zwei Cache-Schichten |
-| ⚡ **Idempotenz anfordern** | Doppeltes Schutzfenster |
-| 🔒 **TLS-Fingerabdruck-Spoofing** | Bessere Kompatibilität mit Anti-Bot-gefilterten Anbietern |
-| 🌐 **IP-Filterung** | Zulassungs-/Blocklistenkontrolle für exponierte Bereitstellungen |
-| 📊 **Bearbeitbare Ratenlimits** | Konfigurierbare globale/Provider-Level-Limits mit Persistenz |
-| 🔑 **API-Schlüsselverwaltung + Scoping** | Sichere Schlüsselausgabe/-rotation und Modell-/Anbieterkontrollen |
-| 🛡️ **Geschützt `/models`** | Optionales Authentifizierungs-Gating und Provider-Ausblenden für Modellkatalog |
+### 🟣 GEMINI CLI (Google OAuth)
-### 📊 Beobachtbarkeit und Analyse
+| Model | Prefix | Limit | Rate Limit |
+| ------------------------ | ------ | --------------------------- | ------------- |
+| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |
+| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |
-| Funktion | Was es tut |
-| ---------------------------------------- | ------------------------------------------------------------------- |
-| 📝 **Anfrage + Proxy-Protokollierung** | Vollständige Anfrage/Antwort- und Proxy-Protokollierung |
-| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |
-| 📋 **Einheitliches Protokoll-Dashboard** | Anforderungs-, Proxy-, Audit- und Konsolenansichten auf einer Seite |
-| 🔍 **Telemetrie anfordern** | p50/p95/p99-Latenz und Anforderungsverfolgung |
-| 🏥 **Gesundheits-Dashboard** | Betriebszeit, Breaker-Zustände, Sperrungen, Cache-Statistiken |
-| 💰 **Kostenverfolgung** | Budgetkontrolle und Preistransparenz pro Modell |
-| 📈 **Analysevisualisierungen** | Einblicke in die Modell-/Anbieternutzung und Trendansichten |
-| 🧪 **Bewertungsrahmen** | Golden-Set-Test mit konfigurierbaren Match-Strategien |
+### ⚫ NVIDIA NIM (Free API Key — build.nvidia.com)
-### ☁️ Bereitstellung und Plattform
+| Tier | Daily Limit | Rate Limit | Notes |
+| ---------- | ------------ | ----------- | ------------------------------------------------------ |
+| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |
-| Funktion | Was es tut |
-| ------------------------------------------- | ------------------------------------------------------------------------------ | --- | ----------------------------- | ------------------------------------------------ |
-| 🌐 **Überall bereitstellen** | Localhost, VPS, Docker, Cloud-Umgebungen | | 💾 **Cloud-Synchronisierung** | Konfigurationssynchronisierung über Cloud Worker |
-| 🔄 **Sichern/Wiederherstellen** | Export-/Import- und Disaster-Recovery-Abläufe |
-| 🧙 **Onboarding-Assistent** | Erstmaliges geführtes Setup |
-| 🔧 **CLI-Tools-Dashboard** | Ein-Klick-Setup für beliebte Codierungstools |
-| 🌐 **i18n (30 Sprachen)** | Vollständige Sprachunterstützung für Dashboard und Dokumente mit RTL-Abdeckung |
-| 🧹 **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 |
-| 📂 **Benutzerdefiniertes Datenverzeichnis** | `DATA_DIR`-Überschreibung für Speicherort |
+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
+> iFlow (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 v2.0 is built as an operational platform, not just a relay proxy.
+
+### 🆕 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 Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |
+| 🤖 **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 (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) |
+| 🤝 **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** | 9 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 combo, apply resilience profiles, reset breakers from one control surface |
+
+### 🧠 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** | 6 balancing strategies + fallback chain control |
+| 🌐 **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) |
+| 💬 **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 |
+| ----------------------------------- | -------------------------------------------------------------------------------------- |
+| 🔌 **Circuit Breakers** | Per-model trip/recover with threshold controls |
+| 🎯 **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 |
+| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |
+| 🔑 **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 |
+
+### 📊 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 |
+| 📋 **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 |
+
+### ☁️ Deployment & Platform
+
+| Feature | What It Does |
+| ----------------------------- | --------------------------------------------------------- |
+| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |
+| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |
+| 💾 **Cloud Sync** | Configuration sync via cloud worker |
+| 🔄 **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 |
### Feature Deep Dive
-#### Smarter Fallback mit praktischer Kostenkontrolle
+#### Smart fallback with practical cost control
```txt
Combo: "my-coding-stack"
@@ -961,73 +1300,73 @@ Combo: "my-coding-stack"
4. if/kimi-k2-thinking
```
-Wenn Kontingent, Rate oder Integrität fehlschlagen, wechselt OmniRoute automatisch zum nächsten Kandidaten, ohne dass ein manueller Wechsel erforderlich ist.
+When quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.
-#### Protokollverwaltung, die sichtbar und bedienbar ist
+#### Protocol management that is visible and operable
-- MCP + A2A sind in der Benutzeroberfläche und in den Dokumenten erkennbar (nicht ausgeblendet)
- – Protokollstatus-APIs stellen Live-Betriebsdaten bereit (`/api/mcp/*`, `/api/a2a/*`)
-- Dashboards umfassen Aktionen für Tag-2-Operationen (Kombinationsumschaltung, Zurücksetzen von Leistungsschaltern, Aufgabenabbruch).
+- 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)
-#### Übersetzer- und Validierungsworkflow
+#### Translator + validation workflow
-Der Übersetzerbereich umfasst:
+The Translator area includes:
-- **Spielplatz**: Transformationsprüfungen anfordern
-- **Chat-Tester**: vollständiger Anfrage-/Antwort-Roundtrip
-- **Prüfstand**: mehrere Fälle in einem Durchgang
-- **Live Monitor**: Echtzeit-Verkehrsansicht
+- **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 Protokollvalidierung mit echten Clients über `npm run test:protocols:e2e`.
+Plus protocol validation with real clients via `npm run test:protocols:e2e`.
-> 📖 **[MCP Server README](open-sse/mcp-server/README.md)** – Tool-Referenz, IDE-Konfigurationen und Client-Beispiele
+> 📖 **[MCP Server README](open-sse/mcp-server/README.md)** — Tool reference, IDE configs, and client examples
>
-> 📖 **[A2A Server README](src/lib/a2a/README.md)** – Fähigkeiten, JSON-RPC-Methoden, Streaming und Aufgabenlebenszyklus
+> 📖 **[A2A Server README](src/lib/a2a/README.md)** — Skills, JSON-RPC methods, streaming, and task lifecycle
-## 🧪 Bewertungen (Evals)
+## 🧪 Evaluations (Evals)
-OmniRoute umfasst ein integriertes Bewertungsframework zum Testen der LLM-Antwortqualität anhand eines Golden Sets. Greifen Sie darauf über **Analytics → Evals** im Dashboard zu.
+OmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics → Evals** in the dashboard.
-### Eingebautes goldenes Set
+### Built-in Golden Set
-Das vorinstallierte „OmniRoute Golden Set“ enthält Testfälle für:
+The pre-loaded "OmniRoute Golden Set" contains test cases for:
-- Grüße, Mathematik, Geographie, Codegenerierung
-- Einhaltung des JSON-Formats, Übersetzung, Markdown-Generierung
-- Sicherheitsverweigerung (schädlicher Inhalt), Zählung, boolesche Logik
+- Greetings, math, geography, code generation
+- JSON format compliance, translation, markdown generation
+- Safety refusal (harmful content), counting, boolean logic
-### Bewertungsstrategien
+### Evaluation Strategies
-| Strategie | Beschreibung | Beispiel |
-| ---------- | -------------------------------------------------------------------------------------------- | --------------------------------------- |
-| `exact` | Die Ausgabe muss genau mit | übereinstimmen `"4"` |
-| `contains` | Die Ausgabe muss eine Teilzeichenfolge enthalten (Groß-/Kleinschreibung wird nicht beachtet) | `"Paris"` |
-| `regex` | Die Ausgabe muss mit dem Regex-Muster | übereinstimmen `"1.*2.*3"` |
-| `custom` | Benutzerdefinierte JS-Funktion gibt true/false | zurück `(output) => output.length > 10` |
+| 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` |
---
-## 📖 Einrichtungsanleitung
+## 📖 Setup Guide
-### Protokoll-Setup (MCP + A2A)
+### Protocol Setup (MCP + A2A)
🚀 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) + +
-
-🧩 MCP-Setup (Modellkontextprotokoll)
+🧩 MCP Setup (Model Context Protocol)
-Starten Sie den MCP-Transport im Standardmodus: +Start MCP transport in stdio mode: ```bash omniroute --mcp ``` -Empfohlener Validierungsablauf: +Recommended validation flow: -1. Verbinden Sie Ihren MCP-Client über stdio. -2. Führen Sie `omniroute_get_health` aus. -3. Führen Sie `omniroute_list_combos` aus. -4. Öffnen Sie `/dashboard/mcp`, um Heartbeat, Aktivität und Audit zu bestätigen. +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. -Nützliche APIs für die Automatisierung: +Useful APIs for automation: - `GET /api/mcp/status` - `GET /api/mcp/tools` @@ -1036,15 +1375,16 @@ Nützliche APIs für die Automatisierung:🤝 A2A-Setup (Agent2Agent)
+
+
🤝 A2A Setup (Agent2Agent)
-Entdecken Sie den Agenten: +Discover the agent: ```bash curl http://localhost:20128/.well-known/agent.json ``` -Senden Sie eine Aufgabe: +Send a task: ```bash curl -X POST http://localhost:20128/a2a \ @@ -1052,38 +1392,38 @@ curl -X POST http://localhost:20128/a2a \ -d '{"jsonrpc":"2.0","id":"setup-a2a","method":"message/send","params":{"skill":"quota-management","messages":[{"role":"user","content":"Summarize quota status."}]}}' ``` -Lebenszyklus verwalten: +Manage lifecycle: - `GET /api/a2a/status` - `GET /api/a2a/tasks` - `GET /api/a2a/tasks/:id` - `POST /api/a2a/tasks/:id/cancel` -Operative Benutzeroberfläche: +Operational UI: -- `/dashboard/a2a` für Task-/Status-/Stream-Beobachtbarkeit und Smoke-Aktionen +- `/dashboard/a2a` for task/state/stream observability and smoke actions
-
🧪 End-to-End-Protokollvalidierung
+🧪 End-to-end protocol validation
-Validieren Sie beide Protokolle mit echten Clients: +Validate both protocols with real clients: ```bash npm run test:protocols:e2e ``` -Dies bestätigt: +This verifies: -- MCP SDK-Client-Verbindung/Liste/Anruf -- A2A-Erkennung/Senden/Streamen/Get/Abbrechen -- Vergleichen Sie die Daten in MCP-Audit- und A2A-Aufgabenverwaltungs-APIs +- MCP SDK client connect/list/call +- A2A discovery/send/stream/get/cancel +- Cross-check data in MCP audit and A2A task management APIs
-
💳 Abonnementanbieter
+💳 Subscription Providers
### Claude Code (Pro/Max) @@ -1098,7 +1438,7 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Profi-Tipp:** Verwenden Sie Opus für komplexe Aufgaben, Sonnet für Geschwindigkeit. OmniRoute verfolgt das Kontingent pro Modell! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! ### OpenAI Codex (Plus/Pro) @@ -1112,7 +1452,24 @@ Models: cx/gpt-5.1-codex-max ``` -### Gemini CLI (KOSTENLOS 180.000/Monat!) +#### 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). + +### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -1124,9 +1481,9 @@ Models: gc/gemini-2.5-pro ``` -**Bester Wert:** Riesiges kostenloses Kontingent! Verwenden Sie dies vor kostenpflichtigen Stufen. +**Best Value:** Huge free tier! Use this before paid tiers. -### GitHub-Copilot +### GitHub Copilot ```bash Dashboard → Providers → Connect GitHub @@ -1142,103 +1499,103 @@ Models:
-
🔑 API-Schlüsselanbieter
+🔑 API Key Providers
-### NVIDIA NIM (KOSTENLOSE 1000 Credits!) +### NVIDIA NIM (FREE developer access — 70+ models) -1. Registrieren Sie sich: [build.nvidia.com](https://build.nvidia.com) -2. Holen Sie sich einen kostenlosen API-Schlüssel (1000 Inferenz-Credits inbegriffen) -3. Dashboard → Anbieter hinzufügen → NVIDIA NIM: - - API-Schlüssel: `nvapi-your-key` +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` -**Modelle:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct` und über 50 weitere +**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more -**Profi-Tipp:** OpenAI-kompatible API – funktioniert nahtlos mit der Formatübersetzung von OmniRoute! +**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation! ### DeepSeek -1. Registrieren Sie sich: [platform.deepseek.com](https://platform.deepseek.com) -2. Holen Sie sich den API-Schlüssel -3. Dashboard → Anbieter hinzufügen → DeepSeek +1. Sign up: [platform.deepseek.com](https://platform.deepseek.com) +2. Get API key +3. Dashboard → Add Provider → DeepSeek -**Modelle:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` +**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` -### Groq (Kostenloses Kontingent verfügbar!) +### Groq (Free Tier Available!) -1. Registrieren Sie sich: [console.groq.com](https://console.groq.com) -2. Holen Sie sich den API-Schlüssel (kostenloses Kontingent inbegriffen) -3. Dashboard → Anbieter hinzufügen → Groq +1. Sign up: [console.groq.com](https://console.groq.com) +2. Get API key (free tier included) +3. Dashboard → Add Provider → Groq -**Modelle:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` +**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` -**Profi-Tipp:** Ultraschnelle Inferenz – am besten für Echtzeit-Codierung! +**Pro Tip:** Ultra-fast inference — best for real-time coding! -### OpenRouter (über 100 Modelle) +### OpenRouter (100+ Models) -1. Registrieren Sie sich: [openrouter.ai](https://openrouter.ai) -2. Holen Sie sich den API-Schlüssel -3. Dashboard → Anbieter hinzufügen → OpenRouter +1. Sign up: [openrouter.ai](https://openrouter.ai) +2. Get API key +3. Dashboard → Add Provider → OpenRouter -**Modelle:** Greifen Sie über einen einzigen API-Schlüssel auf über 100 Modelle aller großen Anbieter zu. +**Models:** Access 100+ models from all major providers through a single API key.
-
💰 Günstige Anbieter (Backup)
+💰 Cheap Providers (Backup)
-### GLM-4.7 (Täglicher Reset, 0,6 $/1 Mio.) +### GLM-4.7 (Daily reset, $0.6/1M) -1. Registrieren: [Zhipu AI](https://open.bigmodel.cn/) -2. Holen Sie sich den API-Schlüssel vom Coding Plan -3. Dashboard → API-Schlüssel hinzufügen: - - Anbieter: `glm` - - API-Schlüssel: `your-key` +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` -**Verwendung:** `glm/glm-4.7` +**Use:** `glm/glm-4.7` -**Profi-Tipp:** Coding Plan bietet 3× Kontingent zu 1/7 Kosten! Täglich um 10:00 Uhr zurückgesetzt. +**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -### MiniMax M2.1 (5 Stunden Zurücksetzen, 0,20 $/1 Mio.) +### MiniMax M2.1 (5h reset, $0.20/1M) -1. Registrieren: [MiniMax](https://www.minimax.io/) -2. Holen Sie sich den API-Schlüssel -3. Dashboard → API-Schlüssel hinzufügen +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key +3. Dashboard → Add API Key -**Verwendung:** `minimax/MiniMax-M2.1` +**Use:** `minimax/MiniMax-M2.1` -**Profi-Tipp:** Günstigste Option für langen Kontext (1 Mio. Token)! +**Pro Tip:** Cheapest option for long context (1M tokens)! -### Kimi K2 (9 $/Monat pauschal) +### Kimi K2 ($9/month flat) -1. Abonnieren: [Moonshot AI](https://platform.moonshot.ai/) -2. Holen Sie sich den API-Schlüssel -3. Dashboard → API-Schlüssel hinzufügen +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key +3. Dashboard → Add API Key -**Verwendung:** `kimi/kimi-latest` +**Use:** `kimi/kimi-latest` -**Profi-Tipp:** Feste 9 $/Monat für 10 Mio. Token = 0,90 $/1 Mio. effektive Kosten! +**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
-
🆓 KOSTENLOSE Anbieter (Notfall-Backup)
+🆓 FREE Providers (Emergency Backup)
-### iFlow (8 KOSTENLOSE Modelle)```bash +### iFlow (5 FREE models via OAuth) +```bash Dashboard → Connect iFlow → iFlow OAuth login → Unlimited usage Models: -if/kimi-k2-thinking -if/qwen3-coder-plus -if/glm-4.7 -if/minimax-m2 -if/deepseek-r1 + if/kimi-k2-thinking + if/qwen3-coder-plus + if/glm-4.7 + if/minimax-m2 + if/deepseek-r1 +``` -```` - -### Qwen (3 KOSTENLOSE Modelle) +### Qwen (4 FREE models via Device Code) ```bash Dashboard → Connect Qwen @@ -1248,9 +1605,9 @@ Dashboard → Connect Qwen Models: qw/qwen3-coder-plus qw/qwen3-coder-flash -```` +``` -### Kiro (Claude KOSTENLOS) +### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro @@ -1265,9 +1622,9 @@ Models:
-
🎨 Combos erstellen
+🎨 Create Combos
-### Beispiel 1: Abonnement maximieren → Günstiges Backup +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -1281,7 +1638,7 @@ Models: Use in CLI: premium-coding ``` -### Beispiel 2: Nur kostenlos (kostenlos) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -1296,9 +1653,9 @@ Cost: $0 forever!
-
---
-## 🐛 Fehlerbehebung
+## Fehlerbehebung
🔧 CLI-Integration
+🔧 CLI Integration
-### Cursor-IDE +### Cursor IDE ``` Settings → Models → Advanced: @@ -1309,9 +1666,9 @@ Settings → Models → Advanced: ### Claude Code -Verwenden Sie die Seite **CLI-Tools** im Dashboard für die Ein-Klick-Konfiguration oder bearbeiten Sie `~/.claude/settings.json` manuell. +Use the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually. -### Codex-CLI +### Codex CLI ```bash export OPENAI_BASE_URL="http://localhost:20128" @@ -1322,13 +1679,13 @@ codex "your prompt" ### OpenClaw -**Option 1 – Dashboard (empfohlen):** +**Option 1 — Dashboard (recommended):** ``` Dashboard → CLI Tools → OpenClaw → Select Model → Apply ``` -**Option 2 – Manuell:** Bearbeiten `~/.openclaw/openclaw.json`: +**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`: ```json { @@ -1344,9 +1701,9 @@ Dashboard → CLI Tools → OpenClaw → Select Model → Apply } ``` -> **Hinweis:** OpenClaw funktioniert nur mit lokaler OmniRoute. Verwenden Sie `127.0.0.1` anstelle von `localhost`, um Probleme mit der IPv6-Auflösung zu vermeiden. +> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues. -### Cline / Weiter / RooCode +### Cline / Continue / RooCode ``` Settings → API Configuration: @@ -1358,7 +1715,7 @@ Settings → API Configuration: ### OpenCode -**Schritt 1:** OmniRoute als benutzerdefinierten Anbieter hinzufügen: +**Step 1:** Add OmniRoute as a custom provider: ```bash opencode @@ -1366,7 +1723,7 @@ opencode # Select "Other" → Enter ID: "omniroute" → Enter your OmniRoute API key ``` -**Schritt 2:** Erstellen/bearbeiten Sie `opencode.json` in Ihrem Projektstamm: +**Step 2:** Create/edit `opencode.json` in your project root: ```json { @@ -1388,120 +1745,213 @@ opencode } ``` -**Schritt 3:** Wählen Sie das Modell in OpenCode aus: +**Step 3:** Select the model in OpenCode: ```bash /models # Select any OmniRoute model from the list ``` -> **Tipp:** Fügen Sie alle in Ihrem OmniRoute `/v1/models`-Endpunkt verfügbaren Modelle zum Abschnitt `models` hinzu. Verwenden Sie das Format `provider/model-id` aus Ihrem OmniRoute-Dashboard. +> **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.
-
+
+## 🛠️ Tech Stack
Klicken Sie hier, um den Leitfaden zur Fehlerbehebung zu erweitern
+Click to expand troubleshooting guide
-**„Sprachmodell hat keine Nachrichten bereitgestellt“** +**"Language model did not provide messages"** -- Anbieterkontingent erschöpft → Überprüfen Sie den Dashboard-Kontingent-Tracker -- Lösung: Combo-Fallback verwenden oder auf günstigere Stufe wechseln +- Provider quota exhausted → Check dashboard quota tracker +- Solution: Use combo fallback or switch to cheaper tier -**Ratenbegrenzung** +**Rate limiting** -- Abonnementkontingent aufgebraucht → Fallback auf GLM/MiniMax -- Kombination hinzufügen: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Subscription quota out → Fallback to GLM/MiniMax +- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -**OAuth-Token abgelaufen** +**OAuth token expired** -- Automatische Aktualisierung durch OmniRoute -- Wenn die Probleme weiterhin bestehen: Dashboard → Anbieter → Verbindung wiederherstellen +- Auto-refreshed by OmniRoute +- If issues persist: Dashboard → Provider → Reconnect -**Hohe Kosten** +**High costs** -- Überprüfen Sie die Nutzungsstatistiken im Dashboard → Kosten -- Primärmodell auf GLM/MiniMax umstellen -- Nutzen Sie das kostenlose Kontingent (Gemini CLI, iFlow) für unkritische Aufgaben +- Check usage stats in Dashboard → Costs +- Switch primary model to GLM/MiniMax +- Use free tier (Gemini CLI, iFlow) for non-critical tasks -**Dashboard-/API-Ports sind falsch** +**Dashboard/API ports are wrong** -- `PORT` ist der kanonische Basisport (und standardmäßig API-Port) - – `API_PORT` überschreibt nur OpenAI-kompatible API-Listener - – `DASHBOARD_PORT` überschreibt nur Dashboard/Next.js-Listener -- Setzen Sie `NEXT_PUBLIC_BASE_URL` auf Ihr Dashboard/öffentliche URL (für OAuth-Rückrufe). +- `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-Synchronisierungsfehler** +**Cloud sync errors** -– Überprüfen Sie, ob `BASE_URL` auf Ihre laufende Instanz verweist -– Überprüfen Sie, ob `CLOUD_URL` auf Ihren erwarteten Cloud-Endpunkt verweist -– Halten Sie die `NEXT_PUBLIC_*`-Werte an den serverseitigen Werten ausgerichtet +- 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 -**Erste Anmeldung funktioniert nicht** +**First login not working** -- Überprüfen Sie `INITIAL_PASSWORD` in `.env` - – Wenn nicht festgelegt, lautet das Fallback-Passwort `123456` +- Check `INITIAL_PASSWORD` in `.env` +- If unset, fallback password is `123456` -**Keine Anfrageprotokolle** +**No request logs** -- Setzen Sie `ENABLE_REQUEST_LOGS=true` in `.env` +- Set `ENABLE_REQUEST_LOGS=true` in `.env` -**Verbindungstest zeigt „Ungültig“ für OpenAI-kompatible Anbieter** +**Connection test shows "Invalid" for OpenAI-compatible providers** -– Viele Anbieter stellen keinen `/models`-Endpunkt bereit -– OmniRoute v1.0.6+ beinhaltet eine Fallback-Validierung über Chat-Abschlüsse -– Stellen Sie sicher, dass die Basis-URL das Suffix `/v1` enthält +- 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 auf Server Remoto +### 🔐 OAuth on a Remote Server + -> **⚠️ WICHTIG für den Einsatz von OmniRoute auf VPS/Docker/Remote-Servern** +> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server** -#### OAuth +#### Why does Antigravity / Gemini CLI OAuth fail on remote servers? -Als OAuth-Anmeldeinformationen wurde OmniRoute nicht in die Liste eingetragen. **Zugelassen für `localhost`**. Wenn Sie OmniRoute auf einem Remote-Server (z. B. +The **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console. + +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 ``` -#### Lösung: Konfigurieren Sie Ihre eigenen OAuth-Anmeldeinformationen +#### Solution: Configure your own OAuth credentials -Sie schreiben bitte eine **OAuth 2.0-Client-ID** in der Google Cloud Console mit einem URI für Ihren Server. +You need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI. -#### Passo a Passo +#### Step-by-step -**1. Zugriff auf die Google Cloud Console** +**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 + +# For Gemini CLI: +GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com +GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +``` + +**6. Restart OmniRoute** + +```bash +# npm: +npm run dev + +# Docker: +docker restart omniroute +``` + +**7. Try connecting again** + +Dashboard → Providers → Antigravity (or Gemini CLI) → OAuth + +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. + +--- + +
+
---
-## 🛠️
+🇧🇷 Versão em Português
+ +#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos? + +Os provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo. + +As credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticação com: + +``` +Error 400: redirect_uri_mismatch +``` + +#### Solução: Configure suas próprias credenciais OAuth + +Você precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor. + +#### Passo a passo + +**1. Acesse o Google Cloud Console** Abra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) -**2. Rufen Sie eine neue OAuth 2.0-Client-ID auf** +**2. Crie um novo OAuth 2.0 Client ID** -- Klicken Sie auf **"+ Anmeldeinformationen erstellen"** → **"OAuth-Client-ID"** -- Anwendungstyp: **„Webanwendung“** -- Name: Escolha qualquer nome (z. B. `OmniRoute Remote`) +- Clique em **"+ Create Credentials"** → **"OAuth client ID"** +- Tipo de aplicativo: **"Web application"** +- Nome: escolha qualquer nome (ex: `OmniRoute Remote`) -**3. Adicione als autorisierte Weiterleitungs-URIs** +**3. Adicione as Authorized Redirect URIs** -Nein, **"Autorisierte Weiterleitungs-URIs"**, Zusatz: +No campo **"Authorized redirect URIs"**, adicione: ``` https://seu-servidor.com/callback ``` -> Ersetzen Sie `seu-servidor.com` durch die Domain oder die IP Ihres Servers (einschließlich eines Ports, der unbedingt erforderlich ist, z. B.: `http://45.33.32.156:20128/callback`). +> Substitua `seu-servidor.com` pelo domínio ou IP do seu servidor (inclua a porta se necessário, ex: `http://45.33.32.156:20128/callback`). -**4. Als Anmeldedaten speichern und kopieren** +**4. Salve e copie as credenciais** -Anschließend hat Google die **Client-ID** und das **Client-Geheimnis** angezeigt. +Após criar, o Google mostrará o **Client ID** e o **Client Secret**. -**5. Als Umgebungsvariationen konfigurieren** +**5. Configure as variáveis de ambiente** -Kein `.env` (oder mehrere Docker-Umgebungsvarianten): +No seu `.env` (ou nas variáveis de ambiente do Docker): ```bash # Para Antigravity: @@ -1514,7 +1964,7 @@ GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret ``` -**6. Neuzugang zu OmniRoute** +**6. Reinicie o OmniRoute** ```bash # Se usando npm: @@ -1526,110 +1976,114 @@ docker restart omniroute **7. Tente conectar novamente** -Dashboard → Anbieter → Antigravity (oder Gemini CLI) → OAuth +Dashboard → Providers → Antigravity (ou Gemini CLI) → OAuth -Jetzt hat Google die Nachricht an `https://seu-servidor.com/callback` weitergeleitet und eine Authentifizierungsfunktion durchgeführt. +Agora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará. --- -#### Workaround vorübergehend (nicht vorab konfiguriert) +#### Workaround temporário (sem configurar credenciais próprias) -Wenn Sie vorab keine Berechtigung erhalten möchten, besteht die Möglichkeit, das **URL-Handbuch** zu verwenden: +Se não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**: -1. OmniRoute ruft eine von Google autorisierte URL auf -2. Nachdem Sie den Autor autorisiert haben, sendet Google eine Weiterleitung an `localhost` (diese wird jedoch nicht vom Server weitergeleitet). -3. **Kopieren Sie eine vollständige URL**, um sie in Ihren Browser zu laden (bitte beachten Sie, dass die Seite noch nicht abgeschlossen ist). -4. Geben Sie die URL ein, die nicht zur Verbindung mit OmniRoute verwendet werden soll -5. Klicken Sie auf **„Verbinden“** +1. O OmniRoute abrirá a URL de autorização do Google +2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto) +3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue) +4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute +5. Clique em **"Connect"** -> Diese Problemumgehung funktioniert aufgrund des Autorisierungscodes auf der URL und ist unabhängig von der Weiterleitung oder Nicht-Weiterleitung gültig. +> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.
-
---
-## 📖 Dokumentation
+## Dokumentation
-| Dokument | Beschreibung |
-| ------------------------------------------------ | ------------------------------------------------------------------ |
-| [Benutzerhandbuch](docs/USER_GUIDE.md) | Anbieter, Kombinationen, CLI-Integration, Bereitstellung |
-| [API-Referenz](docs/API_REFERENCE.md) | Alle Endpunkte mit Beispielen |
-| [MCP-Server](open-sse/mcp-server/README.md) | 16 MCP-Tools, IDE-Konfigurationen, Python/TS/Go-Clients |
-| [A2A-Server](src/lib/a2a/README.md) | JSON-RPC 2.0-Protokoll, Fähigkeiten, Streaming, Aufgabenverwaltung |
-| [Auto-Combo-Engine](docs/auto-combo.md) | 6-Faktor-Bewertung, Moduspakete, Selbstheilung |
-| [Fehlerbehebung](docs/TROUBLESHOOTING.md) | Häufige Probleme und Lösungen |
-| [Architektur](docs/ARCHITECTURE.md) | Systemarchitektur und Interna |
-| [Beitrag](CONTRIBUTING.md) | Entwicklungsaufbau und Richtlinien |
-| [OpenAPI-Spezifikation](docs/openapi.yaml) | OpenAPI 3.0-Spezifikation |
-| [Sicherheitsrichtlinie](SECURITY.md) | Schwachstellenmeldung und Sicherheitspraktiken |
-| [VM-Bereitstellung](docs/VM_DEPLOYMENT_GUIDE.md) | Vollständige Anleitung: VM + Nginx + Cloudflare-Setup |
-| [Features-Galerie](docs/FEATURES.md) | Visuelle Dashboard-Tour mit Screenshots |
-| [Release-Checkliste](docs/RELEASE_CHECKLIST.md) | Validierungsschritte vor der Veröffentlichung |
+| Document | Description |
+| ---------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 16 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/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
+| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
-## 🗺️
+## 🗺️ Roadmap
-Für OmniRoute sind **210+ Funktionen** in mehreren Entwicklungsphasen geplant. Hier sind die Schlüsselbereiche:
+OmniRoute has **210+ features planned** across multiple development phases. Here are the key areas:
-| Kategorie | Geplante Funktionen | Höhepunkte |
-| ------------------------------ | ------------------- | ------------------------------------------------------------------------------------------------------ |
-| 🧠 **Routing & Intelligenz** | 25+ | Routing mit der niedrigsten Latenz, Tag-basiertes Routing, Quoten-Preflight, P2C-Kontoauswahl |
-| 🔒 **Sicherheit & Compliance** | 20+ | SSRF-Härtung, Credential-Cloaking, Ratenbegrenzung pro Endpunkt, Verwaltungsschlüssel-Scoping |
-| 📊 **Beobachtbarkeit** | 15+ | OpenTelemetry-Integration, Echtzeit-Kontingentüberwachung, Kostenverfolgung pro Modell |
-| 🔄 **Anbieterintegrationen** | 20+ | Dynamische Modellregistrierung, Anbieter-Abklingzeiten, Multi-Account-Codex, Copilot-Kontingentanalyse |
-| ⚡ **Leistung** | 15+ | Duale Cache-Schicht, Prompt-Cache, Antwort-Cache, Streaming-Keepalive, Batch-API |
-| 🌐 **Ökosystem** | 10+ | WebSocket-API, Hot-Reload der Konfiguration, verteilter Konfigurationsspeicher, kommerzieller Modus |
+| Category | Planned Features | Highlights |
+| ----------------------------- | ---------------- | -------------------------------------------------------------------------------------- |
+| 🧠 **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, P2C account selection |
+| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |
+| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |
+| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider 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 |
-### 🔜 Bald erhältlich- 🔗 **OpenCode-Integration** – Native Anbieterunterstützung für die OpenCode AI-Codierungs-IDE
+### 🔜 Coming Soon
-- 🔗 **TRAE-Integration** – Volle Unterstützung für das TRAE AI-Entwicklungsframework
-- 📦 **Batch-API** – Asynchrone Stapelverarbeitung für Massenanfragen
-- 🎯 **Tag-basiertes Routing** – Leiten Sie Anfragen basierend auf benutzerdefinierten Tags und Metadaten weiter
-- 💰 **Niedrigste Kostenstrategie** – Wählen Sie automatisch den günstigsten verfügbaren Anbieter aus
+- 🔗 **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
-> 📝 Vollständige Funktionsspezifikationen verfügbar in [`docs/new-features/`](docs/new-features/) (217 detaillierte Spezifikationen)
+> 📝 Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs)
---
-## 👥 Mitwirkende
+## 👥 Contributors
-[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
+[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
-### So leisten Sie einen Beitrag
+### How to Contribute
-1. Forken Sie das Repository
-2. Erstellen Sie Ihren Feature-Zweig (`git checkout -b feature/amazing-feature`)
-3. Übernehmen Sie Ihre Änderungen (`git commit -m 'Add amazing feature'`)
-4. Push zum Zweig (`git push origin feature/amazing-feature`)
-5. Öffnen Sie eine Pull-Anfrage
+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
-Detaillierte Richtlinien finden Sie unter [CONTRIBUTING.md](CONTRIBUTING.md).
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
-### Veröffentlichung einer neuen Version
+### Releasing a New Version
```bash
# Create a release — npm publish happens automatically
@@ -1638,28 +2092,28 @@ gh release create v2.0.0 --title "v2.0.0" --generate-notes
---
-## 📊 Sterngeschichte
+## 📊 Star History
## Stargazers over time
## [](https://starchart.cc/diegosouzapw/OmniRoute)
-## 🙏 Danksagungen
+## 🙏 Acknowledgments
-Besonderer Dank geht an **[9router](https://github.com/decolua/9router)** von **[decolua](https://github.com/decolua)** – das ursprüngliche Projekt, das diesen Fork inspiriert hat. OmniRoute baut auf dieser unglaublichen Grundlage mit zusätzlichen Funktionen, multimodalen APIs und einer vollständigen Neufassung von TypeScript auf.
+Special thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.
-Besonderer Dank geht an **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** – die ursprüngliche Go-Implementierung, die diese JavaScript-Portierung inspiriert hat.
+Special thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.
---
-## 📄 Lizenz
+## Lizenz
-MIT-Lizenz – Einzelheiten finden Sie unter [LIZENZ](LICENSE).
+MIT License - see [LICENSE](LICENSE) for details.
---
Klicken Sie hier, um die Tech-Stack-Details zu erweitern
+Click to expand tech stack details
-- **Laufzeit**: Node.js 18–22 LTS (⚠️ Node.js 24+ wird **nicht unterstützt** – native Binärdateien von `better-sqlite3` sind inkompatibel) -- **Sprache**: TypeScript 5.9 – **100 % TypeScript** für `src/` und `open-sse/` (null `any` in Kernmodulen seit Version 2.0) +- **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 -- **Datenbank**: LowDB (JSON) + SQLite (Domänenstatus + Proxy-Protokolle + MCP-Prüfung + Routing-Entscheidungen) -- **Schemas**: Zod (MCP-Tool-I/O-Validierung, API-Verträge) -- **Protokolle**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE) -- **Streaming**: Vom Server gesendete Ereignisse (SSE) -- **Auth**: OAuth 2.0 (PKCE) + JWT + API-Schlüssel + MCP-bezogene Autorisierung -- **Testen**: Node.js-Testläufer + Vitest (über 900 Tests einschließlich Einheit, Integration, E2E)- **CI/CD**: GitHub-Aktionen (automatische NPM-Veröffentlichung + Docker Hub bei Veröffentlichung) +- **Database**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions) +- **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) -- **Paket**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute) +- **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) -- **Resilienz**: Leistungsschalter, exponentielles Backoff, Anti-Donner-Herde, TLS-Spoofing, automatische Kombinations-Selbstheilung +- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing
- BErstellt mit ❤️ für Entwickler, die rund um die Uhr programmieren
+ Built with ❤️ for developers who code 24/7
omniroute.online
diff --git a/docs/i18n/de/docs/FEATURES.md b/docs/i18n/de/docs/FEATURES.md
new file mode 100644
index 0000000000..1680d2013c
--- /dev/null
+++ b/docs/i18n/de/docs/FEATURES.md
@@ -0,0 +1,145 @@
+# OmniRoute — Dashboard Features Gallery (Deutsch)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/FEATURES.md) · 🇪🇸 [es](../../es/docs/FEATURES.md) · 🇫🇷 [fr](../../fr/docs/FEATURES.md) · 🇩🇪 [de](../../de/docs/FEATURES.md) · 🇮🇹 [it](../../it/docs/FEATURES.md) · 🇷🇺 [ru](../../ru/docs/FEATURES.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FEATURES.md) · 🇯🇵 [ja](../../ja/docs/FEATURES.md) · 🇰🇷 [ko](../../ko/docs/FEATURES.md) · 🇸🇦 [ar](../../ar/docs/FEATURES.md) · 🇮🇳 [in](../../in/docs/FEATURES.md) · 🇹🇭 [th](../../th/docs/FEATURES.md) · 🇻🇳 [vi](../../vi/docs/FEATURES.md) · 🇮🇩 [id](../../id/docs/FEATURES.md) · 🇲🇾 [ms](../../ms/docs/FEATURES.md) · 🇳🇱 [nl](../../nl/docs/FEATURES.md) · 🇵🇱 [pl](../../pl/docs/FEATURES.md) · 🇸🇪 [sv](../../sv/docs/FEATURES.md) · 🇳🇴 [no](../../no/docs/FEATURES.md) · 🇩🇰 [da](../../da/docs/FEATURES.md) · 🇫🇮 [fi](../../fi/docs/FEATURES.md) · 🇵🇹 [pt](../../pt/docs/FEATURES.md) · 🇷🇴 [ro](../../ro/docs/FEATURES.md) · 🇭🇺 [hu](../../hu/docs/FEATURES.md) · 🇧🇬 [bg](../../bg/docs/FEATURES.md) · 🇸🇰 [sk](../../sk/docs/FEATURES.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FEATURES.md) · 🇮🇱 [he](../../he/docs/FEATURES.md) · 🇵🇭 [phi](../../phi/docs/FEATURES.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FEATURES.md)
+
+---
+
+Visual guide to every section of the OmniRoute dashboard.
+
+---
+
+## 🔌 Providers
+
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
+
+
+
+---
+
+## 🎨 Combos
+
+Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
+
+
+
+---
+
+## 📊 Analytics
+
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
+
+
+
+---
+
+## 🏥 System Health
+
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+
+
+
+---
+
+## 🔧 Translator Playground
+
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
+
+
+
+---
+
+## 🎮 Model Playground _(v2.0.9+)_
+
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
+
+---
+
+## 🎨 Themes _(v2.0.5+)_
+
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
+
+## ⚙️ Settings
+
+Comprehensive settings panel with tabs:
+
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning
+- **Advanced** — Configuration overrides
+
+
+
+---
+
+## 🔧 CLI Tools
+
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
+
+
+
+---
+
+## 🤖 CLI Agents _(v2.0.11+)_
+
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
+
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
+
+---
+
+## 🖼️ Media _(v2.0.3+)_
+
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
+
+## 📝 Request Logs
+
+Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
+
+
+
+---
+
+## 🌐 API Endpoint
+
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
+
+
+
+---
+
+## 🔑 API Key Management
+
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
+
+---
+
+## 📋 Audit Log
+
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
+
+---
+
+## 🖥️ Desktop Application
+
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
+
+Key features:
+
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
+
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.
diff --git a/docs/i18n/es/README.md b/docs/i18n/es/README.md
index 6f9cfc8d31..757d67c750 100644
--- a/docs/i18n/es/README.md
+++ b/docs/i18n/es/README.md
@@ -1,24 +1,94 @@
-omniroute.online
-
-
- # 🚀 OmniRoute — El Gateway de IA Gratuito
+# 🚀 OmniRoute — The Free AI Gateway (Español)
-### Nunca dejes de programar. Enrutamiento inteligente hacia **modelos de IA GRATUITOS y económicos** con fallback automático.
-
-_Tu proxy de API universal — un endpoint, 36+ proveedores, cero tiempo de inactividad._
-
-**Chat Completions • Embeddings • Generación de Imágenes • Audio • Reranking • 100% TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Proveedor de IA Gratuito para tus agentes de programación favoritos
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Conecta cualquier IDE o herramienta CLI con IA a través de OmniRoute — gateway de API gratuito para programación ilimitada._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+` tags no longer leak to clients in SSE streaming responses (#585) |
+| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with per-provider/account quota enforcement, idempotency, SHA-256 storage, and optional GitHub issue reporting |
+| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG → generic fallback chain |
+| 🔄 **Model Auto-Sync** | 24h scheduler and manual UI toggle to sync model lists for built-in and custom OpenAI-compatible providers |
+| 🌐 **OpenCode Zen/Go** | Two new providers from @kang-heewon via PR #530: free tier + subscription tier via `OpencodeExecutor` |
+| 🐛 **Gemini CLI OAuth** | Actionable error when `GEMINI_OAUTH_CLIENT_SECRET` is missing in Docker (was cryptic Google error) |
+| 🐛 **OpenCode config** | `saveOpenCodeConfig()` now correctly writes TOML to `XDG_CONFIG_HOME` |
+| 🐛 **Pinned model override** | `body.model` correctly set to `pinnedModel` on context-cache protection |
+| 🐛 **Codex/Claude loop** | `tool_result` blocks now converted to text to stop infinite loops |
+| 🐛 **Login redirect** | Login no longer freezes after skipping password setup |
+| 🐛 **Windows paths** | MSYS2/Git-Bash paths (`/c/...`) normalized to `C:\...` automatically |
+
+---
+
+## 🖼️ Main Dashboard
+
+
-📡 Todos los agentes se conectan vía ` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**Stop wasting money and hitting limits:**
-### 🆕 What's New in v3.0.0
+- Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**OmniRoute solves this:**
+
+- ✅ **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
+- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool
---
-[](https://www.npmjs.com/package/omniroute)
-[](https://hub.docker.com/r/diegosouzapw/omniroute)
-[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
-[](https://omniroute.online)
-[](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
+## 📧 Support
-[🌐 Website](https://omniroute.online) • [🚀 Inicio Rápido](#-inicio-rápido) • [💡 Características](#-características-principales) • [📖 Docs](#-documentación) • [💰 Precios](#-precios-resumidos)
-
-🌐 **Disponible en:** 🇺🇸 [English](../../README.md) | 🇧🇷 [Português (Brasil)](../pt-BR/README.md) | 🇪🇸 [Español](../es/README.md) | 🇫🇷 [Français](../fr/README.md) | 🇮🇹 [Italiano](../it/README.md) | 🇷🇺 [Русский](../ru/README.md) | 🇨🇳 [中文 (简体)](../zh-CN/README.md) | 🇩🇪 [Deutsch](../de/README.md) | 🇮🇳 [हिन्दी](../in/README.md) | 🇹🇭 [ไทย](../th/README.md) | 🇺🇦 [Українська](../uk-UA/README.md) | 🇸🇦 [العربية](../ar/README.md) | 🇯🇵 [日本語](../ja/README.md) | 🇻🇳 [Tiếng Việt](../vi/README.md) | 🇧🇬 [Български](../bg/README.md) | 🇩🇰 [Dansk](../da/README.md) | 🇫🇮 [Suomi](../fi/README.md) | 🇮🇱 [עברית](../he/README.md) | 🇭🇺 [Magyar](../hu/README.md) | 🇮🇩 [Bahasa Indonesia](../id/README.md) | 🇰🇷 [한국어](../ko/README.md) | 🇲🇾 [Bahasa Melayu](../ms/README.md) | 🇳🇱 [Nederlands](../nl/README.md) | 🇳🇴 [Norsk](../no/README.md) | 🇵🇹 [Português (Portugal)](../pt/README.md) | 🇷🇴 [Română](../ro/README.md) | 🇵🇱 [Polski](../pl/README.md) | 🇸🇰 [Slovenčina](../sk/README.md) | 🇸🇪 [Svenska](../sv/README.md) | 🇵🇭 [Filipino](../phi/README.md)
-
-
-
----
-
-## 🖼️
-
-
-
- # 🚀 OmniRoute — El Gateway de IA Gratuito
+# 🚀 OmniRoute — The Free AI Gateway (Español)
-### Nunca dejes de programar. Enrutamiento inteligente hacia **modelos de IA GRATUITOS y económicos** con fallback automático.
-
-_Tu proxy de API universal — un endpoint, 36+ proveedores, cero tiempo de inactividad._
-
-**Chat Completions • Embeddings • Generación de Imágenes • Audio • Reranking • 100% TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Proveedor de IA Gratuito para tus agentes de programación favoritos
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Conecta cualquier IDE o herramienta CLI con IA a través de OmniRoute — gateway de API gratuito para programación ilimitada._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+
+
+[](https://www.npmjs.com/package/omniroute)
+[](https://www.npmjs.com/package/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
+[](https://omniroute.online)
+[](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)
+
+
+
+🌐 **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)
+
+---
+
+## 🆕 What's New in v3.0.0
+
+> **Upgrading from v2.9.5?** — See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes.
+
+| Area | Change |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection remediation |
+| ✅ **Route Validation** | All 176 API routes now validated with Zod schemas + `validateBody()` — CI `check:route-validation:t06` passes |
+| 🐛 **omniModel Tag Leak** | Internal `
+
+
+
+---
+
+## 📸 Dashboard Preview
+
+
+
+
+
+---
+
+### 🤖 Free AI Provider for your favorite coding agents
+
+_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._
Click to see dashboard screenshots
+ +| Page | Screenshot | +| -------------- | ------------------------------------------------- | +| **Providers** |  | +| **Combos** |  | +| **Analytics** |  | +| **Health** |  | +| **Translator** |  | +| **Settings** |  | +| **CLI Tools** |  | +| **Usage Logs** |  | +| **Endpoints** |  | + +
-
+
 OpenClaw @@ -92,586 +162,527 @@ _Conecta cualquier IDE o herramienta CLI con IA a través de OmniRoute — gatew |
http://localhost:20128/v1 o http://cloud.omniroute.online/v1 — una configuración, modelos y cuota ilimitados
+📡 All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 — one config, unlimited models and quota
---
-### 🆕 What's New in v3.0.0
+## 🤔 Why OmniRoute?
-| Area | Change |
-| ------------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal ` Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `
-
-
-
----
-
-## 📸
-
-
-
-
-
----
-
-## 🤔 ¿Por qué OmniRoute?
-
-**Deja de desperdiciar dinero y chocar con límites:**
-
-- ...
- -| # | # | -| ----- | ---------------------------------------- | -| **1** |  | -| **2** |  | -| **3** |  | -| **4** |  | -| **5** |  | -| **6** |  | -| **7** |  | -| **8** |  | -| **9** |  | - - La cuota de suscripción expira sin usar cada mes
-- Los límites de tasa te detienen en medio de la programación
-- APIs caras ($20-50/mes por proveedor)
-- Cambiar manualmente entre proveedores
-
-**OmniRoute resuelve esto:**
-
-- ✅ **Maximiza suscripciones** - Rastrea cuotas, usa cada bit antes del reset
-- ✅ **Fallback automático** - Suscripción → API Key → Barato → Gratuito, cero tiempo de inactividad
-- ✅ **Multi-cuenta** - Round-robin entre cuentas por proveedor
-- ✅ **Universal** - Funciona con Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, cualquier herramienta CLI
-
----
-
-## 📧 Soporte
-
-> 💬 **¡Únete a la comunidad!** [Grupo WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Obtén ayuda, comparte consejos y mantente al día.
+> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.
- **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**: [Grupo de la Comunidad](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Proyecto Original**: [9router por decolua](https://github.com/decolua/9router)
+- **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`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 Cómo Funciona
+## 🔄 How It Works
```
┌─────────────┐
-│ Tu CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
+│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
│ Tool │
└──────┬──────┘
│ http://localhost:20128/v1
↓
┌─────────────────────────────────────────┐
-│ OmniRoute (Enrutador Inteligente) │
-│ • Traducción de formato (OpenAI ↔ Claude) │
-│ • Rastreo de cuota + Embeddings + Imágenes │
-│ • Renovación automática de tokens │
+│ OmniRoute (Smart Router) │
+│ • Format translation (OpenAI ↔ Claude) │
+│ • Quota tracking + Embeddings + Images │
+│ • Auto token refresh │
└──────┬──────────────────────────────────┘
│
- ├─→ [Tier 1: SUSCRIPCIÓN] Claude Code, Codex, Gemini CLI
- │ ↓ cuota agotada
+ ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI
+ │ ↓ quota exhausted
├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.
- │ ↓ límite de presupuesto
- ├─→ [Tier 3: BARATO] GLM ($0.6/1M), MiniMax ($0.2/1M)
- │ ↓ límite de presupuesto
- └─→ [Tier 4: GRATUITO] iFlow, Qwen, Kiro (ilimitado)
+ │ ↓ budget limit
+ ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)
+ │ ↓ budget limit
+ └─→ [Tier 4: FREE] iFlow, Qwen, Kiro (unlimited)
-Resultado: Nunca dejes de programar, costo mínimo
+Result: Never stop coding, minimal cost
```
---
-## 🎯 Lo que resuelve OmniRoute: 30 puntos débiles reales y casos de uso
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **Todos los desarrolladores que utilizan herramientas de IA se enfrentan a estos problemas a diario.** OmniRoute se creó para resolverlos todos: desde sobrecostos hasta bloqueos regionales, desde flujos rotos de OAuth hasta operaciones de protocolo y observabilidad empresarial.
+> **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.
-
💸 1. "Pago una suscripción costosa pero aún así me interrumpen los límites"
+💸 1. "I pay for an expensive subscription but still get interrupted by limits"
-Los desarrolladores pagan entre 20 y 200 dólares al mes por Claude Pro, Codex Pro o GitHub Copilot. Incluso pagando, la cuota tiene un límite: 5 horas de uso, límites semanales o límites de tarifa por minuto. A mitad de la sesión de codificación, el proveedor deja de responder y el desarrollador pierde flujo y productividad. +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. -**Cómo lo resuelve OmniRoute:** +**How OmniRoute solves it:** -- **Reserva inteligente de 4 niveles**: si se agota la cuota de suscripción, se redirige automáticamente a la clave API → Barato → Gratis sin intervención manual -- **Seguimiento de cuotas en tiempo real**: muestra el consumo de tokens en tiempo real con cuenta regresiva de reinicio (5 h, diario, semanal) -- **Soporte multicuenta**: varias cuentas por proveedor con rotación automática: cuando una se agota, cambia a la siguiente -- **Combinaciones personalizadas**: cadenas de respaldo personalizables con 6 estrategias de equilibrio (completar primero, por turnos, P2C, aleatoria, menos utilizada, de costo optimizado) -- **Cuotas comerciales de Codex**: monitoreo de cuotas del espacio de trabajo empresarial/de equipo directamente en el panel +- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention +- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly) +- **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 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
-` de modelos como DeepSeek R1 en `reasoning_content` estandarizado.
-- **Salida estructurada para Gemini** — `json_schema` → `responseMimeType`/`responseSchema` conversión automática
-- **`stream` por defecto es `false`**: se alinea con las especificaciones de OpenAI, evitando SSE inesperado en los SDK de Python/Rust/Go
+- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 67+ 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
🔌 2. "Necesito usar varios proveedores pero cada uno tiene una API diferente"
+🔌 2. "I need to use multiple providers but each has a different API"
-OpenAI usa un formato, Claude (Anthropic) usa otro, Gemini otro más. Si un desarrollador quiere probar modelos de diferentes proveedores o recurrir a ellos, debe reconfigurar los SDK, cambiar los puntos finales y lidiar con formatos incompatibles. Los proveedores personalizados (FriendLI, NIM) tienen puntos finales de modelo no estándar. +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. -**Cómo lo resuelve OmniRoute:** +**How OmniRoute solves it:** -- **Punto final unificado**: un único `http://localhost:20128/v1` sirve como proxy para los más de 36 proveedores -- **Traducción de formato**: automática y transparente: OpenAI ↔ Claude ↔ Gemini ↔ API de respuestas -- **Desinfección de respuesta**: elimina los campos no estándar (`x_groq`, `usage_breakdown`, `service_tier`) que interrumpen OpenAI SDK v1.83+ -- **Normalización de roles**: convierte `developer` → `system` para proveedores que no son OpenAI; `system` → `user` para GLM/ERNIE -- **Think Tag Extraction**: extrae bloques `
-
🌐 3. "Mi proveedor de IA bloquea mi región/país"
+🌐 3. "My AI provider blocks my region/country"
-Proveedores como OpenAI/Codex bloquean el acceso desde ciertas regiones geográficas. Los usuarios obtienen errores como `unsupported_country_region_territory` durante las conexiones OAuth y API. Esto resulta especialmente frustrante para los desarrolladores de los países en desarrollo. +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. -**Cómo lo resuelve OmniRoute:** +**How OmniRoute solves it:** -- **Configuración de proxy de 3 niveles**: Proxy configurable en 3 niveles: global (todo el tráfico), por proveedor (un solo proveedor) y por conexión/clave. -- **Insignias de proxy codificadas por colores** — Indicadores visuales: 🟢 proxy global, 🟡 proxy de proveedor, 🔵 proxy de conexión, que siempre muestra la IP -- **Intercambio de tokens de OAuth a través de proxy**: el flujo de OAuth también pasa a través del proxy, lo que resuelve `unsupported_country_region_territory` -- **Pruebas de conexión a través de proxy**: las pruebas de conexión utilizan el proxy configurado (no más derivación directa) -- **Soporte SOCKS5**: soporte completo de proxy SOCKS5 para enrutamiento saliente -- **Suplantación de huellas dactilares TLS**: huella digital TLS similar a la de un navegador a través de `wreq-js` para evitar la detección de bots. +- **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
-` prefix
-- **Combos solo gratuitos**: cadena `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/mes sin tiempo de inactividad
-- **Créditos gratuitos NVIDIA NIM**: 1000 créditos gratuitos integrados
-- **Estrategia de optimización de costos**: estrategia de enrutamiento que elige automáticamente el proveedor más barato disponible
+- **Free-Only Combos** — Chain `gc/gemini-3-flash → 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
🆓 4. "Quiero usar IA para codificar pero no tengo dinero"
+🆓 4. "I want to use AI for coding but I have no money"
-No todo el mundo puede pagar entre 20 y 200 dólares al mes por suscripciones a IA. Los estudiantes, desarrolladores de países emergentes, aficionados y autónomos necesitan acceso a modelos de calidad sin costo alguno. +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. -**Cómo lo resuelve OmniRoute:** +**How OmniRoute solves it:** -- **Proveedores de nivel gratuito integrados**: soporte nativo para proveedores 100% gratuitos: iFlow (8 modelos ilimitados), Qwen (3 modelos ilimitados), Kiro (Claude gratis), Gemini CLI (180K/mes gratis) +- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free) - **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/
-
🔒 5. "Necesito proteger mi puerta de enlace AI del acceso no autorizado"
+🔒 5. "I need to protect my AI gateway from unauthorized access"
-Al exponer una puerta de enlace de IA a la red (LAN, VPS, Docker), cualquiera con la dirección puede consumir los tokens/cuota del desarrollador. Sin protección, las API son vulnerables al mal uso, la inyección rápida y el abuso. +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. -**Cómo lo resuelve OmniRoute:** +**How OmniRoute solves it:** -- **Administración de claves API**: generación, rotación y alcance por proveedor con una página `/dashboard/api-manager` dedicada -- **Permisos a nivel de modelo**: restrinja las claves API a modelos específicos (`openai/*`, patrones comodín), con la opción Permitir todo/Restringir -- **API Endpoint Protection**: requiere una clave para `/v1/models` y bloquea proveedores específicos del listado -- **Auth Guard + Protección CSRF**: todas las rutas del panel protegidas con middleware `withAuth` + tokens CSRF -- **Limitador de velocidad**: limitación de velocidad por IP con ventanas configurables -- **Filtrado de IP**: lista permitida/lista bloqueada para control de acceso -- **Prompt injection guard**: desinfección contra patrones de avisos maliciosos -- **Cifrado AES-256-GCM**: credenciales cifradas en reposo +- **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. "Mi proveedor dejó de funcionar y perdí mi flujo de codificación"
+🛑 6. "My provider went down and I lost my coding flow"
-Los proveedores de IA pueden volverse inestables, devolver errores 5xx o alcanzar límites de velocidad temporales. Si un desarrollador depende de un solo proveedor, se le interrumpe. Sin disyuntores, los reintentos repetidos pueden bloquear la aplicación. +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. -**Cómo lo resuelve OmniRoute:** +**How OmniRoute solves it:** -- **Disyuntor por proveedor**: apertura/cierre automático con umbrales configurables y enfriamiento (cerrado/abierto/medio abierto) -- **Retroceso exponencial**: retrasos progresivos en los reintentos -- **Anti-Thundering Herd** — Mutex + protección de semáforo contra tormentas de reintentos simultáneos -- **Cadenas alternativas combinadas**: si el proveedor principal falla, automáticamente pasa por la cadena sin intervención. -- **Disyuntor combinado**: desactiva automáticamente los proveedores defectuosos dentro de una cadena combinada -- **Panel de estado**: monitoreo del tiempo de actividad, estados de disyuntores, bloqueos, estadísticas de caché, latencia p50/p95/p99 +- **Circuit Breaker per-model** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks +- **Exponential Backoff** — Progressive retry delays +- **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 +- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain +- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
-
🔧 7. "Configurar cada herramienta de IA es tedioso y repetitivo"
+🔧 7. "Configuring each AI tool is tedious and repetitive"
-Los desarrolladores utilizan Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Cada herramienta necesita una configuración diferente (punto final API, clave, modelo). Reconfigurar al cambiar de proveedor o modelo es una pérdida de tiempo. +Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time. -**Cómo lo resuelve OmniRoute:** +**How OmniRoute solves it:** -- **Panel de herramientas CLI**: página dedicada con configuración con un solo clic para Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline -- **Generador de configuración de GitHub Copilot**: genera `chatLanguageModels.json` para código VS con selección de modelo masivo -- **Asistente de incorporación**: configuración guiada de 4 pasos para usuarios nuevos -- **Un punto final, todos los modelos**: configure `http://localhost:20128/v1` una vez, acceda a más de 36 proveedores +- **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 67+ providers
-
🔑 8. "Administrar tokens OAuth de múltiples proveedores es un infierno"
+🔑 8. "Managing OAuth tokens from multiple providers is hell"
-Claude Code, Codex, Gemini CLI, Copilot: todos usan OAuth 2.0 con tokens que caducan. Los desarrolladores necesitan volver a autenticarse constantemente, lidiar con `client_secret is missing`, `redirect_uri_mismatch` y fallas en servidores remotos. OAuth en LAN/VPS es particularmente problemático. +Claude Code, Codex, Gemini CLI, 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. -**Cómo lo resuelve OmniRoute:** +**How OmniRoute solves it:** -- **Actualización automática de tokens**: los tokens de OAuth se actualizan en segundo plano antes de que caduquen -- **OAuth 2.0 (PKCE) integrado**: flujo automático para Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow -- **OAuth multicuenta**: varias cuentas por proveedor mediante extracción de token JWT/ID -- **OAuth LAN/Remote Fix** — Detección de IP privada para `redirect_uri` + modo URL manual para servidores remotos -- **OAuth detrás de Nginx**: utiliza `window.location.origin` para compatibilidad con proxy inverso -- **Guía remota de OAuth**: guía paso a paso para las credenciales de Google Cloud en VPS/Docker +- **Auto Token Refresh** — OAuth tokens refresh in background before expiration +- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow +- **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. "No sé cuánto estoy gastando ni dónde"
+📊 9. "I don't know how much I'm spending or where"
-Los desarrolladores utilizan múltiples proveedores pagos pero no tienen una visión unificada del gasto. Cada proveedor tiene su propio panel de facturación, pero no hay una vista consolidada. Los costos inesperados pueden acumularse. +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. -**Cómo lo resuelve OmniRoute:** +**How OmniRoute solves it:** -- **Panel de análisis de costos**: seguimiento de costos por token y gestión de presupuesto por proveedor -- **Límites de presupuesto por nivel**: límite de gasto por nivel que activa el respaldo automático -- **Configuración de precios por modelo**: precios configurables por modelo -- **Estadísticas de uso por clave API**: recuento de solicitudes y marca de tiempo utilizada por última vez por clave -- **Panel de análisis**: tarjetas de estadísticas, tabla de uso de modelos, tabla de proveedores con tasas de éxito y latencia. +- **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. "No puedo diagnosticar errores y problemas en llamadas AI"
+🐛 10. "I can't diagnose errors and problems in AI calls"
-Cuando falla una llamada, el desarrollador no sabe si se trata de un límite de velocidad, un token caducado, un formato incorrecto o un error del proveedor. Registros fragmentados en diferentes terminales. Sin observabilidad, la depuración es de prueba y error. +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. -**Cómo lo resuelve OmniRoute:** +**How OmniRoute solves it:** -- **Panel de registros unificados**: 4 pestañas: registros de solicitudes, registros de proxy, registros de auditoría y consola -- **Visor de registros de consola**: visor estilo terminal en tiempo real con niveles codificados por colores, desplazamiento automático, búsqueda y filtro -- **Registros de proxy SQLite**: registros persistentes que sobreviven a los reinicios del servidor -- **Translator Playground**: 4 modos de depuración: Playground (traducción de formato), Chat Tester (ida y vuelta), Test Bench (por lotes), Live Monitor (en tiempo real) -- **Solicitud de telemetría**: latencia p50/p95/p99 + seguimiento de X-Request-Id -- **Registro basado en archivos con rotación**: el interceptor de consola captura todo en el registro JSON con rotación basada en el tamaño. +- **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 Proxy Logs** — Persistent logs that survive server restarts +- **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 Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation +- **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. "Implementar y mantener la puerta de enlace es complejo"
+🏗️ 11. "Deploying and maintaining the gateway is complex"
-Instalar, configurar y mantener un proxy de IA en diferentes entornos (local, VPS, Docker, nube) requiere mucha mano de obra. Problemas como rutas codificadas, `EACCES` en directorios, conflictos de puertos y compilaciones multiplataforma añaden fricción. +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. -**Cómo lo resuelve OmniRoute:** +**How OmniRoute solves it:** -- **instalación global de npm** — `npm install -g omniroute && omniroute` — hecho -- **Docker multiplataforma**: AMD64 + ARM64 nativo (Apple Silicon, AWS Graviton, Raspberry Pi) -- **Perfiles de Docker Compose**: `base` (sin herramientas CLI) y `cli` (con Claude Code, Codex, OpenClaw) -- **Aplicación de escritorio Electron**: aplicación nativa para Windows/macOS/Linux con bandeja del sistema, inicio automático y modo sin conexión -- **Modo de puerto dividido**: API y panel en puertos separados para escenarios avanzados (proxy inverso, redes de contenedores) -- **Cloud Sync**: sincronización de configuración entre dispositivos a través de Cloudflare Workers -- **Copias de seguridad de base de datos**: copia de seguridad, restauración, exportación e importación automáticas de todas las configuraciones +- **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
-
🌍 12. "La interfaz es solo en inglés y mi equipo no habla inglés"
+🌍 12. "The interface is English-only and my team doesn't speak English"
-Los equipos en países que no hablan inglés, especialmente en América Latina, Asia y Europa, tienen dificultades con las interfaces solo en inglés. Las barreras del idioma reducen la adopción y aumentan los errores de configuración. +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. -**Cómo lo resuelve OmniRoute:** +**How OmniRoute solves it:** -- **Panel i18n — 30 idiomas** — Las más de 500 teclas traducidas, incluidas árabe, búlgaro, danés, alemán, español, finlandés, francés, hebreo, hindi, húngaro, indonesio, italiano, japonés, coreano, malayo, holandés, noruego, polaco, portugués (PT/BR), rumano, ruso, eslovaco, sueco, tailandés, ucraniano, vietnamita, chino, filipino, inglés. -- **Soporte RTL**: soporte de derecha a izquierda para árabe y hebreo -- **README multilingüe**: 30 traducciones de documentación completa -- **Selector de idioma**: ícono de globo en el encabezado para cambiar en tiempo real +- **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. "Necesito más que chat: necesito incrustaciones, imágenes y audio"
+🔄 13. "I need more than chat — I need embeddings, images, audio"
-La IA no es solo completar un chat. Los desarrolladores necesitan generar imágenes, transcribir audio, crear incrustaciones para RAG, reclasificar documentos y moderar contenido. Cada API tiene un punto final y un formato diferentes. +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. -**Cómo lo resuelve OmniRoute:** +**How OmniRoute solves it:** -- **Integraciones** — `/v1/embeddings` con 6 proveedores y más de 9 modelos -- **Generación de imágenes** — `/v1/images/generations` con 10 proveedores y más de 20 modelos (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI) -- **Texto a vídeo** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) y SD WebUI -- **Texto a música** — `/v1/music/generations` — ComfyUI (audio estable abierto, MusicGen) -- **Transcripción de audio** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3 -- **Texto a voz** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, Inworld, Cartesia, PlayHT y proveedores existentes -- **Moderaciones** — `/v1/moderations` — Comprobaciones de seguridad del contenido -- **Reclasificación** — `/v1/rerank` — Reclasificación de relevancia del documento -- **API de respuestas**: compatibilidad total con `/v1/responses` para Codex +- **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. "No tengo forma de probar y comparar la calidad entre modelos"
+🧪 14. "I have no way to test and compare quality across models"
-Los desarrolladores quieren saber qué modelo es mejor para su caso de uso (código, traducción, razonamiento), pero comparar manualmente es lento. No existen herramientas de evaluación integradas. +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. -**Cómo lo resuelve OmniRoute:** +**How OmniRoute solves it:** -- **Evaluaciones LLM**: pruebas de conjunto dorado con 10 casos precargados que cubren saludos, matemáticas, geografía, generación de código, cumplimiento de JSON, traducción, rebajas y rechazo de seguridad. -- **4 estrategias de coincidencia**: `exact`, `contains`, `regex`, `custom` (función JS) -- **Translator Playground Test Bench**: pruebas por lotes con múltiples entradas y resultados esperados, comparación entre proveedores -- **Chat Tester**: recorrido completo de ida y vuelta con representación de respuesta visual -- **Live Monitor**: flujo en tiempo real de todas las solicitudes que fluyen a través del proxy +- **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. "Necesito escalar sin perder rendimiento"
+📈 15. "I need to scale without losing performance"
-A medida que crece el volumen de solicitudes, sin almacenar en caché las mismas preguntas generan costos duplicados. Sin idempotencia, las solicitudes duplicadas desperdician el procesamiento. Se deben respetar los límites de tarifas por proveedor. +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. -**Cómo lo resuelve OmniRoute:** +**How OmniRoute solves it:** -- **Caché semántica**: la caché de dos niveles (firma + semántica) reduce el costo y la latencia -- **Solicitud de idempotencia**: ventana de deduplicación de 5 segundos para solicitudes idénticas -- **Detección de límite de velocidad**: RPM por proveedor, intervalo mínimo y seguimiento simultáneo máximo -- **Límites de velocidad editables**: valores predeterminados configurables en Configuración → Resiliencia con persistencia -- **Caché de validación de clave API**: caché de 3 niveles para rendimiento de producción -- **Panel de estado con telemetría**: latencia p50/p95/p99, estadísticas de caché, tiempo de actividad +- **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 +- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence +- **API Key Validation Cache** — 3-tier cache for production performance +- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
-
🤖 16. "Quiero controlar el comportamiento del modelo globalmente"
+🤖 16. "I want to control model behavior globally"
-Desarrolladores que quieran todas las respuestas en un idioma específico, con un tono específico o quieran limitar los tokens de razonamiento. Configurar esto en cada herramienta/solicitud no es práctico. +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. -**Cómo lo resuelve OmniRoute:** +**How OmniRoute solves it:** -- **Inyección de aviso del sistema**: aviso global aplicado a todas las solicitudes -- **Thinking Budget Validation**: control de asignación de tokens de razonamiento por solicitud (transferencia, automática, personalizada, adaptativa) -- **6 estrategias de enrutamiento**: estrategias globales que determinan cómo se distribuyen las solicitudes -- **Enrutador comodín**: los patrones `provider/*` se enrutan dinámicamente a cualquier proveedor -- **Activar/desactivar combinación de alternar**: alterna combinaciones directamente desde el panel -- **Alternar proveedor**: activa/desactiva todas las conexiones de un proveedor con un solo clic -- **Proveedores bloqueados**: excluye proveedores específicos del listado `/v1/models` +- **System Prompt Injection** — Global prompt applied to all requests +- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive) +- **6 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 +- **Provider Toggle** — Enable/disable all connections for a provider with one click +- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
-
🧰 17. "Necesito herramientas MCP como capacidades de producto de primera clase"
+🧰 17. "I need MCP tools as first-class product capabilities"
-Muchas puertas de enlace de IA exponen MCP solo como un detalle de implementación oculto. Los equipos necesitan una capa operativa visible y manejable. +Many AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer. -**Cómo lo resuelve OmniRoute:** +**How OmniRoute solves it:** -- MCP aparece en la pestaña de navegación del panel y protocolo de punto final -- Página de gestión de MCP dedicada con procesos, herramientas, alcances y auditoría -- Inicio rápido integrado para `omniroute --mcp` e incorporación de clientes +- 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. "Necesito orquestación A2A con rutas de tareas de sincronización + transmisión"
+🧠 18. "I need A2A orchestration with sync + stream task paths"
-Los flujos de trabajo de los agentes necesitan respuestas directas y una ejecución continua de larga duración con control del ciclo de vida. +Agent workflows need both direct replies and long-running streamed execution with lifecycle control. -**Cómo lo resuelve OmniRoute:** +**How OmniRoute solves it:** -- Punto final A2A JSON-RPC (`POST /a2a`) con `message/send` y `message/stream` -- Transmisión SSE con propagación del estado terminal -- API de ciclo de vida de tareas para `tasks/get` y `tasks/cancel` +- 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. "Necesito un estado real del proceso MCP, no un estado adivinado"
+🛰️ 19. "I need real MCP process health, not guessed status"
-Los equipos operativos necesitan saber si MCP está realmente activo, no solo si se puede acceder a una API. +Operational teams need to know if MCP is actually alive, not just whether an API is reachable. -**Cómo lo resuelve OmniRoute:** +**How OmniRoute solves it:** -- Archivo de latidos en tiempo de ejecución con PID, marcas de tiempo, transporte, recuento de herramientas y modo de alcance -- API de estado de MCP que combina latidos + actividad reciente -- Tarjetas de estado de la interfaz de usuario para el proceso/tiempo de actividad/actualización de latidos +- 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. "Necesito ejecución de herramienta MCP auditable"
+📋 20. "I need auditable MCP tool execution"
-Cuando las herramientas modifican la configuración o desencadenan acciones de operaciones, los equipos necesitan trazabilidad forense. +When tools mutate config or trigger ops actions, teams need forensic traceability. -**Cómo lo resuelve OmniRoute:** +**How OmniRoute solves it:** -- Registro de auditoría respaldado por SQLite para llamadas a herramientas MCP -- Filtros por herramienta, éxito/fracaso, clave API y paginación -- Tabla de auditoría del panel + puntos finales de estadísticas para automatización +- 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. "Necesito permisos MCP con alcance por integración"
+🔐 21. "I need scoped MCP permissions per integration"
-Los diferentes clientes deberían tener acceso con privilegios mínimos a las categorías de herramientas. +Different clients should have least-privilege access to tool categories. -**Cómo lo resuelve OmniRoute:** +**How OmniRoute solves it:** -- 9 alcances MCP granulares para acceso controlado a herramientas -- Aplicación del alcance y visibilidad en la interfaz de usuario de gestión de MCP -- Postura predeterminada segura para herramientas operativas +- 9 granular MCP scopes for controlled tool access +- Scope enforcement and visibility in MCP management UI +- Safe default posture for operational tooling
-
⚙️ 22. "Necesito controles operativos sin redistribuir"
+⚙️ 22. "I need operational controls without redeploying"
-Los equipos necesitan cambios rápidos en el tiempo de ejecución durante incidentes o eventos de costos. +Teams need quick runtime changes during incidents or cost events. -**Cómo lo resuelve OmniRoute:** +**How OmniRoute solves it:** -- Cambie la activación combinada directamente desde el panel de MCP -- Aplicar perfiles de resiliencia de paquetes de políticas predefinidos -- Restablecer el estado del disyuntor desde el mismo panel de operaciones. +- Switch combo activation directly from MCP dashboard +- Apply resilience profiles from pre-defined policy packs +- Reset circuit breaker state from the same operations panel
-
🔄 23. "Necesito visibilidad y cancelación del ciclo de vida de la tarea A2A en vivo"
+🔄 23. "I need live A2A task lifecycle visibility and cancellation"
-Sin visibilidad del ciclo de vida, los incidentes de tareas se vuelven difíciles de clasificar. +Without lifecycle visibility, task incidents become hard to triage. -**Cómo lo resuelve OmniRoute:** +**How OmniRoute solves it:** -- Listado de tareas/filtrado por estado/habilidad con paginación -- Profundización en metadatos, eventos y artefactos de tareas -- Punto final de cancelación de tarea y acción de UI con confirmación +- 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. "Necesito métricas de transmisión activas para la carga A2A"
+🌊 24. "I need active stream metrics for A2A load"
-Los flujos de trabajo de streaming requieren información operativa sobre la simultaneidad y las conexiones en vivo. +Streaming workflows require operational insight into concurrency and live connections. -**Cómo lo resuelve OmniRoute:** +**How OmniRoute solves it:** -- Contadores de flujo activos integrados en el estado A2A -- Marca de tiempo de la última tarea y recuentos por estado -- Tarjetas de tablero A2A para monitoreo de operaciones en tiempo real +- Active stream counters integrated into A2A status +- Last task timestamp and per-state counts +- A2A dashboard cards for real-time ops monitoring
-
🪪 25. "Necesito descubrimiento de agente estándar para clientes"
+🪪 25. "I need standard agent discovery for clients"
-Los clientes y orquestadores externos necesitan metadatos legibles por máquina para la incorporación. +External clients and orchestrators need machine-readable metadata for onboarding. -**Cómo lo resuelve OmniRoute:** +**How OmniRoute solves it:** -- Tarjeta de agente expuesta en `/.well-known/agent.json` -- Capacidades y habilidades mostradas en la interfaz de usuario de gestión. -- La API de estado A2A incluye metadatos de descubrimiento para la automatización +- Agent Card exposed at `/.well-known/agent.json` +- Capabilities and skills shown in management UI +- A2A status API includes discovery metadata for automation
-
🧭 26. "Necesito capacidad de descubrimiento de protocolo en la UX del producto"
+🧭 26. "I need protocol discoverability in the product UX"
-Si los usuarios no pueden descubrir las superficies de protocolo, la calidad de la adopción y el soporte disminuye. +If users cannot discover protocol surfaces, adoption and support quality drop. -**Cómo lo resuelve OmniRoute:** +**How OmniRoute solves it:** -- Entradas de la barra lateral para MCP y A2A -- Pestaña Protocolos de la página del endpoint con inicio rápido y estado -- Enlaces desde la descripción general a paneles de gestión dedicados +- 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. "Necesito validación de protocolo de extremo a extremo con clientes reales"
+🧪 27. "I need end-to-end protocol validation with real clients"
-Las pruebas simuladas no son suficientes para validar la compatibilidad del protocolo antes del lanzamiento. +Mock tests are not enough to validate protocol compatibility before release. -**Cómo lo resuelve OmniRoute:** +**How OmniRoute solves it:** -- Suite E2E que inicia la aplicación y utiliza transporte de cliente MCP SDK real -- Pruebas de cliente A2A para descubrimiento, envío, transmisión, obtención y cancelación de flujos -- Verificar las afirmaciones con las API de auditoría MCP y tareas A2A. +- 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. "Necesito observabilidad unificada en todas las interfaces"
+📡 28. "I need unified observability across all interfaces"
-Dividir la observabilidad por protocolo crea puntos ciegos y MTTR más largos. +Splitting observability by protocol creates blind spots and longer MTTR. -**Cómo lo resuelve OmniRoute:** +**How OmniRoute solves it:** -- Paneles/registros/análisis unificados en un solo producto -- Salud + auditoría + solicitud de telemetría en capas OpenAI, MCP y A2A -- API operativas para estado y automatización. +- Unified dashboards/logs/analytics in one product +- Health + audit + request telemetry across OpenAI, MCP, and A2A layers +- Operational APIs for status and automation
-
💼 29. "Necesito un tiempo de ejecución para proxy + herramientas + orquestación de agentes"
+💼 29. "I need one runtime for proxy + tools + agent orchestration"
-La ejecución de muchos servicios separados aumenta los costos operativos y los modos de falla. +Running many separate services increases operational cost and failure modes. -**Cómo lo resuelve OmniRoute:** +**How OmniRoute solves it:** -- Proxy compatible con OpenAI, servidor MCP y servidor A2A en una sola pila -- Autenticación compartida, resiliencia, almacenamiento de datos y observabilidad. -- Modelo de política consistente en todas las superficies de interacción. +- 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
-
-### Guías de ejemplo (casos de uso integrados)
+### Example Playbooks (Integrated Use Cases)
-**Libro de estrategias A: maximizar la suscripción paga + copia de seguridad económica**
+**Playbook A: Maximize paid subscription + cheap backup**
```txt
Combo: "maximize-claude"
@@ -683,7 +694,7 @@ Monthly cost: $20 + small backup spend
Outcome: higher quality, near-zero interruption
```
-**Libro de estrategias B: pila de codificación de costo cero**
+**Playbook B: Zero-cost coding stack**
```txt
Combo: "free-forever"
@@ -695,7 +706,7 @@ Monthly cost: $0
Outcome: stable free coding workflow
```
-**Libro de estrategias C: cadena alternativa siempre disponible las 24 horas del día, los 7 días de la semana**
+**Playbook C: 24/7 always-on fallback chain**
```txt
Combo: "always-on"
@@ -708,65 +719,132 @@ Combo: "always-on"
Outcome: deep fallback depth for deadline-critical workloads
```
-**Libro de jugadas D: Operaciones del agente con MCP + A2A**
+**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/mcp and /dashboard/a2a
-4) Control incidents with resilience profile + task cancellation
+3) Observe via /dashboard/endpoint (MCP and A2A tabs)
+4) Toggle services via inline status controls
```
---
-## ⚡ Inicio Rápido
+## 🆓 Start Free — Zero Configuration Cost
-**1. Instala globalmente:**
+> 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 **iFlow** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |
+| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |
+| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |
+| 5 | `/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).
+
+## Inicio Rápido
+
+### 1) Install and run
```bash
npm install -g omniroute
omniroute
```
-🎉 El Dashboard se abre en `http://localhost:20128`
+> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:
+>
+> ```bash
+> pnpm install -g omniroute
+> pnpm approve-builds -g # Select all packages → approve
+> omniroute
+> ```
-| Comando | Descripción |
-| ----------------------- | ---------------------------------------------- |
-| `omniroute` | Iniciar servidor (puerto predeterminado 20128) |
-| `omniroute --port 3000` | Usar puerto personalizado |
-| `omniroute --no-open` | No abrir navegador automáticamente |
-| `omniroute --help` | Mostrar ayuda |
+Dashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.
-**2. Conecta un proveedor GRATUITO:**
+| 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 |
-Dashboard → Proveedores → Conectar **Claude Code** o **Antigravity** → Login OAuth → ¡Listo!
+Optional split-port mode:
-**3. Usa en tu herramienta CLI:**
-
-```
-Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Configuración:
- Endpoint: http://localhost:20128/v1
- API Key: [copiar del dashboard]
- Model: if/kimi-k2-thinking
+```bash
+PORT=20128 DASHBOARD_PORT=20129 omniroute
+# API: http://localhost:20128/v1
+# Dashboard: http://localhost:20129
```
-**¡Eso es todo!** Comienza a programar con modelos de IA GRATUITOS.
+### 2) Connect providers and create your API key
-**Alternativa — ejecutar desde código fuente:**
+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
+
+```txt
+Base URL: http://localhost:20128/v1
+API Key: [copy from Endpoint page]
+Model: if/kimi-k2-thinking (or any provider/model prefix)
+```
+
+Works with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.
+
+### 4) Enable and validate protocols (v2.0)
+
+**MCP (for tool-driven operations):**
+
+```bash
+omniroute --mcp
+```
+
+Then connect your MCP client over `stdio` and test tools like:
+
+- `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 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
+PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev
```
---
## 🐳 Docker
-OmniRoute está disponible como imagen Docker pública en [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
+OmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
-**Ejecución rápida:**
+**Quick run:**
```bash
docker run -d \
@@ -777,10 +855,10 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Con archivo de entorno:**
+**With environment file:**
```bash
-# Copia y edita el .env primero
+# Copy and edit .env first
cp .env.example .env
docker run -d \
@@ -792,298 +870,627 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Usando Docker Compose:**
+**Using Docker Compose:**
```bash
-# Perfil base (sin herramientas CLI)
+# Base profile (no CLI tools)
docker compose --profile base up -d
-# Perfil CLI (Claude Code, Codex, OpenClaw integrados)
+# CLI profile (Claude Code, Codex, OpenClaw built-in)
docker compose --profile cli up -d
```
-| Imagen | Tag | Tamaño | Descripción |
-| ------------------------ | -------- | ------ | ---------------------- |
-| `diegosouzapw/omniroute` | `latest` | ~250MB | Última versión estable |
-| `diegosouzapw/omniroute` | `1.0.6` | ~250MB | Versión actual |
+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.
+- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.
+- 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` | `1.0.3` | ~250MB | Current version |
---
----
+## 🖥️ Desktop App — Offline & Always-On
-## 🖥️
+> 🆕 **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.
-> 🆕 **¡NUEVO!** OmniRoute ahora está disponible como **aplicación de escritorio nativa** para Windows, macOS y Linux.
+Run OmniRoute as a standalone desktop app — no terminal, no browser, no internet required for local models. The Electron-based app includes:
-Ejecuta OmniRoute como una aplicación de escritorio autónoma — sin terminal, sin navegador, sin internet necesario para modelos locales. La app basada en Electron incluye:
-
-- 🖥️ **Ventana Nativa** — Ventana dedicada con integración en la bandeja del sistema
-- 🔄 **Inicio Automático** — Inicia OmniRoute al iniciar sesión
-- 🔔 **Notificaciones Nativas** — Recibe alertas sobre cuota o problemas de proveedores
-- ⚡ **Instalación con Un Clic** — NSIS (Windows), DMG (macOS), AppImage (Linux)
-- 🌐 **Modo Sin Conexión** — Funciona completamente offline con servidor incluido
+- 🖥️ **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
### Inicio Rápido
```bash
-npm run electron:dev # Modo desarrollo
-npm run electron:build # Plataforma actual
+# 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)
+npm run electron:build:mac # macOS (.dmg) — x64 & arm64
npm run electron:build:linux # Linux (.AppImage)
```
-📖 Documentación completa: [`electron/README.md`](electron/README.md)
+### 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)
---
-## 💰 Precios Resumidos
+## 💰 Pricing at a Glance
-| Tier | Proveedor | Costo | Reset de Cuota | Mejor Para |
-| ------------------ | ----------------- | ---------------------------- | ----------------- | ----------------------- |
-| **💳 SUSCRIPCIÓN** | Claude Code (Pro) | $20/mes | 5h + semanal | Ya suscrito |
-| | Codex (Plus/Pro) | $20-200/mes | 5h + semanal | Usuarios OpenAI |
-| | Gemini CLI | **GRATUITO** | 180K/mes + 1K/día | ¡Todos! |
-| | GitHub Copilot | $10-19/mes | Mensual | Usuarios GitHub |
-| **🔑 API KEY** | NVIDIA NIM | **GRATUITO** (1000 créditos) | Único | Pruebas gratuitas |
-| | DeepSeek | Por uso | Ninguno | Mejor precio/calidad |
-| | Groq | Tier gratuito + pago | Limitado | Inferencia ultra-rápida |
-| | xAI (Grok) | Por uso | Ninguno | Modelos Grok |
-| | Mistral | Tier gratuito + pago | Limitado | IA Europea |
-| | OpenRouter | Por uso | Ninguno | 100+ modelos |
-| **💰 BARATO** | GLM-4.7 | $0.6/1M | Diario 10h | Respaldo económico |
-| | MiniMax M2.1 | $0.2/1M | Rotativo 5h | Opción más barata |
-| | Kimi K2 | $9/mes fijo | 10M tokens/mes | Costo predecible |
-| **🆓 GRATUITO** | iFlow | $0 | Ilimitado | 8 modelos gratuitos |
-| | Qwen | $0 | Ilimitado | 3 modelos gratuitos |
-| | Kiro | $0 | Ilimitado | Claude gratuito |
+| 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 |
+| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |
+| | 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** | iFlow | **$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 |
-**💡 Consejo Pro:** ¡Comienza con Gemini CLI (180K gratis/mes) + iFlow (ilimitado gratis) = $0 de costo!
+> 🆕 **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
+iFlow (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.
---
-## 💡 Características Principales
+---
-### 🧠 Enrutamiento e Inteligencia
+## 🆓 Free Models — What You Actually Get
-| Característica | Qué Hace |
-| -------------------------------------- | ------------------------------------------------------------------------------- |
-| 🎯 **Fallback Inteligente 4 Tiers** | Auto-enrutamiento: Suscripción → API Key → Barato → Gratuito |
-| 📊 **Rastreo de Cuota en Tiempo Real** | Conteo de tokens en vivo + countdown de reset por proveedor |
-| 🔄 **Traducción de Formato** | OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro transparente |
-| 👥 **Soporte Multi-Cuenta** | Múltiples cuentas por proveedor con selección inteligente |
-| 🔄 **Renovación Automática de Token** | Tokens OAuth se renuevan automáticamente con reintentos |
-| 🎨 **Combos Personalizados** | 6 estrategias: fill-first, round-robin, p2c, random, least-used, cost-optimized |
-| 🧩 **Modelos Personalizados** | Agrega cualquier ID de modelo a cualquier proveedor |
-| 🌐 **Enrutador Wildcard** | Enruta patrones `provider/*` a cualquier proveedor dinámicamente |
-| 🧠 **Presupuesto de Razonamiento** | Modos passthrough, auto, custom y adaptativo para modelos de razonamiento |
-| 🔀 **Model Aliases** | Auto-forward deprecated model IDs to current replacements (built-in + custom) |
-| ⚡ **Background Degradation** | Auto-route background tasks (titles, summaries) to cheaper models |
-| 💬 **Inyección de System Prompt** | System prompt global aplicado en todas las solicitudes |
-| 📄 **API Responses** | Soporte completo de la API Responses de OpenAI (`/v1/responses`) para Codex |
+> 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.
-### 🎵 APIs Multi-Modal
+### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)
-| Característica | Qué Hace |
-| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 🖼️ **Generación de Imágenes** | `/v1/images/generations` — 4 proveedores, 9+ modelos |
-| 📐 **Embeddings** | `/v1/embeddings` — 6 proveedores, 9+ modelos |
-| 🎤 **Transcripción de Audio** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |
-| 🔊 **Texto a Voz** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) |
-| 🛡️ **Moderaciones** | `/v1/moderations` — Verificaciones de seguridad |
-| 🔀 **Reranking** | `/v1/rerank` — Reranking de relevancia de documentos |
+| 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 |
-### 🛡️ Resiliencia y Seguridad
+### 🟢 IFLOW MODELS (Free OAuth — No Credit Card)
-| Característica | Qué Hace |
-| ---------------------------------- | ---------------------------------------------------------------------------- |
-| 🔌 **Circuit Breaker** | Auto-apertura/cierre por proveedor con umbrales configurables |
-| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |
-| 🛡️ **Anti-Thundering Herd** | Mutex + semáforo rate-limit para proveedores con API key |
-| 🧠 **Caché Semántico** | Caché de dos niveles (firma + semántico) reduce costo y latencia |
-| ⚡ **Idempotencia de Solicitud** | Ventana de dedup de 5s para solicitudes duplicadas |
-| 🔒 **Spoofing de Fingerprint TLS** | Bypass de detección de bot vía TLS con wreq-js |
-| 🌐 **Filtrado de IP** | Allowlist/blocklist para control de acceso a la API |
-| 📊 **Rate Limits Editables** | RPM, gap mínimo y concurrencia máxima configurables |
-| 💾 **Rate Limit Persistence** | Learned limits survive restarts via SQLite with 60s debounce + 24h staleness |
-| 🔄 **Token Refresh Resilience** | Per-provider circuit breaker (5 fails→30min) + 30s timeout per attempt |
+| 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 |
-### 📊 Observabilidad y Analytics
+### 🟡 QWEN MODELS (Device Code Auth)
-| Característica | Qué Hace |
-| -------------------------------- | --------------------------------------------------------------------- |
-| 📝 **Logs de Solicitud** | Modo debug con logs completos de request/response |
-| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |
-| 💾 **Logs SQLite** | Logs de proxy persistentes sobreviven a reinicios |
-| 📊 **Dashboard de Analytics** | Recharts: cards de estadísticas, gráfico de uso, tabla de proveedores |
-| 📈 **Rastreo de Progreso** | Eventos de progreso SSE opt-in para streaming |
-| 🧪 **Evaluaciones de LLM** | Pruebas con conjunto golden y 4 estrategias de match |
-| 🔍 **Telemetría de Solicitud** | Agregación de latencia p50/p95/p99 + rastreo X-Request-Id |
-| 📋 **Logs + Cuotas** | Páginas dedicadas para navegación de logs y rastreo de cuotas |
-| 🏥 **Dashboard de Salud** | Uptime, estados de circuit breaker, lockouts, stats de caché |
-| 💰 **Rastreo de Costos** | Gestión de presupuesto + configuración de precios por modelo |
+| 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) |
-### ☁️ Deploy y Sincronización
+### 🟣 GEMINI CLI (Google OAuth)
-| Característica | Qué Hace |
-| --------------------------------- | ------------------------------------------------------------------------------- |
-| 💾 **Cloud Sync** | Sincroniza configuraciones entre dispositivos vía Cloudflare Workers |
-| 🌐 **Deploy en Cualquier Lugar** | Localhost, VPS, Docker, Cloudflare Workers |
-| 🔑 **Gestión de API Keys** | Genera, rota y define alcance de API keys por proveedor |
-| 🧙 **Asistente de Configuración** | Setup guiado en 4 pasos para nuevos usuarios |
-| 🔧 **Dashboard CLI Tools** | Configuración en un clic para Claude, Codex, Cline, OpenClaw, Kilo, Antigravity |
-| 🔄 **Backups de DB** | Backup y restauración automáticos de todas las configuraciones |
+| Model | Prefix | Limit | Rate Limit |
+| ------------------------ | ------ | --------------------------- | ------------- |
+| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |
+| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |
+
+### ⚫ 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
+> iFlow (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 v2.0 is built as an operational platform, not just a relay proxy.
+
+### 🆕 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 Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |
+| 🤖 **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 (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) |
+| 🤝 **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** | 9 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 combo, apply resilience profiles, reset breakers from one control surface |
+
+### 🧠 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** | 6 balancing strategies + fallback chain control |
+| 🌐 **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) |
+| 💬 **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 |
+| ----------------------------------- | -------------------------------------------------------------------------------------- |
+| 🔌 **Circuit Breakers** | Per-model trip/recover with threshold controls |
+| 🎯 **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 |
+| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |
+| 🔑 **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 |
+
+### 📊 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 |
+| 📋 **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 |
+
+### ☁️ Deployment & Platform
+
+| Feature | What It Does |
+| ----------------------------- | --------------------------------------------------------- |
+| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |
+| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |
+| 💾 **Cloud Sync** | Configuration sync via cloud worker |
+| 🔄 **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 |
+
+### Feature Deep Dive
+
+#### Smart fallback with practical cost control
+
+```txt
+Combo: "my-coding-stack"
+ 1. cc/claude-opus-4-6
+ 2. nvidia/llama-3.3-70b
+ 3. glm/glm-4.7
+ 4. if/kimi-k2-thinking
+```
+
+When quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.
+
+#### 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)
+
+#### 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)
🚀 30. "Necesito enviar flujos de trabajo agentes sin expansión de código adhesivo"
+🚀 30. "I need to ship agentic workflows without glue-code sprawl"
-Los equipos pierden velocidad al unir múltiples scripts y servicios ad hoc. +Teams lose velocity when stitching multiple ad-hoc services and scripts. -**Cómo lo resuelve OmniRoute:** +**How OmniRoute solves it:** -- Estrategia de endpoint unificada para clientes y agentes -- UI de gestión de protocolos integradas y rutas de validación de humo -- Fundamentos listos para producción (seguridad, registro, resiliencia, respaldo) +- Unified endpoint strategy for clients and agents +- Built-in protocol management UIs and smoke validation paths +- Production-ready foundations (security, logging, resilience, backup)
-
-## 🧪 Evaluaciones (Evals)
+📖 Detalles de Características
+🧩 MCP Setup (Model Context Protocol)
-### 🎯 Fallback Inteligente 4 Tiers +Start MCP transport in stdio mode: -Crea combos con fallback automático: - -``` -Combo: "my-coding-stack" - 1. cc/claude-opus-4-6 (tu suscripción) - 2. nvidia/llama-3.3-70b (API NVIDIA gratuita) - 3. glm/glm-4.7 (respaldo barato, $0.6/1M) - 4. if/kimi-k2-thinking (fallback gratuito) - -→ Cambia automáticamente cuando la cuota se agota o ocurren errores +```bash +omniroute --mcp ``` -### 📊 Rastreo de Cuota en Tiempo Real +Recommended validation flow: -- Consumo de tokens por proveedor -- Countdown de reset (5 horas, diario, semanal) -- Estimación de costo para tiers pagos -- Reportes de gastos mensuales +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. -### 🔄 Traducción de Formato +Useful APIs for automation: -Traducción transparente entre formatos: - -- **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **OpenAI Responses** -- Tu herramienta CLI envía formato OpenAI → OmniRoute traduce → El proveedor recibe formato nativo -- Funciona con cualquier herramienta que soporte endpoints OpenAI personalizados - -### 👥 Soporte Multi-Cuenta - -- Agrega múltiples cuentas por proveedor -- Round-robin automático o enrutamiento por prioridad -- Fallback a la siguiente cuenta cuando una alcanza la cuota - -### 🔄 Renovación Automática de Token - -- Los tokens OAuth se renuevan automáticamente antes de expirar -- Sin necesidad de re-autenticación manual -- Experiencia transparente en todos los proveedores - -### 🎨 Combos Personalizados - -- Crea combinaciones ilimitadas de modelos -- 6 estrategias: fill-first, round-robin, power-of-two-choices, random, least-used, cost-optimized -- Comparte combos entre dispositivos con Cloud Sync - -### 🏥 Dashboard de Salud - -- Estado del sistema (uptime, versión, uso de memoria) -- Estados de circuit breaker por proveedor (Closed/Open/Half-Open) -- Estado de rate limit y lockouts activos -- Estadísticas de caché de firma -- Telemetría de latencia (p50/p95/p99) + caché de prompt -- Reset de salud con un clic - -### 🔧 Playground del Traductor - -- Debug, prueba y visualiza traducciones de formato de API -- Envía solicitudes y ve cómo OmniRoute traduce entre formatos de proveedores -- Invaluable para troubleshooting de problemas de integración - -### 💾 Cloud Sync - -- Sincroniza proveedores, combos y configuraciones entre dispositivos -- Sincronización automática en segundo plano -- Almacenamiento cifrado seguro +- `GET /api/mcp/status` +- `GET /api/mcp/tools` +- `GET /api/mcp/audit` +- `GET /api/mcp/audit/stats`
+
🤝 A2A Setup (Agent2Agent)
-OmniRoute incluye un framework de evaluación integrado para probar la calidad de respuestas de LLM contra un conjunto golden. Accede vía **Analytics → Evals** en el dashboard. +Discover the agent: -### Conjunto Golden Integrado +```bash +curl http://localhost:20128/.well-known/agent.json +``` -El "OmniRoute Golden Set" precargado contiene 10 casos de prueba que cubren: +Send a task: -- Saludos, matemáticas, geografía, generación de código -- Conformidad de formato JSON, traducción, markdown -- Rechazo de seguridad (contenido dañino), conteo, lógica booleana +```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."}]}}' +``` -### Estrategias de Evaluación +Manage lifecycle: -| Estrategia | Descripción | Ejemplo | -| ---------- | ---------------------------------------------------- | -------------------------------- | -| `exact` | La salida debe coincidir exactamente | `"4"` | -| `contains` | La salida debe contener subcadena (case-insensitive) | `"Paris"` | -| `regex` | La salida debe coincidir con el patrón regex | `"1.*2.*3"` | -| `custom` | Función JS personalizada retorna true/false | `(output) => output.length > 10` | +- `GET /api/a2a/status` +- `GET /api/a2a/tasks` +- `GET /api/a2a/tasks/:id` +- `POST /api/a2a/tasks/:id/cancel` ---- +Operational UI: -## 📖 Guía de Configuración +- `/dashboard/a2a` for task/state/stream observability and smoke actions + +
-
+
+💳 Proveedores por Suscripción
+🧪 End-to-end protocol validation
+ +Validate both protocols with real clients: + +```bash +npm run test:protocols:e2e +``` + +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) ```bash -Dashboard → Proveedores → Conectar Claude Code -→ Login OAuth → Renovación automática de token -→ Rastreo de cuota 5h + semanal +Dashboard → Providers → Connect Claude Code +→ OAuth login → Auto token refresh +→ 5-hour + weekly quota tracking -Modelos: +Models: cc/claude-opus-4-6 cc/claude-sonnet-4-5-20250929 cc/claude-haiku-4-5-20251001 ``` -**Consejo Pro:** Usa Opus para tareas complejas, Sonnet para velocidad. ¡OmniRoute rastrea cuota por modelo! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! ### OpenAI Codex (Plus/Pro) ```bash -Dashboard → Proveedores → Conectar Codex -→ Login OAuth (puerto 1455) -→ Reset 5h + semanal +Dashboard → Providers → Connect Codex +→ OAuth login (port 1455) +→ 5-hour + weekly reset -Modelos: +Models: cx/gpt-5.2-codex cx/gpt-5.1-codex-max ``` -### Gemini CLI (¡GRATUITO 180K/mes!) +#### 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). + +### Gemini CLI (FREE 180K/month!) ```bash -Dashboard → Proveedores → Conectar Gemini CLI +Dashboard → Providers → Connect Gemini CLI → Google OAuth -→ 180K completions/mes + 1K/día +→ 180K completions/month + 1K/day -Modelos: +Models: gc/gemini-3-flash-preview gc/gemini-2.5-pro ``` -**Mejor Valor:** ¡Tier gratuito enorme! Úsalo antes de los tiers pagos. +**Best Value:** Huge free tier! Use this before paid tiers. ### GitHub Copilot ```bash -Dashboard → Proveedores → Conectar GitHub -→ OAuth vía GitHub -→ Reset mensual (1ro del mes) +Dashboard → Providers → Connect GitHub +→ OAuth via GitHub +→ Monthly reset (1st of month) -Modelos: +Models: gh/gpt-5 gh/claude-4.5-sonnet gh/gemini-3-pro @@ -1092,95 +1499,95 @@ Modelos:
-
🔑 Proveedores por API Key
+🔑 API Key Providers
-### NVIDIA NIM (¡GRATUITO 1000 créditos!) +### NVIDIA NIM (FREE developer access — 70+ models) -1. Regístrate: [build.nvidia.com](https://build.nvidia.com) -2. Obtén API key gratuita (1000 créditos de inferencia incluidos) -3. Dashboard → Agregar Proveedor → NVIDIA NIM: +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` -**Modelos:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, y 50+ más +**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more -**Consejo Pro:** ¡API compatible con OpenAI — funciona perfectamente con la traducción de formato de OmniRoute! +**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation! ### DeepSeek -1. Regístrate: [platform.deepseek.com](https://platform.deepseek.com) -2. Obtén API key -3. Dashboard → Agregar Proveedor → DeepSeek +1. Sign up: [platform.deepseek.com](https://platform.deepseek.com) +2. Get API key +3. Dashboard → Add Provider → DeepSeek -**Modelos:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` +**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` -### Groq (¡Tier Gratuito Disponible!) +### Groq (Free Tier Available!) -1. Regístrate: [console.groq.com](https://console.groq.com) -2. Obtén API key (tier gratuito incluido) -3. Dashboard → Agregar Proveedor → Groq +1. Sign up: [console.groq.com](https://console.groq.com) +2. Get API key (free tier included) +3. Dashboard → Add Provider → Groq -**Modelos:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` +**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` -**Consejo Pro:** ¡Inferencia ultra-rápida — mejor para programación en tiempo real! +**Pro Tip:** Ultra-fast inference — best for real-time coding! -### OpenRouter (100+ Modelos) +### OpenRouter (100+ Models) -1. Regístrate: [openrouter.ai](https://openrouter.ai) -2. Obtén API key -3. Dashboard → Agregar Proveedor → OpenRouter +1. Sign up: [openrouter.ai](https://openrouter.ai) +2. Get API key +3. Dashboard → Add Provider → OpenRouter -**Modelos:** Accede a 100+ modelos de todos los principales proveedores a través de una única API key. +**Models:** Access 100+ models from all major providers through a single API key.
-
💰 Proveedores Baratos (Respaldo)
+💰 Cheap Providers (Backup)
-### GLM-4.7 (Reset diario, $0.6/1M) +### GLM-4.7 (Daily reset, $0.6/1M) -1. Regístrate: [Zhipu AI](https://open.bigmodel.cn/) -2. Obtén API key del Plan Coding -3. Dashboard → Agregar API Key: - - Proveedor: `glm` +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` -**Usa:** `glm/glm-4.7` +**Use:** `glm/glm-4.7` -**Consejo Pro:** ¡El Plan Coding ofrece 3× cuota a 1/7 del costo! Reset diario 10:00 AM. +**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -### MiniMax M2.1 (Reset 5h, $0.20/1M) +### MiniMax M2.1 (5h reset, $0.20/1M) -1. Regístrate: [MiniMax](https://www.minimax.io/) -2. Obtén API key -3. Dashboard → Agregar API Key +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key +3. Dashboard → Add API Key -**Usa:** `minimax/MiniMax-M2.1` +**Use:** `minimax/MiniMax-M2.1` -**Consejo Pro:** ¡Opción más barata para contexto largo (1M tokens)! +**Pro Tip:** Cheapest option for long context (1M tokens)! -### Kimi K2 ($9/mes fijo) +### Kimi K2 ($9/month flat) -1. Suscríbete: [Moonshot AI](https://platform.moonshot.ai/) -2. Obtén API key -3. Dashboard → Agregar API Key +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key +3. Dashboard → Add API Key -**Usa:** `kimi/kimi-latest` +**Use:** `kimi/kimi-latest` -**Consejo Pro:** ¡$9/mes fijo por 10M tokens = $0.90/1M de costo efectivo! +**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
-
🆓 Proveedores GRATUITOS (Respaldo de Emergencia)
+🆓 FREE Providers (Emergency Backup)
-### iFlow (8 modelos GRATUITOS) +### iFlow (5 FREE models via OAuth) ```bash -Dashboard → Conectar iFlow -→ Login OAuth iFlow -→ Uso ilimitado +Dashboard → Connect iFlow +→ iFlow OAuth login +→ Unlimited usage -Modelos: +Models: if/kimi-k2-thinking if/qwen3-coder-plus if/glm-4.7 @@ -1188,26 +1595,26 @@ Modelos: if/deepseek-r1 ``` -### Qwen (3 modelos GRATUITOS) +### Qwen (4 FREE models via Device Code) ```bash -Dashboard → Conectar Qwen -→ Autorización por código de dispositivo -→ Uso ilimitado +Dashboard → Connect Qwen +→ Device code authorization +→ Unlimited usage -Modelos: +Models: qw/qwen3-coder-plus qw/qwen3-coder-flash ``` -### Kiro (Claude GRATUITO) +### Kiro (Claude FREE) ```bash -Dashboard → Conectar Kiro -→ AWS Builder ID o Google/GitHub -→ Uso ilimitado +Dashboard → Connect Kiro +→ AWS Builder ID or Google/GitHub +→ Unlimited usage -Modelos: +Models: kr/claude-sonnet-4.5 kr/claude-haiku-4.5 ``` @@ -1215,51 +1622,51 @@ Modelos:
-
🎨 Crear Combos
+🎨 Create Combos
-### Ejemplo 1: Maximizar Suscripción → Respaldo Barato +### Example 1: Maximize Subscription → Cheap Backup ``` -Dashboard → Combos → Crear Nuevo +Dashboard → Combos → Create New -Nombre: premium-coding -Modelos: - 1. cc/claude-opus-4-6 (Suscripción primaria) - 2. glm/glm-4.7 (Respaldo barato, $0.6/1M) - 3. minimax/MiniMax-M2.1 (Fallback más barato, $0.20/1M) +Name: premium-coding +Models: + 1. cc/claude-opus-4-6 (Subscription primary) + 2. glm/glm-4.7 (Cheap backup, $0.6/1M) + 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M) -Usa en CLI: premium-coding +Use in CLI: premium-coding ``` -### Ejemplo 2: Solo Gratuito (Costo Cero) +### Example 2: Free-Only (Zero Cost) ``` -Nombre: free-combo -Modelos: - 1. gc/gemini-3-flash-preview (180K gratis/mes) - 2. if/kimi-k2-thinking (ilimitado) - 3. qw/qwen3-coder-plus (ilimitado) +Name: free-combo +Models: + 1. gc/gemini-3-flash-preview (180K free/month) + 2. if/kimi-k2-thinking (unlimited) + 3. qw/qwen3-coder-plus (unlimited) -Costo: ¡$0 para siempre! +Cost: $0 forever! ```
-
---
-## 🐛 Solución de Problemas
+## Solución de Problemas
🔧 Integración CLI
+🔧 CLI Integration
### Cursor IDE ``` -Configuración → Modelos → Avanzado: +Settings → Models → Advanced: OpenAI API Base URL: http://localhost:20128/v1 - OpenAI API Key: [del dashboard OmniRoute] + OpenAI API Key: [from OmniRoute dashboard] Model: cc/claude-opus-4-6 ``` ### Claude Code -Usa la página **CLI Tools** en el dashboard para configuración en un clic, o edita `~/.claude/settings.json` manualmente. +Use the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually. ### Codex CLI @@ -1272,13 +1679,13 @@ codex "your prompt" ### OpenClaw -**Opción 1 — Dashboard (recomendado):** +**Option 1 — Dashboard (recommended):** ``` -Dashboard → CLI Tools → OpenClaw → Seleccionar Modelo → Aplicar +Dashboard → CLI Tools → OpenClaw → Select Model → Apply ``` -**Opción 2 — Manual:** Edita `~/.openclaw/openclaw.json`: +**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`: ```json { @@ -1294,155 +1701,420 @@ Dashboard → CLI Tools → OpenClaw → Seleccionar Modelo → Aplicar } ``` -> **Nota:** OpenClaw solo funciona con OmniRoute local. Usa `127.0.0.1` en lugar de `localhost` para evitar problemas de resolución IPv6. +> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues. ### Cline / Continue / RooCode ``` -Configuración → Configuración de API: - Proveedor: OpenAI Compatible +Settings → API Configuration: + Provider: OpenAI Compatible Base URL: http://localhost:20128/v1 - API Key: [del dashboard OmniRoute] + 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. +
-
-- **Runtime**: Node.js 20+
-- **Lenguaje**: TypeScript 5.9 — **100% TypeScript** en `src/` y `open-sse/` (v1.0.6)
+## 🛠️ Tech Stack
+
+Haz clic para expandir la guía de solución de problemas
+Click to expand troubleshooting guide
**"Language model did not provide messages"** -- Cuota del proveedor agotada → Verifica el rastreador de cuota en el dashboard -- Solución: Usa combo con fallback o cambia a tier más barato +- Provider quota exhausted → Check dashboard quota tracker +- Solution: Use combo fallback or switch to cheaper tier **Rate limiting** -- Cuota de suscripción agotada → Fallback a GLM/MiniMax -- Agrega combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Subscription quota out → Fallback to GLM/MiniMax +- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -**Token OAuth expirado** +**OAuth token expired** -- Renovado automáticamente por OmniRoute -- Si persiste: Dashboard → Proveedor → Reconectar +- Auto-refreshed by OmniRoute +- If issues persist: Dashboard → Provider → Reconnect -**Costos altos** +**High costs** -- Verifica estadísticas de uso en Dashboard → Costos -- Cambia modelo primario a GLM/MiniMax -- Usa tier gratuito (Gemini CLI, iFlow) para tareas no críticas +- Check usage stats in Dashboard → Costs +- Switch primary model to GLM/MiniMax +- Use free tier (Gemini CLI, iFlow) for non-critical tasks -**Dashboard se abre en el puerto equivocado** +**Dashboard/API ports are wrong** -- Establece `PORT=20128` y `NEXT_PUBLIC_BASE_URL=http://localhost:20128` +- `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) -**Errores de cloud sync** +**Cloud sync errors** -- Verifica que `BASE_URL` apunte a tu instancia en ejecución -- Verifica que `CLOUD_URL` apunte a tu endpoint cloud esperado -- Mantén los valores `NEXT_PUBLIC_*` alineados con los valores del servidor +- 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 -**Primer login no funciona** +**First login not working** -- Verifica `INITIAL_PASSWORD` en `.env` -- Si no está definido, la contraseña predeterminada es `123456` +- Check `INITIAL_PASSWORD` in `.env` +- If unset, fallback password is `123456` -**Sin logs de solicitud** +**No request logs** -- Establece `ENABLE_REQUEST_LOGS=true` en `.env` +- Set `ENABLE_REQUEST_LOGS=true` in `.env` -**Prueba de conexión muestra "Invalid" para proveedores compatibles con OpenAI** +**Connection test shows "Invalid" for OpenAI-compatible providers** -- Muchos proveedores no exponen el endpoint `/models` -- OmniRoute v1.0.6+ incluye validación vía chat completions como fallback -- Asegúrate de que la URL base incluya el sufijo `/v1` +- 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** + +#### Why does Antigravity / Gemini CLI OAuth fail on remote servers? + +The **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console. + +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 + +# For Gemini CLI: +GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com +GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +``` + +**6. Restart OmniRoute** + +```bash +# npm: +npm run dev + +# Docker: +docker restart omniroute +``` + +**7. Try connecting again** + +Dashboard → Providers → Antigravity (or Gemini CLI) → OAuth + +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. + +--- + +
+
---
-## 🛠️
+🇧🇷 Versão em Português
+ +#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos? + +Os provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo. + +As credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticação com: + +``` +Error 400: redirect_uri_mismatch +``` + +#### Solução: Configure suas próprias credenciais OAuth + +Você precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor. + +#### Passo a passo + +**1. Acesse o Google Cloud Console** + +Abra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) + +**2. Crie um novo OAuth 2.0 Client ID** + +- Clique em **"+ Create Credentials"** → **"OAuth client ID"** +- Tipo de aplicativo: **"Web application"** +- Nome: escolha qualquer nome (ex: `OmniRoute Remote`) + +**3. Adicione as Authorized Redirect URIs** + +No campo **"Authorized redirect URIs"**, adicione: + +``` +https://seu-servidor.com/callback +``` + +> Substitua `seu-servidor.com` pelo domínio ou IP do seu servidor (inclua a porta se necessário, ex: `http://45.33.32.156:20128/callback`). + +**4. Salve e copie as credenciais** + +Após criar, o Google mostrará o **Client ID** e o **Client Secret**. + +**5. Configure as variáveis de ambiente** + +No seu `.env` (ou nas variáveis de ambiente do Docker): + +```bash +# Para Antigravity: +ANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com +ANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret + +# Para Gemini CLI: +GEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com +GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret +GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret +``` + +**6. Reinicie o OmniRoute** + +```bash +# Se usando npm: +npm run dev + +# Se usando Docker: +docker restart omniroute +``` + +**7. Tente conectar novamente** + +Dashboard → Providers → Antigravity (ou Gemini CLI) → OAuth + +Agora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará. + +--- + +#### Workaround temporário (sem configurar credenciais próprias) + +Se não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**: + +1. O OmniRoute abrirá a URL de autorização do Google +2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto) +3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue) +4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute +5. Clique em **"Connect"** + +> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.
+
---
-## 📖 Documentación
+## Documentación
-| Documento | Descripción |
-| ------------------------------------------------ | -------------------------------------------------- |
-| [Guía del Usuario](docs/USER_GUIDE.md) | Proveedores, combos, integración CLI, deploy |
-| [Referencia de API](docs/API_REFERENCE.md) | Todos los endpoints con ejemplos |
-| [Solución de Problemas](docs/TROUBLESHOOTING.md) | Problemas comunes y soluciones |
-| [Arquitectura](docs/ARCHITECTURE.md) | Arquitectura del sistema e internos |
-| [Contribuir](CONTRIBUTING.md) | Setup de desarrollo y directrices |
-| [Spec OpenAPI](docs/openapi.yaml) | Especificación OpenAPI 3.0 |
-| [Política de Seguridad](SECURITY.md) | Reportar vulnerabilidades y prácticas de seguridad |
+| Document | Description |
+| ---------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 16 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/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
+| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
-## 🗺️
+## 🗺️ Roadmap
-## 👥 Contribuidores
+OmniRoute has **210+ 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, P2C account selection |
+| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |
+| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |
+| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider 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
[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
-### Cómo Contribuir
+### How to Contribute
-1. Haz fork del repositorio
-2. Crea tu rama de funcionalidad (`git checkout -b feature/amazing-feature`)
-3. Haz commit de tus cambios (`git commit -m 'Add amazing feature'`)
-4. Haz push a la rama (`git push origin feature/amazing-feature`)
-5. Abre un Pull Request
+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
-Consulta [CONTRIBUTING.md](CONTRIBUTING.md) para directrices detalladas.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
-### Lanzar una Nueva Versión
+### Releasing a New Version
```bash
-# Crea un release — la publicación en npm ocurre automáticamente
-gh release create v1.0.6 --title "v1.0.6" --generate-notes
+# Create a release — npm publish happens automatically
+gh release create v2.0.0 --title "v2.0.0" --generate-notes
```
---
-## 📊 Historial de Stars
+## 📊 Star History
## Stargazers over time
## [](https://starchart.cc/diegosouzapw/OmniRoute)
-## 🙏 Agradecimientos
+## 🙏 Acknowledgments
-Agradecimiento especial a **[9router](https://github.com/decolua/9router)** por **[decolua](https://github.com/decolua)** — el proyecto original que inspiró este fork. OmniRoute se construye sobre esa increíble base con características adicionales, APIs multi-modal y una reescritura completa en TypeScript.
+Special thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.
-Agradecimiento especial a **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — la implementación original en Go que inspiró esta adaptación a JavaScript.
+Special thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.
---
-## 📄 Licencia
+## Licencia
-Licencia MIT - consulta [LICENSE](LICENSE) para detalles.
+MIT License - see [LICENSE](LICENSE) for details.
---
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 -- **Base de Datos**: LowDB (JSON) + SQLite (estado del dominio + logs de proxy) +- **Database**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions) +- **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 -- **Testing**: Node.js test runner (368+ tests unitarios) -- **CI/CD**: GitHub Actions (publicación automática npm + Docker Hub en release) +- **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) -- **Paquete**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute) +- **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) -- **Resiliencia**: Circuit breaker, backoff exponencial, anti-thundering herd, spoofing TLS +- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing + +
- Hecho con ❤️ para desarrolladores que programan 24/7
+ Built with ❤️ for developers who code 24/7
omniroute.online
+
diff --git a/docs/i18n/es/docs/FEATURES.md b/docs/i18n/es/docs/FEATURES.md
new file mode 100644
index 0000000000..551412f807
--- /dev/null
+++ b/docs/i18n/es/docs/FEATURES.md
@@ -0,0 +1,145 @@
+# OmniRoute — Dashboard Features Gallery (Español)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/FEATURES.md) · 🇪🇸 [es](../../es/docs/FEATURES.md) · 🇫🇷 [fr](../../fr/docs/FEATURES.md) · 🇩🇪 [de](../../de/docs/FEATURES.md) · 🇮🇹 [it](../../it/docs/FEATURES.md) · 🇷🇺 [ru](../../ru/docs/FEATURES.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FEATURES.md) · 🇯🇵 [ja](../../ja/docs/FEATURES.md) · 🇰🇷 [ko](../../ko/docs/FEATURES.md) · 🇸🇦 [ar](../../ar/docs/FEATURES.md) · 🇮🇳 [in](../../in/docs/FEATURES.md) · 🇹🇭 [th](../../th/docs/FEATURES.md) · 🇻🇳 [vi](../../vi/docs/FEATURES.md) · 🇮🇩 [id](../../id/docs/FEATURES.md) · 🇲🇾 [ms](../../ms/docs/FEATURES.md) · 🇳🇱 [nl](../../nl/docs/FEATURES.md) · 🇵🇱 [pl](../../pl/docs/FEATURES.md) · 🇸🇪 [sv](../../sv/docs/FEATURES.md) · 🇳🇴 [no](../../no/docs/FEATURES.md) · 🇩🇰 [da](../../da/docs/FEATURES.md) · 🇫🇮 [fi](../../fi/docs/FEATURES.md) · 🇵🇹 [pt](../../pt/docs/FEATURES.md) · 🇷🇴 [ro](../../ro/docs/FEATURES.md) · 🇭🇺 [hu](../../hu/docs/FEATURES.md) · 🇧🇬 [bg](../../bg/docs/FEATURES.md) · 🇸🇰 [sk](../../sk/docs/FEATURES.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FEATURES.md) · 🇮🇱 [he](../../he/docs/FEATURES.md) · 🇵🇭 [phi](../../phi/docs/FEATURES.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FEATURES.md)
+
+---
+
+Visual guide to every section of the OmniRoute dashboard.
+
+---
+
+## 🔌 Providers
+
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
+
+
+
+---
+
+## 🎨 Combos
+
+Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
+
+
+
+---
+
+## 📊 Analytics
+
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
+
+
+
+---
+
+## 🏥 System Health
+
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+
+
+
+---
+
+## 🔧 Translator Playground
+
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
+
+
+
+---
+
+## 🎮 Model Playground _(v2.0.9+)_
+
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
+
+---
+
+## 🎨 Themes _(v2.0.5+)_
+
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
+
+## ⚙️ Settings
+
+Comprehensive settings panel with tabs:
+
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning
+- **Advanced** — Configuration overrides
+
+
+
+---
+
+## 🔧 CLI Tools
+
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
+
+
+
+---
+
+## 🤖 CLI Agents _(v2.0.11+)_
+
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
+
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
+
+---
+
+## 🖼️ Media _(v2.0.3+)_
+
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
+
+## 📝 Request Logs
+
+Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
+
+
+
+---
+
+## 🌐 API Endpoint
+
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
+
+
+
+---
+
+## 🔑 API Key Management
+
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
+
+---
+
+## 📋 Audit Log
+
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
+
+---
+
+## 🖥️ Desktop Application
+
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
+
+Key features:
+
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
+
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.
diff --git a/docs/i18n/fi/README.md b/docs/i18n/fi/README.md
index e009f2b724..d55e6741e0 100644
--- a/docs/i18n/fi/README.md
+++ b/docs/i18n/fi/README.md
@@ -1,24 +1,94 @@
-omniroute.online
-
-
- # 🚀 OmniRoute — ilmainen tekoälyyhdyskäytävä
+# 🚀 OmniRoute — The Free AI Gateway (Suomi)
-### Älä koskaan lopeta koodaamista. Älykäs reititys **ILMAisiin ja edullisiin tekoälymalleihin** automaattisella varalla.
-
-_Universaali API-välityspalvelin – yksi päätepiste, yli 36 palveluntarjoajaa, nolla seisokkia._
-
-**Pikaviestien loppuun saattaminen • upotukset • kuvien luominen • ääni • uudelleensijoitus • 100 % TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Ilmainen AI Provider suosikkikoodaajillesi
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Yhdistä mikä tahansa tekoälyllä toimiva IDE- tai CLI-työkalu OmniRouten kautta – ilmainen API-yhdyskäytävä rajoittamattomaan koodaukseen._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+` tags no longer leak to clients in SSE streaming responses (#585) |
+| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with per-provider/account quota enforcement, idempotency, SHA-256 storage, and optional GitHub issue reporting |
+| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG → generic fallback chain |
+| 🔄 **Model Auto-Sync** | 24h scheduler and manual UI toggle to sync model lists for built-in and custom OpenAI-compatible providers |
+| 🌐 **OpenCode Zen/Go** | Two new providers from @kang-heewon via PR #530: free tier + subscription tier via `OpencodeExecutor` |
+| 🐛 **Gemini CLI OAuth** | Actionable error when `GEMINI_OAUTH_CLIENT_SECRET` is missing in Docker (was cryptic Google error) |
+| 🐛 **OpenCode config** | `saveOpenCodeConfig()` now correctly writes TOML to `XDG_CONFIG_HOME` |
+| 🐛 **Pinned model override** | `body.model` correctly set to `pinnedModel` on context-cache protection |
+| 🐛 **Codex/Claude loop** | `tool_result` blocks now converted to text to stop infinite loops |
+| 🐛 **Login redirect** | Login no longer freezes after skipping password setup |
+| 🐛 **Windows paths** | MSYS2/Git-Bash paths (`/c/...`) normalized to `C:\...` automatically |
+
+---
+
+## 🖼️ Main Dashboard
+
+
-📡 Kaikki agentit muodostavat yhteyden kautta ` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**Stop wasting money and hitting limits:**
-### 🆕 What's New in v3.0.0
+- Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**OmniRoute solves this:**
+
+- ✅ **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
+- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool
---
-[](https://www.npmjs.com/package/omniroute)
-[](https://hub.docker.com/r/diegosouzapw/omniroute)
-[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
-[](https://omniroute.online)
-[](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
+## 📧 Support
-[🌐 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)
+> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.
-🌐 **Available in:** 🇺🇸 [English](../../README.md) | 🇧🇷 [Português (Brasil)](../pt-BR/README.md) | 🇪🇸 [Español](../es/README.md) | 🇫🇷 [Français](../fr/README.md) | 🇮🇹 [Italiano](../it/README.md) | 🇷🇺 [Русский](../ru/README.md) | 🇨🇳 [中文 (简体)](../zh-CN/README.md) | 🇩🇪 [Deutsch](../de/README.md) | 🇮🇳 [हिन्दी](../in/README.md) | 🇹🇭 [ไทย](../th/README.md) | 🇺🇦 [Українська](../uk-UA/README.md) | 🇸🇦 [العربية](../ar/README.md) | 🇯🇵 [日本語](../ja/README.md) | 🇻🇳 [Tiếng Việt](../vi/README.md) | 🇧🇬 [Български](../bg/README.md) | 🇩🇰 [Dansk](../da/README.md) | 🇫🇮 [Suomi](../fi/README.md) | 🇮🇱 [עברית](../he/README.md) | 🇭🇺 [Magyar](../hu/README.md) | 🇮🇩 [Bahasa Indonesia](../id/README.md) | 🇰🇷 [한국어](../ko/README.md) | 🇲🇾 [Bahasa Melayu](../ms/README.md) | 🇳🇱 [Nederlands](../nl/README.md) | 🇳🇴 [Norsk](../no/README.md) | 🇵🇹 [Português (Portugal)](../pt/README.md) | 🇷🇴 [Română](../ro/README.md) | 🇵🇱 [Polski](../pl/README.md) | 🇸🇰 [Slovenčina](../sk/README.md) | 🇸🇪 [Svenska](../sv/README.md) | 🇵🇭 [Filipino](../phi/README.md)
-
-
-
----
-
-## 🖼️
-
-
-
- # 🚀 OmniRoute — ilmainen tekoälyyhdyskäytävä
+# 🚀 OmniRoute — The Free AI Gateway (Suomi)
-### Älä koskaan lopeta koodaamista. Älykäs reititys **ILMAisiin ja edullisiin tekoälymalleihin** automaattisella varalla.
-
-_Universaali API-välityspalvelin – yksi päätepiste, yli 36 palveluntarjoajaa, nolla seisokkia._
-
-**Pikaviestien loppuun saattaminen • upotukset • kuvien luominen • ääni • uudelleensijoitus • 100 % TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Ilmainen AI Provider suosikkikoodaajillesi
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Yhdistä mikä tahansa tekoälyllä toimiva IDE- tai CLI-työkalu OmniRouten kautta – ilmainen API-yhdyskäytävä rajoittamattomaan koodaukseen._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+
+
+[](https://www.npmjs.com/package/omniroute)
+[](https://www.npmjs.com/package/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
+[](https://omniroute.online)
+[](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)
+
+
+
+🌐 **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)
+
+---
+
+## 🆕 What's New in v3.0.0
+
+> **Upgrading from v2.9.5?** — See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes.
+
+| Area | Change |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection remediation |
+| ✅ **Route Validation** | All 176 API routes now validated with Zod schemas + `validateBody()` — CI `check:route-validation:t06` passes |
+| 🐛 **omniModel Tag Leak** | Internal `
+
+
+
+---
+
+## 📸 Dashboard Preview
+
+
+
+
+
+---
+
+### 🤖 Free AI Provider for your favorite coding agents
+
+_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._
Click to see dashboard screenshots
+ +| Page | Screenshot | +| -------------- | ------------------------------------------------- | +| **Providers** |  | +| **Combos** |  | +| **Analytics** |  | +| **Health** |  | +| **Translator** |  | +| **Settings** |  | +| **CLI Tools** |  | +| **Usage Logs** |  | +| **Endpoints** |  | + +|
-
+
OpenClaw @@ -92,113 +162,52 @@ _Yhdistä mikä tahansa tekoälyllä toimiva IDE- tai CLI-työkalu OmniRouten ka |
http://localhost:20128/v1 tai http://cloud.omniroute_EN_2NI4/v_1_TO_OM. konfiguraatio, rajattomat mallit ja kiintiö
+📡 All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 — one config, unlimited models and quota
---
-### 🆕 What's New in v3.0.0
+## 🤔 Why OmniRoute?
-| Area | Change |
-| ------------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal ` Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `
-
-
-
----
-
-## 📸
-
-
-
-
-
----
-
-## 🤔 Miksi OmniRoute?
-
-**Lopeta rahan tuhlaaminen ja rajojen ylittäminen:**
-
-- ...
- -| # | # | -| ----- | ---------------------------------------- | -| **1** |  | -| **2** |  | -| **3** |  | -| **4** |  | -| **5** |  | -| **6** |  | -| **7** |  | -| **8** |  | -| **9** |  | - - Tilauskiintiö vanhenee käyttämättä joka kuukausi
-- Korjausrajoitukset estävät sinua kesken koodaamisen
-- kalliita sovellusliittymiä (20-50 $/kk per tarjoaja)
-- Manuaalinen vaihtaminen palveluntarjoajien välillä
-
-**OmniRoute ratkaisee tämän:**
-
-- ✅ **Maksimoi tilaukset** - Seuraa kiintiötä, käytä jokainen bitti ennen nollausta
-- ✅ **Automaattinen palautus** - Tilaus → API-avain → Halpa → Ilmainen, nolla seisonta-aikaa
-- ✅ **Moni tili** - Pyöreä haku tilien välillä per palveluntarjoaja
-- ✅ **Universaali** - Toimii Claude Coden, Codexin, Gemini CLI:n, Cursorin, Clinen, OpenClawin ja minkä tahansa CLI-työkalun kanssa
-
----
-
-## 📧 Tuki
-
-> 💬 **Liity yhteisöömme!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Hanki apua, jaa vinkkejä ja pysy ajan tasalla.
-
-- **Verkkosivusto**: [omniroute.online](https://omniroute.online)
+- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Ongelmia**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Alkuperäinen projekti**: [9router by decolua](https://github.com/decolua/9router)
+- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 Näin se toimii
+## 🔄 How It Works
```
┌─────────────┐
@@ -227,452 +236,453 @@ Result: Never stop coding, minimal cost
---
-## 🎯 Mitä OmniRoute ratkaisee – 30 todellista kipukohtaa ja käyttötapausta
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **Jokainen tekoälytyökaluja käyttävä kehittäjä kohtaa nämä ongelmat päivittäin.** OmniRoute luotiin ratkaisemaan ne kaikki – kustannusten ylityksistä alueellisiin lohkoihin, rikkinäisistä OAuth-virroista protokollatoimintoihin ja yrityksen havainnointikykyyn.
+> **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.
-
💸 1. "Maksan kalliista tilauksesta, mutta silti rajoitukset häiritsevät minua"
+💸 1. "I pay for an expensive subscription but still get interrupted by limits"
-Kehittäjät maksavat 20–200 dollaria kuukaudessa Claude Prosta, Codex Prosta tai GitHub Copilotista. Maksamallakin kiintiöllä on katto – 5 tuntia käyttöä, viikkorajat tai minuuttirajoitukset. Koodausistunnon puolivälissä palveluntarjoaja lakkaa vastaamasta ja kehittäjä menettää virtauksen ja tuottavuuden. +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. -**Kuinka OmniRoute ratkaisee sen:** +**How OmniRoute solves it:** -- **Smart 4-Tier Fallback** — Jos tilauskiintiö loppuu, ohjataan automaattisesti kohtaan API-avain → Halpa → Ilmainen ilman manuaalista toimenpiteitä -- **Reaaliaikainen kiintiöseuranta** - Näyttää tunnuksen kulutuksen reaaliajassa ja nollaa lähtölaskenta (5 tuntia, päivittäin, viikoittain) -- **Useiden tilien tuki** — Useita tilejä palveluntarjoajaa kohden automaattisella kierrätyksellä — kun yksi loppuu, vaihtuu seuraavaan -- **Muokatut yhdistelmät** — Muokattavat varaketjut, joissa on 6 tasapainotusstrategiaa (täytä ensin, round-robin, P2C, satunnainen, vähiten käytetty, kustannusoptimoitu) -- **Codex Business Quotat** — Yritysten/Tiimien työtilan kiintiöiden valvonta suoraan kojelaudassa +- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention +- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly) +- **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 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
-`-lohkot malleista, kuten DeepSeek R1, standardoituun `reasoning_content`:hen
-- **Strukturoitu lähtö Geminille** — `json_schema` → `responseMimeType`/`responseSchema` automaattinen muunnos
-- **`stream`:n oletusarvo on `false`** — yhdenmukaistuu OpenAI-spesifikaation kanssa välttäen odottamattoman SSE:n Python/Rust/Go SDK:issa
+- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 67+ 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
🔌 2. "Minun täytyy käyttää useita palveluntarjoajia, mutta jokaisella on erilainen API"
+🔌 2. "I need to use multiple providers but each has a different API"
-OpenAI käyttää yhtä muotoa, Claude (Anthropic) käyttää toista, Gemini vielä toista. Jos kehittäjä haluaa testata eri palveluntarjoajien malleja tai vaihtoehtoja niiden välillä, hänen on määritettävä SDK:t uudelleen, muutettava päätepisteitä ja käsiteltävä yhteensopimattomia muotoja. Mukautetuilla palveluntarjoajilla (FriendLI, NIM) on mallista poikkeavat päätepisteet. +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. -**Kuinka OmniRoute ratkaisee sen:** +**How OmniRoute solves it:** -- **Yhdistetty päätepiste** — Yksi `http://localhost:20128/v1` toimii välityspalvelimena kaikille yli 36 palveluntarjoajalle -- **Format Translation** - Automaattinen ja läpinäkyvä: OpenAI ↔ Claude ↔ Gemini ↔ Responses API -- **Response Sanitization** – Poistaa standardista poikkeavat kentät (`x_groq`, `usage_breakdown`, `service_tier`), jotka rikkovat OpenAI SDK v1.83+:n -- **Roolin normalisointi** — Muuntaa `developer` → `system` muille kuin OpenAI-palveluntarjoajille; `system` → `user` GLM/ERNIE:lle -- **Think Tag Extraction** - Purkaa `
-
🌐 3. "Tekoälypalveluntarjoajani estää alueeni/maani"
+🌐 3. "My AI provider blocks my region/country"
-Palveluntarjoajat, kuten OpenAI/Codex, estävät pääsyn tietyiltä maantieteellisiltä alueilta. Käyttäjät saavat virheitä, kuten `unsupported_country_region_territory`, OAuth- ja API-yhteyksien aikana. Tämä on erityisen turhauttavaa kehitysmaiden kehittäjille. +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. -**Kuinka OmniRoute ratkaisee sen:** +**How OmniRoute solves it:** -- **3-tason välityspalvelimen määritys** – Muokattava välityspalvelin kolmella tasolla: yleinen (kaikki liikenne), palveluntarjoajakohtainen (vain yksi palveluntarjoaja) ja yhteys/avain -- **Värikoodatut välityspalvelinmerkit** — Visuaaliset ilmaisimet: 🟢 maailmanlaajuinen välityspalvelin, 🟡 tarjoajan välityspalvelin, 🔵 yhteysvälityspalvelin, joka näyttää aina IP-osoitteen -- **OAuth-tunnusten vaihto välityspalvelimen kautta** — OAuth-kulku kulkee myös välityspalvelimen kautta, mikä ratkaisee `unsupported_country_region_territory` -- **Yhteystestit välityspalvelimen kautta** - Yhteystestit käyttävät määritettyä välityspalvelinta (ei enää suoraa ohitusta) -- **SOCKS5-tuki** — Täysi SOCKS5-välityspalvelintuki lähtevään reititykseen -- **TLS-sormenjälkien huijaus** — Selaimen kaltainen TLS-sormenjälki `wreq-js`:n kautta ohittaakseen bot-tunnistuksen +- **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
-` prefix
-- **Vain ilmaiset yhdistelmät** — Ketju `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = 0 $/kk ilman seisonta-aikaa
-- **NVIDIA NIM Free Credits** - 1000 ilmaista saldoa integroituna
-- **Kustannusoptimoitu strategia** — Reititysstrategia, joka valitsee automaattisesti halvimman saatavilla olevan palveluntarjoajan
+- **Free-Only Combos** — Chain `gc/gemini-3-flash → 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
🆓 4. "Haluan käyttää tekoälyä koodaukseen, mutta minulla ei ole rahaa"
+🆓 4. "I want to use AI for coding but I have no money"
-Kaikki eivät voi maksaa 20–200 dollaria kuukaudessa tekoälytilauksista. Opiskelijat, kehittäjät nousevista maista, harrastajat ja freelancerit tarvitsevat pääsyn laadukkaisiin malleihin ilman kustannuksia. +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. -**Kuinka OmniRoute ratkaisee sen:** +**How OmniRoute solves it:** -- **Free Tier Providers -sisäänrakennettu** - Natiivituki 100 % ilmaisille palveluntarjoajille: iFlow (8 rajatonta mallia), Qwen (3 rajoittamatonta mallia), Kiro (Claude ilmaiseksi), Gemini CLI (180 000/kk ilmaiseksi) +- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free) - **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/
-
🔒 5. "Minun täytyy suojata tekoälyyhdyskäytävääni luvattomalta käytöltä"
+🔒 5. "I need to protect my AI gateway from unauthorized access"
-Kun paljastat tekoälyyhdyskäytävän verkkoon (LAN, VPS, Docker), kuka tahansa osoitteen tietävä voi kuluttaa kehittäjän tunnukset/kiintiöt. Ilman suojaa API:t ovat alttiita väärinkäytölle, nopealle injektiolle ja väärinkäytöksille. +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. -**Kuinka OmniRoute ratkaisee sen:** +**How OmniRoute solves it:** -- **API-avainten hallinta** — Luominen, kierto ja laajuus palveluntarjoajakohtaisesti erillisellä `/dashboard/api-manager`-sivulla -- **Mallitason käyttöoikeudet** - Rajoita API-avaimet tiettyihin malleihin (`openai/*`, jokerimerkkimallit) Salli kaikki/Rajoita-kytkimellä -- **API Endpoint Protection** — Vaadi avainta `/v1/models`:lle ja estä tietyt palveluntarjoajat luettelosta -- **Auth Guard + CSRF-suojaus** — Kaikki kojelaudan reitit on suojattu `withAuth`-väliohjelmistolla + CSRF-tunnuksilla -- **Rate Limiter** — IP-nopeuden rajoitus konfiguroitavilla ikkunoilla -- **IP-suodatus** — Pääsynhallinnan sallittu-/estolista -- **Prompt Injection Guard** — Desinfiointi haitallisia kehotusmalleja vastaan -- **AES-256-GCM Encryption** — Tunnistetiedot on salattu lepotilassa +- **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. "palveluntarjoajani kaatui ja menetin koodauskulkuni"
+🛑 6. "My provider went down and I lost my coding flow"
-Tekoälypalveluntarjoajat voivat muuttua epävakaiksi, palauttaa 5xx-virheitä tai saavuttaa väliaikaiset nopeusrajoitukset. Jos kehittäjä on riippuvainen yhdestä palveluntarjoajasta, se keskeytyy. Ilman katkaisijoita toistuvat uudelleenyritykset voivat kaataa sovelluksen. +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. -**Kuinka OmniRoute ratkaisee sen:** +**How OmniRoute solves it:** -- **Katkaisija palveluntarjoajakohtaisesti** - Automaattinen avautuminen/sulkeminen konfiguroitavilla kynnyksillä ja jäähdytys (suljettu/auki/puoliauki) -- **Eksponentiaalinen peruutus** — Progressiiviset uudelleenyritysviiveet -- **Anti-Thundering Herd** — Mutex + semaforisuoja samanaikaisia myrskyjä vastaan -- **Yhdistelmävaraketjut** – Jos ensisijainen toimittaja epäonnistuu, putoaa automaattisesti ketjun läpi ilman väliintuloa -- **Combo Circuit Breaker** — Poistaa automaattisesti käytöstä vialliset palveluntarjoajat yhdistelmäketjussa - | 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format | -- **Health Dashboard** — käytettävyyden valvonta, katkaisijoiden tilat, lukitukset, välimuistitilastot, p50/p95/p99-viive +- **Circuit Breaker per-model** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks +- **Exponential Backoff** — Progressive retry delays +- **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 +- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain +- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
-
🔧 7. "Jokaisen tekoälytyökalun määrittäminen on työlästä ja toistuvaa"
+🔧 7. "Configuring each AI tool is tedious and repetitive"
-Kehittäjät käyttävät kursoria, Claude Codea, Codex CLI:tä, OpenClaw:ta, Gemini CLI:tä, Kilo Codea... Jokainen työkalu tarvitsee eri konfiguraation (API-päätepiste, avain, malli). Uudelleenmääritys toimittajaa tai mallia vaihdettaessa on ajanhukkaa. +Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time. -**Kuinka OmniRoute ratkaisee sen:** +**How OmniRoute solves it:** -- **CLI Tools Dashboard** - Erillinen sivu yhdellä napsautuksella Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline -- **GitHub Copilot Config Generator** — Luo `chatLanguageModels.json` VS-koodille joukkomallin valinnalla -- **Ohjattu käyttöönottotoiminto** — Ohjattu 4-vaiheinen asennus ensikertalaisille -- **Yksi päätepiste, kaikki mallit** — Määritä `http://localhost:20128/v1` kerran, käytä 36+ palveluntarjoajaa +- **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 67+ providers
-
🔑 8. "Useiden palveluntarjoajien OAuth-tunnusten hallinta on helvettiä"
+🔑 8. "Managing OAuth tokens from multiple providers is hell"
-Claude Code, Codex, Gemini CLI, Copilot – kaikki käyttävät OAuth 2.0:aa vanhentuvilla tunnuksilla. Kehittäjien on todennettava jatkuvasti uudelleen, käsiteltävä `client_secret is missing`-, `redirect_uri_mismatch`- ja etäpalvelimien vikoja. OAuth LAN/VPS:ssä on erityisen ongelmallinen. +Claude Code, Codex, Gemini CLI, 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. -**Kuinka OmniRoute ratkaisee sen:** +**How OmniRoute solves it:** -- **Automaattinen tunnuksen päivitys** - OAuth-tunnukset päivittyvät taustalla ennen vanhenemista -- **Sisäänrakennettu OAuth 2.0 (PKCE)** - Automaattinen kulku Claude Codelle, Codexille, Gemini CLI:lle, Copilotille, Kirolle, Qwenille, iFlowille -- **Multi-Account OAuth** - Useita tilejä palveluntarjoajaa kohden JWT/ID-tunnuksen purkamisen kautta -- **OAuth LAN/Remote Fix** — Yksityinen IP-tunnistus `redirect_uri`:lle + manuaalinen URL-tila etäpalvelimille -- **OAuth Nginxin takana** - Käyttää `window.location.origin`-protokollaa käänteisen välityspalvelimen yhteensopivuuteen -- **OAuth-etäopas** — Vaiheittainen opas Google Cloud -kirjautumistiedoille VPS/Dockerissa +- **Auto Token Refresh** — OAuth tokens refresh in background before expiration +- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow +- **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. "En tiedä kuinka paljon kulutan tai minne"
+📊 9. "I don't know how much I'm spending or where"
-Kehittäjät käyttävät useita maksullisia palveluntarjoajia, mutta heillä ei ole yhtenäistä näkemystä kuluttamisesta. Jokaisella palveluntarjoajalla on oma laskutuksen hallintapaneeli, mutta yhdistettyä näkymää ei ole. Odottamattomat kustannukset voivat kasaantua. +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. -**Kuinka OmniRoute ratkaisee sen:** +**How OmniRoute solves it:** -- **Cost Analytics Dashboard** – Token-kohtainen kustannusseuranta ja budjetin hallinta palveluntarjoajakohtaisesti -- **Tasokohtaiset budjettirajat** – Tasokohtainen kulutuskatto, joka laukaisee automaattisen varauksen -- **Malleittainen hinnoittelu** — Muokattavat hinnat mallikohtaisesti -- **Käyttötilastot API-avainta kohti** — Pyyntömäärä ja viimeksi käytetty aikaleima avainta kohti -- **Analytics Dashboard** - Tilastokortit, mallin käyttökaavio, toimittajataulukko onnistumisprosenteilla ja viiveellä +- **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. "En pysty diagnosoimaan tekoälypuhelujen virheitä ja ongelmia"
+🐛 10. "I can't diagnose errors and problems in AI calls"
-Kun puhelu epäonnistuu, kehittäjä ei tiedä, oliko kyseessä nopeusrajoitus, vanhentunut tunnus, väärä muoto vai palveluntarjoajan virhe. Sirpaloituneet lokit eri terminaaleissa. Ilman havaittavuutta virheenkorjaus on yrityksen ja erehdysten menetelmää. +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. -**Kuinka OmniRoute ratkaisee sen:** +**How OmniRoute solves it:** -- **Yhdistettyjen lokien hallintapaneeli** - 4 välilehteä: pyyntölokit, välityspalvelimen lokit, tarkastuslokit, konsoli -- **Console Log Viewer** - Reaaliaikainen päätetyylinen katseluohjelma värikoodatuilla tasoilla, automaattinen vieritys, haku, suodatin -- **SQLite-välityspalvelimen lokit** — Pysyvät lokit, jotka kestävät palvelimen uudelleenkäynnistyksen -- **Kääntäjän leikkikenttä** — 4 virheenkorjaustilaa: Playground (muodon käännös), Chat Tester (meno-paluu), testipenkki (erä), Live Monitor (reaaliaikainen) -- **Pyyntötelemetria** — p50/p95/p99-latenssi + X-Request-Id-seuranta -- **Tiedostopohjainen kirjaaminen rotaatiolla** – Konsolin sieppaaja tallentaa kaiken JSON-lokiin kokoperusteisella kierrolla +- **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 Proxy Logs** — Persistent logs that survive server restarts +- **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 Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation +- **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. "Yhdyskäytävän käyttöönotto ja ylläpito on monimutkaista"
+🏗️ 11. "Deploying and maintaining the gateway is complex"
-AI-välityspalvelimen asentaminen, määrittäminen ja ylläpito eri ympäristöissä (paikallinen, VPS, Docker, pilvi) on työvoimavaltaista. Ongelmat, kuten kovakoodatut polut, `EACCES` hakemistoissa, porttiristiriidat ja monikäyttöjärjestelmät lisäävät kitkaa. +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. -**Kuinka OmniRoute ratkaisee sen:** +**How OmniRoute solves it:** -- **npm yleinen asennus** — `npm install -g omniroute && omniroute` — valmis -- **Docker Multi-Platform** - AMD64 + ARM64 natiivi (Apple Silicon, AWS Graviton, Raspberry Pi) -- **Docker Compose -profiilit** — `base` (ei CLI-työkaluja) ja `cli` (Claude Code, Codex, OpenClaw) -- **Electron Desktop App** - Natiivisovellus Windowsille/macOS:lle/Linuxille, jossa ilmaisinalue, automaattinen käynnistys, offline-tila -- **Split-Port Mode** — API ja Dashboard erillisissä porteissa edistyneille skenaarioille (käänteinen välityspalvelin, konttiverkko) -- **Cloud Sync** - Määritä synkronointi laitteiden välillä Cloudflare Workersin kautta -- **DB-varmuuskopiot** — Kaikkien asetusten automaattinen varmuuskopiointi, palautus, vienti ja tuonti +- **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
-
🌍 12. "Käyttöliittymä on vain englanninkielinen ja tiimini ei puhu englantia"
+🌍 12. "The interface is English-only and my team doesn't speak English"
-Ryhmät muissa kuin englanninkielisissä maissa, erityisesti Latinalaisessa Amerikassa, Aasiassa ja Euroopassa, kamppailevat vain englanninkielisten käyttöliittymien kanssa. Kielimuurit vähentävät käyttöönottoa ja lisäävät konfigurointivirheitä. +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. -**Kuinka OmniRoute ratkaisee sen:** +**How OmniRoute solves it:** -- **Dashboard i18n — 30 kieltä** — Kaikki yli 500 näppäintä käännetty mukaan lukien arabia, bulgaria, tanska, saksa, espanja, suomi, ranska, heprea, hindi, unkari, indonesia, italia, japani, korea, malaiji, hollanti, norja, puola, portugali (PT/BR), romania, thai, venäjä, ukraina, slovakki, ruotsi, englanti -- **RTL-tuki** — Tuki oikealta vasemmalle arabian ja heprean kielelle -- **Multi-Language READMEs** - 30 täydellistä dokumentaation käännöstä -- **Kielen valitsin** — Maapallokuvake otsikossa reaaliaikaista vaihtoa varten +- **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. "Tarvitsen muutakin kuin chatin – tarvitsen upotuksia, kuvia, ääntä"
+🔄 13. "I need more than chat — I need embeddings, images, audio"
-Tekoäly ei ole vain chatin loppuun saattamista. Kehittäjien on luotava kuvia, litteroitava ääni, luotava upotuksia RAG:lle, järjestettävä asiakirjat uudelleen ja valvottava sisältöä. Jokaisella API:lla on eri päätepiste ja muoto. +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. -**Kuinka OmniRoute ratkaisee sen:** +**How OmniRoute solves it:** -- **Upotukset** — `/v1/embeddings`, 6 toimittajaa ja 9+ mallia -- **Image Generation** — `/v1/images/generations` 10 palveluntarjoajan ja 20+ mallin kanssa (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI) -- **Tekstistä videoksi** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) ja SD WebUI -- **Tekstistä musiikiksi** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen) -- **Äänitranskriptio** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3 -- **Tekstistä puheeksi** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, Inworld, Cartesia, PlayHT ja olemassa olevat palveluntarjoajat -- **Moderaatiot** — `/v1/moderations` — Sisällön turvallisuustarkastukset -- **Uudelleensijoitus** — `/v1/rerank` — Asiakirjan relevanssin uudelleensijoitus -- **Responses API** — Täysi `/v1/responses`-tuki Codexille +- **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. "Minulla ei ole mahdollisuutta testata ja vertailla laatua eri mallien välillä"
+🧪 14. "I have no way to test and compare quality across models"
-Kehittäjät haluavat tietää, mikä malli sopii parhaiten heidän käyttötapaukseensa – koodi, käännös, päättely – mutta manuaalinen vertailu on hidasta. Integroituja arviointityökaluja ei ole olemassa. +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. -**Kuinka OmniRoute ratkaisee sen:** +**How OmniRoute solves it:** -- **LLM-arvioinnit** — Golden set -testaus 10 esiladatulla kotelolla, jotka kattavat tervehdyksen, matematiikan, maantieteen, koodin luomisen, JSON-yhteensopivuuden, käännöksen, merkinnän, turvallisuuden kieltämisen -- **4 sovitusstrategiaa** — `exact`, `contains`, `regex`, `custom` (JS-toiminto) -- **Translator Playground Test Bench** - Erätestaus useilla tuloilla ja odotetulla lähdöllä, tarjoajien välinen vertailu -- **Chat Tester** - Täysi edestakainen matka visuaalisen vasteen renderöinnillä -- **Live Monitor** — Reaaliaikainen tietovirta kaikista välityspalvelimen kautta kulkevista pyynnöistä +- **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. "Minun täytyy skaalata suorituskykyä menettämättä"
+📈 15. "I need to scale without losing performance"
-Pyynnön määrän kasvaessa samat kysymykset aiheuttavat päällekkäisiä kustannuksia välimuistiin tallentamatta. Ilman idempotenssia kaksoiskappaleet pyytävät jätteenkäsittelyä. Palveluntarjoajakohtaisia hintarajoja on noudatettava. +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. -**Kuinka OmniRoute ratkaisee sen:** +**How OmniRoute solves it:** -- **Semanttinen välimuisti** – Kaksitasoinen välimuisti (allekirjoitus + semanttinen) vähentää kustannuksia ja viivettä -- **Request Idempotency** — 5 sekunnin deduplikaatioikkuna identtisille pyynnöille -- **nopeusrajoituksen tunnistus** – palveluntarjoajakohtainen RPM, pienin väli ja suurin samanaikainen seuranta -- **Muokattavat nopeusrajoitukset** - Määritettävissä olevat oletusasetukset kohdassa Asetukset → Resilience with persistence -- **API Key Validation Cache** – 3-tasoinen välimuisti tuotannon suorituskykyä varten -- **Health Dashboard telemetrialla** - p50/p95/p99 latenssi, välimuistitilastot, käyttöaika +- **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 +- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence +- **API Key Validation Cache** — 3-tier cache for production performance +- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
-
🤖 16. "Haluan hallita mallin käyttäytymistä maailmanlaajuisesti"
+🤖 16. "I want to control model behavior globally"
-Kehittäjät, jotka haluavat kaikki vastaukset tietyllä kielellä, tietyllä sävyllä tai haluavat rajoittaa perusteluita. Tämän määrittäminen jokaiseen työkaluun/pyyntöön on epäkäytännöllistä. +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. -**Kuinka OmniRoute ratkaisee sen:** +**How OmniRoute solves it:** -- **Järjestelmäkehotteen lisäys** — Yleinen kehote koskee kaikkia pyyntöjä -- **Thinking Budget Validation** – perustelutunnisteen allokoinnin ohjaus pyyntöä kohti (läpivienti, automaattinen, mukautettu, mukautuva) -- **6 reititysstrategiaa** — Globaalit strategiat, jotka määrittävät pyyntöjen jakautumisen -- **Wildcard Router** — `provider/*`-mallit reitittävät dynaamisesti mille tahansa palveluntarjoajalle -- **Yhdistelmä käyttöön/pois käytöstä** - Vaihda yhdistelmät suoraan kojelaudalta -- **Provider Toggle** — Ota käyttöön tai poista käytöstä kaikki palveluntarjoajan yhteydet yhdellä napsautuksella -- **Estetyt palveluntarjoajat** - Sulje tietyt palveluntarjoajat pois `/v1/models`-luettelosta +- **System Prompt Injection** — Global prompt applied to all requests +- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive) +- **6 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 +- **Provider Toggle** — Enable/disable all connections for a provider with one click +- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
-
🧰 17. "Tarvitsen MCP-työkaluja ensiluokkaisina tuoteominaisuuksina"
+🧰 17. "I need MCP tools as first-class product capabilities"
-Monet tekoälyyhdyskäytävät paljastavat MCP:n vain piilotettuna toteutustietona. Tiimit tarvitsevat näkyvän, hallittavan toimintakerroksen. +Many AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer. -**Kuinka OmniRoute ratkaisee sen:** +**How OmniRoute solves it:** -- MCP näkyy kojelaudan navigointi- ja päätepisteprotokolla-välilehdessä -- Erillinen MCP-hallintasivu, jossa on prosessit, työkalut, laajuudet ja tarkastus -- Sisäänrakennettu pikakäynnistys `omniroute --mcp`:lle ja asiakkaan käyttöönottoon +- 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. "Tarvitsen A2A-orkesterin synkronointia ja suoratoiston tehtäväpolkuja"
+🧠 18. "I need A2A orchestration with sync + stream task paths"
-Agenttityönkulut tarvitsevat sekä suoria vastauksia että pitkäkestoista suoratoistoa elinkaariohjauksella. +Agent workflows need both direct replies and long-running streamed execution with lifecycle control. -**Kuinka OmniRoute ratkaisee sen:** +**How OmniRoute solves it:** -- A2A JSON-RPC -päätepiste (`POST /a2a`) `message/send`:n ja `message/stream`:n kanssa -- SSE-suoratoisto päätetilan etenemisellä -- Tehtävän elinkaaren sovellusliittymät `tasks/get`:lle ja `tasks/cancel`:lle +- 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. "Tarvitsen todellisen MCP-prosessin kunnon, en arvatun tilan"
+🛰️ 19. "I need real MCP process health, not guessed status"
-Operatiivisten tiimien on tiedettävä, onko MCP todella elossa, ei vain sitä, onko API tavoitettavissa. +Operational teams need to know if MCP is actually alive, not just whether an API is reachable. -**Kuinka OmniRoute ratkaisee sen:** +**How OmniRoute solves it:** -- Ajonaikainen syketiedosto, jossa on PID, aikaleimat, kuljetus, työkalujen määrä ja laajuustila -- MCP-tilan API, joka yhdistää sykkeen + viimeaikaisen toiminnan -- Käyttöliittymän tilakortit prosessin / käytettävyyden / sydämenlyöntien tuoreudelle +- 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. "Tarvitsen tarkastettavan MCP-työkalun suorituksen"
+📋 20. "I need auditable MCP tool execution"
-Kun työkalut muuttavat määrityksiä tai käynnistävät operaatioita, tiimit tarvitsevat rikosteknistä jäljitettävyyttä. +When tools mutate config or trigger ops actions, teams need forensic traceability. -**Kuinka OmniRoute ratkaisee sen:** +**How OmniRoute solves it:** -- SQLite-tuettu tarkastusloki MCP-työkalukutsuille -- Suodattimet työkalun, onnistumisen/epäonnistumisen, API-avaimen ja sivutuksen mukaan -- Kojelaudan tarkastustaulukko + tilastopäätepisteet automatisointia varten +- 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. "Tarvitsen laajennettuja MCP-oikeuksia integraatiota kohti"
+🔐 21. "I need scoped MCP permissions per integration"
-Eri asiakkailla tulisi olla vähiten käyttöoikeus työkaluluokkiin. +Different clients should have least-privilege access to tool categories. -**Kuinka OmniRoute ratkaisee sen:** +**How OmniRoute solves it:** -- 9 rakeista MCP-skooppia ohjattua työkalujen käyttöä varten -- Laajuuden valvonta ja näkyvyys MCP-hallintaliittymässä -- Turvallinen oletusasento käyttötyökaluille +- 9 granular MCP scopes for controlled tool access +- Scope enforcement and visibility in MCP management UI +- Safe default posture for operational tooling
-
⚙️ 22. "Tarvitsen toiminnan ohjaimia ilman uudelleenjärjestelyä"
+⚙️ 22. "I need operational controls without redeploying"
-Tiimit tarvitsevat nopeita ajonaikaisia muutoksia tapausten tai kustannustapahtumien aikana. +Teams need quick runtime changes during incidents or cost events. -**Kuinka OmniRoute ratkaisee sen:** +**How OmniRoute solves it:** -- Vaihda yhdistelmäaktivointia suoraan MCP-kojelaudalta -- Käytä joustavuusprofiileja ennalta määritetyistä käytäntöpaketeista -- Nollaa katkaisijan tila samasta käyttöpaneelista +- Switch combo activation directly from MCP dashboard +- Apply resilience profiles from pre-defined policy packs +- Reset circuit breaker state from the same operations panel
-
🔄 23. "Tarvitsen live-A2A-tehtävän elinkaaren näkyvyyden ja peruutuksen"
+🔄 23. "I need live A2A task lifecycle visibility and cancellation"
-Ilman elinkaaren näkyvyyttä tehtäväkohtauksista tulee vaikeasti luokiteltuja. +Without lifecycle visibility, task incidents become hard to triage. -**Kuinka OmniRoute ratkaisee sen:** +**How OmniRoute solves it:** -- Tehtäväluettelo / suodatus tilan / taitojen mukaan ja sivutus -- Tehtävän metatietojen, tapahtumien ja artefaktien yksityiskohdat -- Tehtävän peruutuksen päätepiste ja käyttöliittymätoiminto vahvistuksen kanssa +- 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. "Tarvitsen aktiivisia suoratoistotietoja A2A-kuormalle"
+🌊 24. "I need active stream metrics for A2A load"
-Streaming-työnkulut edellyttävät toiminnallista tietoa samanaikaisuudesta ja reaaliaikaisista yhteyksistä. +Streaming workflows require operational insight into concurrency and live connections. -**Kuinka OmniRoute ratkaisee sen:** +**How OmniRoute solves it:** -- Aktiiviset virtalaskurit integroitu A2A-tilaan -- Viimeisen tehtävän aikaleima ja tilakohtaiset määrät -- A2A kojelautakortit reaaliaikaiseen toimintojen seurantaan +- Active stream counters integrated into A2A status +- Last task timestamp and per-state counts +- A2A dashboard cards for real-time ops monitoring
-
🪪 25. "Tarvitsen asiakkaille vakioagentin haun"
+🪪 25. "I need standard agent discovery for clients"
-Ulkoiset asiakkaat ja orkesterit tarvitsevat koneellisesti luettavaa metadataa käyttöönottoa varten. +External clients and orchestrators need machine-readable metadata for onboarding. -**Kuinka OmniRoute ratkaisee sen:** +**How OmniRoute solves it:** -- Agenttikortti esillä osoitteessa `/.well-known/agent.json` -- Johdon käyttöliittymässä näkyvät valmiudet ja taidot -- A2A status API sisältää etsintämetatiedot automatisointia varten +- Agent Card exposed at `/.well-known/agent.json` +- Capabilities and skills shown in management UI +- A2A status API includes discovery metadata for automation
-
🧭 26. "Tarvitsen protokollan löydettävyyden tuotteessa UX"
+🧭 26. "I need protocol discoverability in the product UX"
-Jos käyttäjät eivät löydä protokollapintoja, käyttöönoton ja tuen laatu heikkenee. +If users cannot discover protocol surfaces, adoption and support quality drop. -**Kuinka OmniRoute ratkaisee sen:** +**How OmniRoute solves it:** -- Sivupalkkimerkinnät MCP:lle ja A2A:lle -- Päätepistesivu Protokollat-välilehti, jossa on pika-aloitus ja tila -- Linkit yleiskatsauksesta erityisiin hallintapaneeliin +- 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. "Tarvitsen päästä päähän -protokollan validoinnin oikeiden asiakkaiden kanssa"
+🧪 27. "I need end-to-end protocol validation with real clients"
-Valetestit eivät riitä vahvistamaan protokollan yhteensopivuutta ennen julkaisua. +Mock tests are not enough to validate protocol compatibility before release. -**Kuinka OmniRoute ratkaisee sen:** +**How OmniRoute solves it:** -- E2E-paketti, joka käynnistää sovelluksen ja käyttää todellista MCP SDK -asiakassiirtoa -- A2A-asiakas testaa virtojen löytämistä, lähettämistä, suoratoistoa, vastaanottamista ja peruuttamista -- Tarkista väitteet MCP-tarkastuksen ja A2A-tehtävien sovellusliittymien kanssa +- 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. "Tarvitsen yhtenäisen havainnoinnin kaikissa liitännöissä"
+📡 28. "I need unified observability across all interfaces"
-Havainnon jakaminen protokollan mukaan luo kuolleita kulmia ja pidemmän MTTR:n. +Splitting observability by protocol creates blind spots and longer MTTR. -**Kuinka OmniRoute ratkaisee sen:** +**How OmniRoute solves it:** -- Yhdistetyt kojelaudat/lokit/analytiikka yhdessä tuotteessa -- Terveys + auditointi + pyyntö telemetria OpenAI-, MCP- ja A2A-tasoilla -- Toiminnalliset sovellusliittymät tilaa ja automaatiota varten +- Unified dashboards/logs/analytics in one product +- Health + audit + request telemetry across OpenAI, MCP, and A2A layers +- Operational APIs for status and automation
-
💼 29. "Tarvitsen yhden suoritusajan välityspalvelimelle + työkaluille + agentin orkestraatiolle"
+💼 29. "I need one runtime for proxy + tools + agent orchestration"
-Useiden erillisten palvelujen suorittaminen lisää käyttökustannuksia ja vikatiloja. +Running many separate services increases operational cost and failure modes. -**Kuinka OmniRoute ratkaisee sen:** +**How OmniRoute solves it:** -- OpenAI-yhteensopiva välityspalvelin, MCP-palvelin ja A2A-palvelin yhdessä pinossa -- Jaettu todennus, joustavuus, tietovarasto ja havaittavuus -- Yhdenmukainen toimintamalli kaikilla vuorovaikutuspinnoilla +- 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
-
-### Esimerkkiohjekirjat (integroidut käyttötapaukset)
+### Example Playbooks (Integrated Use Cases)
-**Ohjekirja A: maksimoi maksullinen tilaus + halpa varmuuskopio**
+**Playbook A: Maximize paid subscription + cheap backup**
```txt
Combo: "maximize-claude"
@@ -684,7 +694,7 @@ Monthly cost: $20 + small backup spend
Outcome: higher quality, near-zero interruption
```
-**Ohjekirja B: Nollahintainen koodauspino**
+**Playbook B: Zero-cost coding stack**
```txt
Combo: "free-forever"
@@ -696,7 +706,7 @@ Monthly cost: $0
Outcome: stable free coding workflow
```
-**Playbook C: 24/7 aina päällä oleva varaketju**
+**Playbook C: 24/7 always-on fallback chain**
```txt
Combo: "always-on"
@@ -709,65 +719,132 @@ Combo: "always-on"
Outcome: deep fallback depth for deadline-critical workloads
```
-**Pelikirja D: Agentti toimii MCP:llä + A2A**
+**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/mcp and /dashboard/a2a
-4) Control incidents with resilience profile + task cancellation
+3) Observe via /dashboard/endpoint (MCP and A2A tabs)
+4) Toggle services via inline status controls
```
---
-## ⚡ Pika-aloitus
+## 🆓 Start Free — Zero Configuration Cost
-**1. Asenna maailmanlaajuisesti:**
+> 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 **iFlow** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |
+| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |
+| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |
+| 5 | `/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).
+
+## Pikakäynnistys
+
+### 1) Install and run
```bash
npm install -g omniroute
omniroute
```
-🎉 Hallintapaneeli avautuu klo `http://localhost:20128`
+> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:
+>
+> ```bash
+> pnpm install -g omniroute
+> pnpm approve-builds -g # Select all packages → approve
+> omniroute
+> ```
-| Komento | Kuvaus |
-| ----------------------- | --------------------------------------- |
-| `omniroute` | Käynnistä palvelin (oletusportti 20128) |
-| `omniroute --port 3000` | Käytä mukautettua porttia |
-| `omniroute --no-open` | Älä avaa selainta automaattisesti |
-| `omniroute --help` | Näytä ohje |
+Dashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.
-**2. Yhdistä ILMAINEN palveluntarjoaja:**
+| 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 |
-Kojelauta → Palveluntarjoajat → Yhdistä **Claude Code** tai **Antigravity** → OAuth-kirjautuminen → Valmis!
+Optional split-port mode:
-**3. Käytä CLI-työkalussasi:**
-
-```
-Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Settings:
- Endpoint: http://localhost:20128/v1
- API Key: [copy from dashboard]
- Model: if/kimi-k2-thinking
+```bash
+PORT=20128 DASHBOARD_PORT=20129 omniroute
+# API: http://localhost:20128/v1
+# Dashboard: http://localhost:20129
```
-**Siinä se!** Aloita koodaus ILMAISTEN AI-malleilla.
+### 2) Connect providers and create your API key
-**Vaihtoehto – suorita lähteestä:**
+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
+
+```txt
+Base URL: http://localhost:20128/v1
+API Key: [copy from Endpoint page]
+Model: if/kimi-k2-thinking (or any provider/model prefix)
+```
+
+Works with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.
+
+### 4) Enable and validate protocols (v2.0)
+
+**MCP (for tool-driven operations):**
+
+```bash
+omniroute --mcp
+```
+
+Then connect your MCP client over `stdio` and test tools like:
+
+- `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 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
+PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev
```
---
## 🐳 Docker
-OmniRoute on saatavilla julkisena Docker-kuvana osoitteessa [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
+OmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
-**Pikaajo:**
+**Quick run:**
```bash
docker run -d \
@@ -778,7 +855,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Ympäristötiedostolla:**
+**With environment file:**
```bash
# Copy and edit .env first
@@ -793,7 +870,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Docker Composen käyttäminen:**
+**Using Docker Compose:**
```bash
# Base profile (no CLI tools)
@@ -803,255 +880,550 @@ docker compose --profile base up -d
docker compose --profile cli up -d
```
-| Kuva | Tag | Koko | Kuvaus |
-| ------------------------ | -------- | ------- | -------------------- |
-| `diegosouzapw/omniroute` | `latest` | ~250 Mt | Uusin vakaa julkaisu |
-| `diegosouzapw/omniroute` | `1.0.3` | ~250 Mt | Nykyinen versio |
+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.
+- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.
+- 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` | `1.0.3` | ~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
+### Pikakäynnistys
+
```bash
-npm run electron:dev # Development mode
+# 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)
+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)
---
-## 💰 Hinnoittelu yhdellä silmäyksellä
+## 💰 Pricing at a Glance
-| Taso | Palveluntarjoaja | Kustannukset | Kiintiön nollaus | Paras |
-| ---------------- | ----------------- | ------------------------------ | ---------------------- | -------------------------- |
-| **💳 TILAUS** | Claude Code (Pro) | 20 dollaria/kk | 5h + viikoittain | jo tilattu |
-| | Codex (Plus/Pro) | 20-200 $/kk | 5h + viikoittain | OpenAI-käyttäjät |
-| | Gemini CLI | **ILMAINEN** | 180 tk/kk + 1 tk/päivä | Kaikki! |
-| | GitHub Copilot | 10-19 $/kk | Kuukausittain | GitHub-käyttäjät |
-| **🔑 API-AVAIN** | NVIDIA NIM | **ILMAINEN** (1000 krediittiä) | Kertaluonteinen | Ilmainen tasotestaus |
-| | DeepSeek | Maksu per käyttö | Ei yhtään | Paras hinta/laatu |
-| | Groq | Ilmainen taso + maksettu | Hinta rajoitettu | Erittäin nopea johtopäätös |
-| | xAI (Grok) | Maksu per käyttö | Ei yhtään | Grok mallit |
-| | Mistral | Ilmainen taso + maksettu | Hinta rajoitettu | Eurooppalainen tekoäly |
-| | OpenRouter | Maksu per käyttö | Ei yhtään | 100+ mallia |
-| **💰 EDULLISET** | GLM-4.7 | 0,6 $/1 milj. | Päivittäin klo 10 | Budjetin varmuuskopio |
-| | MiniMax M2.1 | 0,2 $/1 milj. | 5 tunnin rullaus | Halvin vaihtoehto |
-| | Kimi K2 | 9 dollaria/kk asunto | 10 milj. rahakkeita/kk | Ennustettavat kustannukset |
-| **🆓 ILMAINEN** | iFlow | 0 dollaria | Rajoittamaton | 8 mallia ilmaiseksi |
-| | Qwen | 0 dollaria | Rajoittamaton | 3 mallia ilmaiseksi |
-| | Kiro | 0 dollaria | Rajoittamaton | Claude ilmaiseksi |
+| 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 |
+| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |
+| | 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** | iFlow | **$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 |
-**💡 Pro-vinkki:** Aloita Gemini CLI:llä (180 000 ilmaista kuukaudessa) + iFlow (rajoittamaton ilmainen) -yhdistelmä = 0 dollarin hinta!
+> 🆕 **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
+iFlow (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.
---
-## 💡 Tärkeimmät ominaisuudet
+---
-### 🧠 Ydinreititys ja älykkyys
+## 🆓 Free Models — What You Actually Get
-| Ominaisuus | Mitä se tekee |
-| ------------------------------------- | --------------------------------------------------------------------------------------------- |
-| 🎯 **Smart 4-Tier Fallback** | Automaattinen reitti: Tilaus → API-avain → Halpa → Ilmainen |
-| 📊 **Reaaliaikainen kiintiöseuranta** | Live-tunnusten määrä + nollaa lähtölaskenta palveluntarjoajaa kohti |
-| 🔄 **Käännösmuoto** | OpenAI ↔ Claude ↔ Kaksoset ↔ Kursori ↔ Kiro saumaton + vastaus desinfiointi |
-| 👥 **Useiden tilien tuki** | Useita tilejä per palveluntarjoaja älykkäällä valinnalla |
-| 🔄 **Automaattinen Token Refresh** | OAuth-tunnukset päivittyvät automaattisesti yrittämällä uudelleen |
-| 🎨 **Muokatut yhdistelmät** | 6 strategiaa: fill-first, round-robin, p2c, satunnainen, vähiten käytetty, kustannusoptimoitu |
-| 🧩 **Räätälöidyt mallit** | Lisää mikä tahansa mallitunnus mille tahansa toimittajalle |
-| 🌐 **Wildcard-reititin** | Reititä `provider/*` mallit mille tahansa palveluntarjoajalle dynaamisesti |
-| 🧠 **Ajatteleva budjetti** | Läpivienti-, automaatti-, mukautetut ja mukautuvat tilat päättelymalleille |
-| 🔀 **Model Aliases** | Auto-forward deprecated model IDs to current replacements (built-in + custom) |
-| ⚡ **Background Degradation** | Auto-route background tasks (titles, summaries) to cheaper models |
-| 💬 **Järjestelmän pikaruiskutus** | Maailmanlaajuinen järjestelmäkehote käytössä kaikissa pyynnöissä |
-| 📄 **Responses API** | Täysi OpenAI Responses API (`/v1/responses`) tuki Codexille |
+> 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.
-### 🎵 Multimodaaliset sovellusliittymät
+### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)
-| Ominaisuus | Mitä se tekee |
-| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 🖼️ **Kuvan luominen** | `/v1/images/generations` — 4 toimittajaa, 9+ mallia |
-| 📐 **Upotukset** | `/v1/embeddings` — 6 toimittajaa, 9+ mallia |
-| 🎤 **Äänitranskriptio** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |
-| 🔊 **Tekstistä puheeksi** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) |
-| 🛡️ **Moderaatiot** | `/v1/moderations` — Sisällön turvallisuustarkistukset |
-| 🔀 **Uudelleenjärjestys** | `/v1/rerank` — Asiakirjan osuvuuden uudelleensijoitus |
+| 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 |
-### 🛡️ Joustavuus ja turvallisuus
+### 🟢 IFLOW MODELS (Free OAuth — No Credit Card)
-| Ominaisuus | Mitä se tekee |
-| ----------------------------------------- | ------------------------------------------------------------------------------------------------ |
-| 🔌 **Katkaisija** | Automaattinen avaaminen/sulkeminen palveluntarjoajakohtaisesti konfiguroitavilla kynnysarvoilla |
-| 🛡️ **Ukkosen vastainen lauma** | Mutex + semaforin nopeusrajoitus API-avainten tarjoajille |
-| 🧠 **Semanttinen välimuisti** | Kaksitasoinen välimuisti (allekirjoitus + semanttinen) vähentää kustannuksia ja viivettä |
-| ⚡ **Pyydä idempotenssia** | 5s dedup-ikkuna päällekkäisille pyynnöille |
-| 🔒 **TLS-sormenjälkien huijaus** | Ohita TLS-pohjainen bot-tunnistus wreq-js:n avulla |
-| 🌐 **IP-suodatus** | API-käyttöoikeuksien hallinnan sallittu-/estoluettelo |
-| 📊 **Muokattavat hintarajat** | Konfiguroitava kierrosluku, minimiväli ja suurin samanaikainen järjestelmätasolla |
-| 💾 **Rate Limit Persistence** | Learned limits survive restarts via SQLite with 60s debounce + 24h staleness |
-| 🔄 **Token Refresh Resilience** | Per-provider circuit breaker (5 fails→30min) + 30s timeout per attempt |
-| 🛡 **API Endpoint Protection** | Todennusportin + tarjoajan esto `/models`-päätepisteelle |
-| 🔒 **Välityspalvelimen näkyvyys** | Värikoodatut merkit: 🟢 maailmanlaajuinen, 🟡 tarjoaja, 🔵 yhteyskohtainen IP-näytöllä |
-| 🌐 **3-tason välityspalvelimen määritys** | Määritä välityspalvelimet maailmanlaajuisesti, palveluntarjoajakohtaisesti tai yhteyskohtaisesti |
+| 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 |
-### 📊 Havaittavuus ja analytiikka
+### 🟡 QWEN MODELS (Device Code Auth)
-| Ominaisuus | Mitä se tekee |
-| ------------------------------------- | ----------------------------------------------------------------------------------------------------- |
-| 📝 **Pyydä kirjaamista** | Vianetsintätila täydellisillä pyyntö-/vastauslokeilla |
-| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |
-| 💾 **SQLite-välityspalvelimen lokit** | Pysyvät välityspalvelimen lokit selviävät palvelimen uudelleenkäynnistyksistä |
-| 📊 **Analytics Dashboard** | Recharts-powered: tilastokortit, mallin käyttökaavio, toimittajataulukko |
-| 📈 **Edistyksen seuranta** | Ota SSE:n edistymistapahtumat käyttöön suoratoistoa varten |
-| 🧪 **LLM-arvioinnit** | Kultaisen setin testaus 4 ottelustrategialla |
-| 🔍 **Pyydä telemetriaa** | p50/p95/p99 latenssiaggregointi + X-Request-Id-jäljitys |
-| 📋 **Lokien hallintapaneeli** | Yhdistetty 4-välilehden sivu: pyyntölokit, välityspalvelimen lokit, tarkastuslokit, konsoli |
-| 🖥️ **Console Log Viewer** | Reaaliaikainen pääte-tyylinen katseluohjelma tasosuodattimella, haulla, automaattisella vierityksellä |
-| 📑 **Tiedostopohjainen kirjaus** | Konsolin sieppaaja kaappaa kaiken lähdön JSON-lokitiedostoon pyörittämällä |
-| 🏥 **Terveyden hallintapaneeli** | Järjestelmän käytettävyys, katkaisijoiden tilat, lukitukset, välimuistitilastot |
-| 💰 **Kustannusseuranta** | Budjetin hallinta + mallikohtainen hinnoittelu |
+| 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) |
-### ☁️ Käyttöönotto ja synkronointi
+### 🟣 GEMINI CLI (Google OAuth)
-| Ominaisuus | Mitä se tekee |
-| ----------------------------------- | -------------------------------------------------------------------------------- |
-| 💾 **Cloud Sync** | Synkronoi asetukset laitteiden välillä Cloudflare Workersin kautta |
-| 🌐 **Ota käyttöön missä tahansa** | Localhost, VPS, Docker, Cloudflare Workers |
-| 🔑 **API-avainten hallinta** | Luo, kierrä ja laajenna API-avaimia tarjoajakohtaisesti |
-| 🧙 **Ohjattu käyttöönottotoiminto** | 4-vaiheinen ohjattu asennus ensikertalaisille |
-| 🔧 **CLI Tools Dashboard** | Määritä yhdellä napsautuksella Claude, Codex, Cline, OpenClaw, Kilo, Antigravity |
-| 🔄 **DB-varmuuskopiot** | Automaattinen varmuuskopiointi, palautus, vienti ja tuonti kaikille asetuksille |
-| 🌐 **Kansainvälistyminen** | Täysi i18n next-intl:llä — Englanti + portugali (Brasilia) tuki |
-| 🌍 **Kielenvalitsin** | Maapallokuvake otsikossa reaaliaikaista kielenvaihtoa varten (🇺🇸/🇧🇷) |
-| 🧹 **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 |
-| 📂 **Muokattu tietohakemisto** | `DATA_DIR` env var ohittaa oletusarvoisen `~/.omniroute`-tallennuspolun |
+| Model | Prefix | Limit | Rate Limit |
+| ------------------------ | ------ | --------------------------- | ------------- |
+| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |
+| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |
+
+### ⚫ 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
+> iFlow (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 v2.0 is built as an operational platform, not just a relay proxy.
+
+### 🆕 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 Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |
+| 🤖 **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 (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) |
+| 🤝 **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** | 9 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 combo, apply resilience profiles, reset breakers from one control surface |
+
+### 🧠 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** | 6 balancing strategies + fallback chain control |
+| 🌐 **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) |
+| 💬 **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 |
+| ----------------------------------- | -------------------------------------------------------------------------------------- |
+| 🔌 **Circuit Breakers** | Per-model trip/recover with threshold controls |
+| 🎯 **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 |
+| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |
+| 🔑 **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 |
+
+### 📊 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 |
+| 📋 **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 |
+
+### ☁️ Deployment & Platform
+
+| Feature | What It Does |
+| ----------------------------- | --------------------------------------------------------- |
+| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |
+| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |
+| 💾 **Cloud Sync** | Configuration sync via cloud worker |
+| 🔄 **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 |
+
+### Feature Deep Dive
+
+#### Smart fallback with practical cost control
+
+```txt
+Combo: "my-coding-stack"
+ 1. cc/claude-opus-4-6
+ 2. nvidia/llama-3.3-70b
+ 3. glm/glm-4.7
+ 4. if/kimi-k2-thinking
+```
+
+When quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.
+
+#### 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)
+
+#### 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)
🚀 30. "Minun on lähetettävä agenttityönkulkuja ilman liimakoodin leviämistä"
+🚀 30. "I need to ship agentic workflows without glue-code sprawl"
-Tiimit menettävät nopeutta yhdistäessään useita ad-hoc-palveluita ja skriptejä. +Teams lose velocity when stitching multiple ad-hoc services and scripts. -**Kuinka OmniRoute ratkaisee sen:** +**How OmniRoute solves it:** -- Yhtenäinen päätepistestrategia asiakkaille ja edustajille -- Sisäänrakennetut protokollien hallinnan käyttöliittymät ja savun vahvistuspolut -- Tuotantovalmis perusta (turvallisuus, puunkorjuu, joustavuus, varmuuskopiointi) +- Unified endpoint strategy for clients and agents +- Built-in protocol management UIs and smoke validation paths +- Production-ready foundations (security, logging, resilience, backup)
-` lohkot → `reasoning_content` ajattelumalleille
-- **Strukturoitu tulos** — `json_schema` → Geminin `responseMimeType`/`responseSchema`
-
-### 👥 Usean tilin tuki
-
-- Lisää useita tilejä palveluntarjoajaa kohti
-- Automaattinen round-robin tai prioriteettipohjainen reititys
-- Takaisin seuraavalle tilille, kun kiintiö saavutetaan
-
-### 🔄 Tokenin automaattinen päivitys
-
-- OAuth-tunnukset päivittyvät automaattisesti ennen vanhenemista
-- Manuaalista uudelleentodennusta ei tarvita
-- Saumaton kokemus kaikilta palveluntarjoajilta
-
-### 🎨 Mukautetut yhdistelmät
-
-- Luo rajattomasti malliyhdistelmiä
-- 6 strategiaa: täytä ensin, round-robin, kahden valinnan teho, satunnainen, vähiten käytetty, kustannusoptimoitu
-- Jaa komboja laitteiden välillä Cloud Sync -sovelluksella
-
-### 🏥 Health Dashboard
-
-- Järjestelmän tila (käyttöaika, versio, muistin käyttö)
-- Katkaisijoiden tilat palveluntarjoajan mukaan (suljettu/auki/puoliauki)
-- Hintarajoituksen tila ja aktiiviset lukitukset
-- Allekirjoitusvälimuistin tilastot
-- Latenssi-telemetria (p50/p95/p99) + välimuisti
-- Palauta terveydentila yhdellä napsautuksella
-
-### 🔧 Kääntäjän leikkikenttä
-
-OmniRoute sisältää tehokkaan sisäänrakennetun Translator Playgroundin, jossa on **4 tilaa** virheenkorjausta, testausta ja API-käännösten seurantaa varten:
-
-| Tila | Kuvaus |
-| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **💻 Leikkikenttä** | Suoramuotoinen käännös — liitä mikä tahansa API-pyynnön runko ja katso heti, kuinka OmniRoute kääntää sen toimittajamuotojen välillä (OpenAI ↔ Claude ↔ Gemini ↔ Responses API). Sisältää esimerkkimalleja ja muotojen automaattisen tunnistuksen. |
-| **💬 Chat Tester** | Lähetä todellisia chat-pyyntöjä OmniRouten kautta ja katso koko meno-paluu: syötteesi, käännetty pyyntö, palveluntarjoajan vastaus ja käännetty vastaus takaisin. Korvaamaton yhdistelmäreitityksen vahvistamisessa. |
-| **🧪 Testipenkki** | Erätestaustila — määritä useita testitapauksia eri tuloilla ja odotettavissa olevilla lähdöillä, suorita ne kaikki kerralla ja vertaile tuloksia eri toimittajien ja mallien välillä. |
-| **📱 Live Monitor** | Reaaliaikainen pyyntöjen seuranta – seuraa saapuvia pyyntöjä niiden kulkeessa OmniRouten kautta, katso muotokäännökset reaaliajassa ja tunnista ongelmat välittömästi. |
-
-**Käyttö:** Kojelauta → Kääntäjä (sivupalkki)
-
-### 💾 Cloud Sync
-
-- Synkronoi palveluntarjoajat, yhdistelmät ja asetukset eri laitteiden välillä
-- Automaattinen taustasynkronointi
-- Suojattu salattu tallennustila
+- `GET /api/mcp/status`
+- `GET /api/mcp/tools`
+- `GET /api/mcp/audit`
+- `GET /api/mcp/audit/stats`
-## 🧪 Arvioinnit (Evals)
+📖 Ominaisuuden tiedot
+🧩 MCP Setup (Model Context Protocol)
-### 🎯 Älykäs 4-tasoinen varavaihtoehto +Start MCP transport in stdio mode: -Luo komboja automaattisella varalla: - -``` -Combo: "my-coding-stack" - 1. cc/claude-opus-4-6 (your subscription) - 2. nvidia/llama-3.3-70b (free NVIDIA API) - 3. glm/glm-4.7 (cheap backup, $0.6/1M) - 4. if/kimi-k2-thinking (free fallback) - -→ Auto switches when quota runs out or errors occur +```bash +omniroute --mcp ``` -### 📊 Reaaliaikainen kiintiöseuranta +Recommended validation flow: -- Token-kulutus palveluntarjoajaa kohti -- Nollaa lähtölaskenta (5 tuntia, päivittäin, viikoittain) -- Kustannusarvio maksetuille tasoille -- Kuukausittaiset kuluraportit +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. -### 🔄 Muotoile käännös +Useful APIs for automation: -Saumaton käännös muotojen välillä: - -- **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **OpenAI-vastaukset** -- CLI-työkalusi lähettää OpenAI-muodon → OmniRoute kääntää → Palveluntarjoaja vastaanottaa alkuperäisen muodon -- Toimii minkä tahansa työkalun kanssa, joka tukee mukautettuja OpenAI-päätepisteitä -- **Vastauksen desinfiointi** - Poistaa standardista poikkeavat kentät tiukan OpenAI SDK -yhteensopivuuden varmistamiseksi -- **Roolin normalisointi** — `developer` → `system` ei-OpenAI:lle; `system` → `user` GLM/ERNIE-malleille -- **Ajattele tunnisteen purkaminen** — `
+
🤝 A2A Setup (Agent2Agent)
-OmniRoute sisältää sisäänrakennetun arviointikehyksen, jolla testataan LLM-vastauksen laatua kultaiseen joukkoon verrattuna. Käytä sitä kojelaudan **Analytics → Evals** kautta. +Discover the agent: -### Sisäänrakennettu kultainen setti +```bash +curl http://localhost:20128/.well-known/agent.json +``` -Esiladattu "OmniRoute Golden Set" sisältää 10 testitapausta, jotka kattavat: +Send a task: -- Tervehdys, matematiikka, maantiede, koodin luominen -- JSON-muodon noudattaminen, käännös, merkintä -- Turvallisuuskielto (haitallinen sisältö), laskenta, boolen logiikka +```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."}]}}' +``` -### Arviointistrategiat +Manage lifecycle: -| Strategia | Kuvaus | Esimerkki | -| ---------- | ------------------------------------------------------------------------ | -------------------------------- | -| `exact` | Tulosten on vastattava tarkasti | `"4"` | -| `contains` | Tulosteen tulee sisältää alimerkkijono (kirjainkoolla ei ole merkitystä) | `"Paris"` | -| `regex` | Tulostuksen on vastattava regex-mallia | `"1.*2.*3"` | -| `custom` | Mukautettu JS-funktio palauttaa true/false | `(output) => output.length > 10` | +- `GET /api/a2a/status` +- `GET /api/a2a/tasks` +- `GET /api/a2a/tasks/:id` +- `POST /api/a2a/tasks/:id/cancel` ---- +Operational UI: -## 📖 Asennusopas +- `/dashboard/a2a` for task/state/stream observability and smoke actions + +
-
+
+💳 Tilauksen tarjoajat
+🧪 End-to-end protocol validation
+ +Validate both protocols with real clients: + +```bash +npm run test:protocols:e2e +``` + +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) @@ -1066,7 +1438,7 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Provinkki:** Käytä Opusta monimutkaisiin tehtäviin ja Sonnetia nopeutta varten. OmniRoute jäljityskiintiö mallia kohden! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! ### OpenAI Codex (Plus/Pro) @@ -1080,7 +1452,24 @@ Models: cx/gpt-5.1-codex-max ``` -### Gemini CLI (ILMAINEN 180 000/kk!) +#### 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). + +### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -1092,7 +1481,7 @@ Models: gc/gemini-2.5-pro ``` -**Paras hinta-laatusuhde:** Valtava ilmainen taso! Käytä tätä ennen maksettuja tasoja. +**Best Value:** Huge free tier! Use this before paid tiers. ### GitHub Copilot @@ -1110,88 +1499,88 @@ Models:
-
🔑 API-avaintoimittajat
+🔑 API Key Providers
-### NVIDIA NIM (ILMAINEN 1000 krediittiä!) +### NVIDIA NIM (FREE developer access — 70+ models) -1. Rekisteröidy: [build.nvidia.com](https://build.nvidia.com) -2. Hanki ilmainen API-avain (sisältää 1000 johtopäätöskrediittiä) -3. Kojelauta → Lisää toimittaja → NVIDIA NIM: - - API-avain: `nvapi-your-key` +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` -**Mallit:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct` ja yli 50 muuta +**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more -**Provinkki:** OpenAI-yhteensopiva API – toimii saumattomasti OmniRouten muotokäännöksen kanssa! +**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation! ### DeepSeek -1. Rekisteröidy: [platform.deepseek.com](https://platform.deepseek.com) -2. Hanki API-avain +1. Sign up: [platform.deepseek.com](https://platform.deepseek.com) +2. Get API key 3. Dashboard → Add Provider → DeepSeek -**Mallit:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` +**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` -### Groq (ilmainen taso saatavilla!) +### Groq (Free Tier Available!) -1. Rekisteröidy: [console.groq.com](https://console.groq.com) -2. Hanki API-avain (ilmainen taso mukana) +1. Sign up: [console.groq.com](https://console.groq.com) +2. Get API key (free tier included) 3. Dashboard → Add Provider → Groq -**Mallit:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` +**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` -**Provinkki:** Erittäin nopea päättely – paras reaaliaikaiseen koodaukseen! +**Pro Tip:** Ultra-fast inference — best for real-time coding! -### OpenRouter (100+ mallia) +### OpenRouter (100+ Models) -1. Rekisteröidy: [openrouter.ai](https://openrouter.ai) -2. Hanki API-avain +1. Sign up: [openrouter.ai](https://openrouter.ai) +2. Get API key 3. Dashboard → Add Provider → OpenRouter -**Mallit:** Käytä yli 100 mallia kaikilta tärkeimmiltä palveluntarjoajilta yhdellä API-avaimella. +**Models:** Access 100+ models from all major providers through a single API key.
-
💰 Halvat palveluntarjoajat (Varmuuskopio)
+💰 Cheap Providers (Backup)
-### GLM-4.7 (Päivittäinen nollaus, 0,6 $/1 milj.) +### GLM-4.7 (Daily reset, $0.6/1M) -1. Rekisteröidy: [Zhipu AI](https://open.bigmodel.cn/) -2. Hanki API-avain Coding Planista -3. Hallintapaneeli → Lisää API-avain: - - Palveluntarjoaja: `glm` - - API-avain: `your-key` +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` -**Käytä:** `glm/glm-4.7` +**Use:** `glm/glm-4.7` -**Provinkki:** Koodaussuunnitelma tarjoaa 3-kertaisen kiintiön 1/7 hinnalla! Nollaa päivittäin klo 10.00. +**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -### MiniMax M2.1 (5 h nollaus, 0,20 $/1 milj.) +### MiniMax M2.1 (5h reset, $0.20/1M) -1. Rekisteröidy: [MiniMax](https://www.minimax.io/) -2. Hanki API-avain -3. Kojelauta → Lisää API-avain +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key +3. Dashboard → Add API Key -**Käytä:** `minimax/MiniMax-M2.1` +**Use:** `minimax/MiniMax-M2.1` -**Ammattilaisen vinkki:** Halvin vaihtoehto pitkälle kontekstille (1 milj. merkkiä)! +**Pro Tip:** Cheapest option for long context (1M tokens)! -### Kimi K2 (9 dollaria/kk asunto) +### Kimi K2 ($9/month flat) -1. Tilaa: [Moonshot AI](https://platform.moonshot.ai/) -2. Hanki API-avain -3. Kojelauta → Lisää API-avain +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key +3. Dashboard → Add API Key -**Käytä:** `kimi/kimi-latest` +**Use:** `kimi/kimi-latest` -**Ammattilaisen vinkki:** Kiinteä 9 dollaria kuukaudessa 10 miljoonalle tokenille = 0,90 dollaria / 1 miljoona todellista hintaa! +**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
-
🆓 ILMAISIA palveluntarjoajia (hätävarmuuskopio)
+🆓 FREE Providers (Emergency Backup)
-### iFlow (8 ILMAISTA mallia) +### iFlow (5 FREE models via OAuth) ```bash Dashboard → Connect iFlow @@ -1206,7 +1595,7 @@ Models: if/deepseek-r1 ``` -### Qwen (3 ILMAISTA mallia) +### Qwen (4 FREE models via Device Code) ```bash Dashboard → Connect Qwen @@ -1218,7 +1607,7 @@ Models: qw/qwen3-coder-flash ``` -### Kiro (Claude ILMAINEN) +### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro @@ -1233,9 +1622,9 @@ Models:
-
🎨 Luo komboja
+🎨 Create Combos
-### Esimerkki 1: Maksimoi tilaus → Halpa varmuuskopio +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -1249,7 +1638,7 @@ Models: Use in CLI: premium-coding ``` -### Esimerkki 2: Vain ilmainen (nollahinta) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -1264,9 +1653,9 @@ Cost: $0 forever!
-
---
-## 🐛 Vianetsintä
+## Vianmääritys
🔧 CLI-integrointi
+🔧 CLI Integration
-### Kohdistimen IDE +### Cursor IDE ``` Settings → Models → Advanced: @@ -1277,7 +1666,7 @@ Settings → Models → Advanced: ### Claude Code -Käytä kojelaudan **CLI Tools** -sivua määrittääksesi yhdellä napsautuksella tai muokkaa `~/.claude/settings.json` manuaalisesti. +Use the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually. ### Codex CLI @@ -1290,13 +1679,13 @@ codex "your prompt" ### OpenClaw -**Vaihtoehto 1 – hallintapaneeli (suositus):** +**Option 1 — Dashboard (recommended):** ``` Dashboard → CLI Tools → OpenClaw → Select Model → Apply ``` -**Vaihtoehto 2 – Manuaalinen:** Muokkaa `~/.openclaw/openclaw.json`: +**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`: ```json { @@ -1312,7 +1701,7 @@ Dashboard → CLI Tools → OpenClaw → Select Model → Apply } ``` -> **Huomaa:** OpenClaw toimii vain paikallisen OmniRouten kanssa. Käytä `127.0.0.1` `localhost` sijaan IPv6-resoluutioongelmien välttämiseksi. +> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues. ### Cline / Continue / RooCode @@ -1324,110 +1713,245 @@ Settings → API Configuration: 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. +
- Le quota d'abonnement expire inutilisé chaque mois
-- Les limites de débit vous arrêtent en plein codage
-- APIs coûteuses (20-50 $/mois par fournisseur)
-- Changement manuel entre fournisseurs
-
-**OmniRoute résout ces problèmes :**
-
-- ✅ **Maximisez les abonnements** — Suivez les quotas, utilisez chaque bit avant la réinitialisation
-- ✅ **Fallback automatique** — Abonnement → Clé API → Économique → Gratuit, zéro temps d'arrêt
-- ✅ **Multi-comptes** — Round-robin entre les comptes par fournisseur
-- ✅ **Universel** — Fonctionne avec Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, tout outil CLI
+- ✅ **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
+- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool
---
## 📧 Support
-> 💬 **Rejoignez notre communauté !** [Groupe WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Obtenez de l'aide, partagez des astuces et restez informé.
+> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.
-- **Site web** : [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** : [Groupe communautaire](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Projet original** : [9router par decolua](https://github.com/decolua/9router)
+- **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`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 Comment ça fonctionne
+## 🔄 How It Works
```
┌─────────────┐
-│ Votre CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
+│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
│ Tool │
└──────┬──────┘
│ http://localhost:20128/v1
↓
┌─────────────────────────────────────────┐
-│ OmniRoute (Routeur intelligent) │
-│ • Traduction de format (OpenAI ↔ Claude) │
-│ • Suivi des quotas + Embeddings + Images │
-│ • Renouvellement automatique des tokens │
+│ OmniRoute (Smart Router) │
+│ • Format translation (OpenAI ↔ Claude) │
+│ • Quota tracking + Embeddings + Images │
+│ • Auto token refresh │
└──────┬──────────────────────────────────┘
│
- ├─→ [Tier 1: ABONNEMENT] Claude Code, Codex, Gemini CLI
- │ ↓ quota épuisé
- ├─→ [Tier 2: CLÉ API] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.
- │ ↓ limite de budget
- ├─→ [Tier 3: ÉCONOMIQUE] GLM ($0.6/1M), MiniMax ($0.2/1M)
- │ ↓ limite de budget
- └─→ [Tier 4: GRATUIT] iFlow, Qwen, Kiro (illimité)
+ ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI
+ │ ↓ 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] iFlow, Qwen, Kiro (unlimited)
-Résultat : Ne jamais arrêter de coder, coût minimal
+Result: Never stop coding, minimal cost
```
---
-## 🎯 Ce qu'OmniRoute résout : 30 problèmes réels et cas d'utilisation
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **Tous les développeurs utilisant des outils d'IA sont confrontés quotidiennement à ces problèmes.** OmniRoute a été conçu pour tous les résoudre : des dépassements de coûts aux blocages régionaux, des flux OAuth interrompus aux opérations de protocole et à l'observabilité de l'entreprise.
+> **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.
מכסת המנויים מסתיימת ללא שימוש בכל חודש
-- מגבלות קצב עוצרות אותך בקידוד באמצע
-- ממשקי API יקרים ($20-50 לחודש לכל ספק)
-- מעבר ידני בין ספקים
-
-**OmniRoute פותר את זה:**
-
-- ✅ **מקסם מנויים** - עקוב אחר מכסת, השתמש בכל סיביות לפני האיפוס
-- ✅ **החזר אוטומטי** - מנוי → מפתח API → זול → חינם, אפס זמן השבתה
-- ✅ **ריבוי חשבונות** - סיבוב בין חשבונות לכל ספק
-- ✅ **אוניברסלי** - עובד עם קלוד קוד, Codex, Gemini CLI, Cursor, Cline, OpenClaw, כל כלי CLI
-
----
-
-## 📧 תמיכה
-
-> 💬 **הצטרפו לקהילה שלנו!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — קבל עזרה, שתף טיפים והישאר מעודכן.
-
-- **אתר**: [omniroute.online](https://omniroute.online)
+- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **בעיות**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **וואטסאפ**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **פרויקט מקורי**: [9router by decolua](https://github.com/decolua/9router)
+- **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`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 איך זה עובד
+## 🔄 How It Works
```
┌─────────────┐
@@ -227,451 +236,453 @@ Result: Never stop coding, minimal cost
---
-## 🎯 מה OmniRoute פותר - 30 נקודות כאב אמיתיות ומקרי שימוש
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **כל מפתח המשתמש בכלי בינה מלאכותית מתמודד עם הבעיות הללו מדי יום.** OmniRoute נבנתה כדי לפתור את כולן - החל מחריפות עלויות ועד לחסימות אזוריות, מזרימות OAuth שבורות ועד פעולות פרוטוקול וצפייה ארגונית.
+> **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.
Az előfizetési kvóta minden hónapban fel nem használt
-- A sebességkorlátok megakadályozzák a közbenső kódolást
-- Drága API-k (20-50 USD/hó szolgáltatónként)
-- Manuális váltás a szolgáltatók között
-
-**Az OmniRoute ezt megoldja:**
-
-- ✅ **Az előfizetések maximalizálása** - Kövesse nyomon a kvótát, használjon fel minden bitet a visszaállítás előtt
-- ✅ **Automatikus tartalék** - Előfizetés → API-kulcs → Olcsó → Ingyenes, nulla állásidő
-- ✅ **Több fiók** - Kör-robin a fiókok között szolgáltatónként
-- ✅ **Univerzális** - Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, bármilyen CLI eszközzel működik
-
----
-
-## 📧 Támogatás
-
-> 💬 **Csatlakozzon közösségünkhöz!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Kérjen segítséget, ossza meg tippjeit, és naprakész legyen.
-
-- **Webhely**: [omniroute.online](https://omniroute.online)
+- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Problémák**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Eredeti projekt**: [9router by decolua](https://github.com/decolua/9router)
+- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 Hogyan működik
+## 🔄 How It Works
```
┌─────────────┐
@@ -227,452 +236,453 @@ Result: Never stop coding, minimal cost
---
-## 🎯 Mit old meg az OmniRoute – 30 valódi fájdalompont és használati eset
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **Minden mesterséges intelligencia-eszközöket használó fejlesztő naponta szembesül ezekkel a problémákkal.** Az OmniRoute úgy készült, hogy ezeket mind megoldja – a költségtúllépésektől a regionális blokkokig, a megszakadt OAuth-folyamatoktól a protokollműveletekig és a vállalati megfigyelhetőségig.
+> **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.
Laajenna vianetsintäopas napsauttamalla
+Click to expand troubleshooting guide
-**"Kielimalli ei antanut viestejä"** +**"Language model did not provide messages"** -- Palveluntarjoajan kiintiö käytetty loppuun → Tarkista kojelaudan kiintiön seuranta -- Ratkaisu: Käytä yhdistelmävaraa tai vaihda halvempaan tasoon +- Provider quota exhausted → Check dashboard quota tracker +- Solution: Use combo fallback or switch to cheaper tier -**hintarajoitus** +**Rate limiting** -- Tilauskiintiö loppu → Varaa GLM/MiniMaxiin -- Lisää yhdistelmä: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Subscription quota out → Fallback to GLM/MiniMax +- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -**OAuth-tunnus vanhentunut** +**OAuth token expired** -- OmniRoute päivittää automaattisesti -- Jos ongelmat jatkuvat: Kojelauta → Palveluntarjoaja → Yhdistä uudelleen +- Auto-refreshed by OmniRoute +- If issues persist: Dashboard → Provider → Reconnect -**Korkeat kustannukset** +**High costs** -- Tarkista käyttötilastot kohdassa Dashboard → Costs -- Vaihda ensisijaiseksi malliksi GLM/MiniMax -- Käytä ilmaista tasoa (Gemini CLI, iFlow) ei-kriittisiin tehtäviin +- Check usage stats in Dashboard → Costs +- Switch primary model to GLM/MiniMax +- Use free tier (Gemini CLI, iFlow) for non-critical tasks -**Kojelauta avautuu väärään porttiin** +**Dashboard/API ports are wrong** -- Aseta `PORT=20128` ja `NEXT_PUBLIC_BASE_URL=http://localhost:20128` +- `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) -**Pilvisynkronointivirheet** +**Cloud sync errors** -- Vahvista `BASE_URL` pistettä käynnissä olevaan esiintymääsi -- Vahvista `CLOUD_URL` pistettä odotettuun pilvipäätepisteeseen -- Pidä `NEXT_PUBLIC_*`-arvot kohdakkain palvelinpuolen arvojen kanssa +- 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 -**Ensimmäinen kirjautuminen ei toimi** +**First login not working** -- Tarkista `INITIAL_PASSWORD` kohteessa `.env` -- Jos ei ole asetettu, varasalasana on `123456` +- Check `INITIAL_PASSWORD` in `.env` +- If unset, fallback password is `123456` -**Ei pyyntölokeja** +**No request logs** -- Aseta `ENABLE_REQUEST_LOGS=true` kohteeseen `.env` +- Set `ENABLE_REQUEST_LOGS=true` in `.env` -**Yhteystesti näyttää "Virheellinen" OpenAI-yhteensopiville palveluntarjoajille** +**Connection test shows "Invalid" for OpenAI-compatible providers** -- Monet palveluntarjoajat eivät paljasta `/models`-päätepistettä -- OmniRoute v1.0.6+ sisältää varatarkistuksen chatin loppuunsaattamisen kautta -- Varmista, että perus-URL sisältää `/v1`-liitteen +- 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 +### 🔐 OAuth on a Remote Server + -> **⚠️ TÄRKEÄÄ käyttäjille com OmniRoute em VPS/Docker/servidor Remoto** +> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server** -### OAuth +#### Why does Antigravity / Gemini CLI OAuth fail on remote servers? -Os provedores **Antigravity** ja **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pre-cadastradas no Google Cloud Console do aplicativo. +The **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console. -As credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para `localhost`**. Quando você acessa o OmniRoute em um servidor Remoto (esim. `https://omniroute.meuservidor.com`), o Google rejeita a autenticação com: +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 ``` -### Ratkaisu: Määritä suas próprias credenciais OAuth +#### Solution: Configure your own OAuth credentials -Você precisa criar um **OAuth 2.0 Client ID** ei Google Cloud Console com URI do seu servidor. +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 + +# For Gemini CLI: +GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com +GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +``` + +**6. Restart OmniRoute** + +```bash +# npm: +npm run dev + +# Docker: +docker restart omniroute +``` + +**7. Try connecting again** + +Dashboard → Providers → Antigravity (or Gemini CLI) → OAuth + +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. + +--- + +
+
-- **Suoritusaika**: Node.js 18–22 LTS (⚠️ Node.js 24+ -versiota **ei tueta** — `better-sqlite3` alkuperäiset binaarit eivät ole yhteensopivia)
-- **Kieli**: TypeScript 5.9 — **100 % TypeScript** `src/` ja `open-sse/` (v1.0.6) välillä
-- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4
-- **Tietokanta**: LowDB (JSON) + SQLite (verkkotunnuksen tila + välityspalvelimen lokit)
-- **Striimaus**: Palvelimen lähettämät tapahtumat (SSE)
-- **Auth**: OAuth 2.0 (PKCE) + JWT + API-avaimet
-- **Testaus**: Node.js-testausohjelma (368+ yksikkötestiä)
-- **CI/CD**: GitHub Actions (automaattinen npm-julkaisu + Docker Hub julkaisussa)
-- **Verkkosivusto**: [omniroute.online](https://omniroute.online)
-- **Paketti**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
-- **Dokkeri**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
-- **Kestävyys**: Katkaisija, eksponentiaalinen backoff, ukkosen esto, TLS-huijaus
-
----
-
-## 📖 Dokumentaatio
-
-| Asiakirja | Kuvaus |
-| -------------------------------------------- | ------------------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Palveluntarjoajat, yhdistelmät, CLI-integrointi, käyttöönotto |
-| [API Reference](docs/API_REFERENCE.md) | Kaikki päätepisteet esimerkeineen |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Yleisiä ongelmia ja ratkaisuja |
-| [Architecture](docs/ARCHITECTURE.md) | Järjestelmäarkkitehtuuri ja sisäosat |
-| [Contributing](CONTRIBUTING.md) | Kehittämisjärjestelyt ja -ohjeet |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 -spesifikaatio |
-| [Security Policy](SECURITY.md) | Haavoittuvuusraportointi ja tietoturvakäytännöt |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Täydellinen opas: VM + nginx + Cloudflare-asennus |
-| [Features Gallery](docs/FEATURES.md) | Visuaalinen kojelautakierros kuvakaappauksilla |
-
-### 📸 Kojelaudan esikatselu
+## 🛠️ Tech Stack
🇧🇷 Versão em Português
+ +#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos? + +Os provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo. + +As credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticação com: + +``` +Error 400: redirect_uri_mismatch +``` + +#### Solução: Configure suas próprias credenciais OAuth + +Você precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor. #### Passo a passo -**1. Acesse tai Google Cloud Console** +**1. Acesse o Google Cloud Console** Abra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) -**2. Crie um novo OAuth 2.0 -asiakastunnus** +**2. Crie um novo OAuth 2.0 Client ID** -- Klikkaa em **"+ Luo kirjautumistiedot"** → **"OAuth-asiakastunnus"** -- Tipo de aplicativo: **"Web-sovellus"** -- Nimi: escolha qualquer nome (esim.: `OmniRoute Remote`) +- Clique em **"+ Create Credentials"** → **"OAuth client ID"** +- Tipo de aplicativo: **"Web application"** +- Nome: escolha qualquer nome (ex: `OmniRoute Remote`) -**3. Adicione valtuutettuina uudelleenohjaus-URI:ina** +**3. Adicione as Authorized Redirect URIs** -No campo **"Authorized redirect URIs"**, lisäys: +No campo **"Authorized redirect URIs"**, adicione: ``` https://seu-servidor.com/callback ``` -> Korvaa `seu-servidor.com` pelo dominio tai IP do seu servidor (mukaan lukien porta se necessário, esim. `http://45.33.32.156:20128/callback`). +> Substitua `seu-servidor.com` pelo domínio ou IP do seu servidor (inclua a porta se necessário, ex: `http://45.33.32.156:20128/callback`). -**4. Tallenna kopio valtuutuksena** +**4. Salve e copie as credenciais** Após criar, o Google mostrará o **Client ID** e o **Client Secret**. -**5. Määritä variáveis de ambiente** +**5. Configure as variáveis de ambiente** -Ei seu `.env` (ou nas variáveis de ambiente do Docker): +No seu `.env` (ou nas variáveis de ambiente do Docker): ```bash # Para Antigravity: @@ -1462,11 +1986,11 @@ Agora o Google redirecionará corretamente para `https://seu-servidor.com/callba Se não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**: -1. OmniRoute lähettää Googlen lupa-osoitteen -2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor Remoto) -3. **Kopioi URL-osoite täydellinen** da barra de endereço do seu selaimessa (mesmo que a página não carregue) +1. O OmniRoute abrirá a URL de autorização do Google +2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto) +3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue) 4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute -5. Klikkaa em **"Yhdistä"** +5. Clique em **"Connect"** > Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não. @@ -1474,128 +1998,123 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux --- -## 🛠️ +
-
---
-## 🗺️
+## Dokumentaatio
-OmniRoutella on **210+ suunniteltua ominaisuutta** useissa kehitysvaiheissa. Tässä ovat tärkeimmät alueet:
-
-| Luokka | Suunnitellut ominaisuudet | Kohokohdat |
-| ------------------------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| 🧠 **Routing & Intelligence** | 25+ | Pienimmän viiveen reititys, tunnistepohjainen reititys, kiintiön esitarkastus, P2C-tilin valinta |
-| 🔒 **Turvallisuus ja vaatimustenmukaisuus** | 20+ | SSRF-karkaisu, valtuustietojen peittäminen, päätepistekohtainen nopeusraja, hallintaavaimen laajuus |
-| 📊 **Havaittavuus** | 15+ | OpenTelemetry-integraatio, reaaliaikainen kiintiöiden seuranta, kustannusseuranta mallikohtaisesti |
-| 🔄 **Tarjoajien integraatiot** | 20+ | Dynaaminen mallirekisteri, palveluntarjoajan jäähtyminen, usean tilin Codex, Copilot-kiintiön jäsentäminen |
-| ⚡ **Suorituskyky** | 15+ | Kaksoisvälimuistikerros, kehotevälimuisti, vastausvälimuisti, suoratoiston ylläpitäminen, erä-API |
-| 🌐 **Ekosysteemi** | 10+ | WebSocket API, konfiguroinnin hot-reload, hajautettu konfiguraatiosäilö, kaupallinen tila |
-
-### 🔜 Tulossa pian
-
-- 🔗 **OpenCode Integration** - Natiivitoimittajan tuki OpenCode AI -koodaus-IDE:lle
-- 🔗 **TRAE-integraatio** — Täysi tuki TRAE AI -kehityskehykselle
-- 📦 **Eräsovellusliittymä** — Asynkroninen eräkäsittely joukkopyyntöille
-- 🎯 **Tagipohjainen reititys** - Reittipyynnöt mukautettujen tunnisteiden ja metatietojen perusteella
-- 💰 **Alhaisimman kustannustason strategia** - Valitse automaattisesti halvin saatavilla oleva palveluntarjoaja
-
-> 📝 Täydelliset ominaisuudet saatavilla osoitteessa [link](docs/new-features/) (217 yksityiskohtaista spesifikaatiota)
+| Document | Description |
+| ---------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 16 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/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
+| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
-## 👥 Avustajat
+## 🗺️ Roadmap
+
+OmniRoute has **210+ 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, P2C account selection |
+| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |
+| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |
+| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider 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
[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
-### Kuinka osallistua
+### How to Contribute
-1. Haarukka arkisto
-2. Luo ominaisuushaara (`git checkout -b feature/amazing-feature`)
-3. Vahvista muutokset (`git commit -m 'Add amazing feature'`)
-4. Työnnä haaraan (`git push origin feature/amazing-feature`)
-5. Avaa vetopyyntö
+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
-Katso tarkemmat ohjeet kohdasta [CONTRIBUTING.md](CONTRIBUTING.md).
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
-### Uuden version julkaisu
+### Releasing a New Version
```bash
# Create a release — npm publish happens automatically
-gh release create v1.0.6 --title "v1.0.6" --generate-notes
+gh release create v2.0.0 --title "v2.0.0" --generate-notes
```
---
-## 📊 Tähtihistoria
+## 📊 Star History
## Stargazers over time
## [](https://starchart.cc/diegosouzapw/OmniRoute)
-## 🙏 Kiitokset
+## 🙏 Acknowledgments
-Erityinen kiitos **[9router](https://github.com/decolua/9router)**, **[decolua](https://github.com/decolua)** - alkuperäinen projekti, joka inspiroi tätä haarukkaa. OmniRoute rakentaa tälle uskomattomalle perustalle lisäominaisuuksia, multimodaalisia API-liittymiä ja täydellistä TypeScript-uudelleenkirjoitusta.
+Special thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.
-Erityinen kiitos **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** - alkuperäiselle Go-toteutukselle, joka inspiroi tätä JavaScript-porttia.
+Special thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.
---
-## 📄 Lisenssi
+## Lisenssi
-MIT-lisenssi – katso lisätietoja osoitteesta [LICENSE](LICENSE).
+MIT License - see [LICENSE](LICENSE) for details.
---
Klikkaa nähdäksesi hallintapaneelin kuvakaappaukset
+Click to expand tech stack details
-| Sivu | Kuvakaappaus | -| ---------------- | ------------------------------------------------- | -| **Palvelut** |  | -| **Yhdistelmät** |  | -| **Analytics** |  | -| **Terveys** |  | -| **Kääntäjä** |  | -| **Asetukset** |  | -| **CLI-työkalut** |  | -| **Käyttölokit** |  | -| **Päätepiste** |  | +- **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**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions) +- **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
- Rakennettu ❤️-kehittäjille, jotka koodaavat 24/7
+ Built with ❤️ for developers who code 24/7
omniroute.online
+
diff --git a/docs/i18n/fi/docs/FEATURES.md b/docs/i18n/fi/docs/FEATURES.md
new file mode 100644
index 0000000000..45932eeb41
--- /dev/null
+++ b/docs/i18n/fi/docs/FEATURES.md
@@ -0,0 +1,145 @@
+# OmniRoute — Dashboard Features Gallery (Suomi)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/FEATURES.md) · 🇪🇸 [es](../../es/docs/FEATURES.md) · 🇫🇷 [fr](../../fr/docs/FEATURES.md) · 🇩🇪 [de](../../de/docs/FEATURES.md) · 🇮🇹 [it](../../it/docs/FEATURES.md) · 🇷🇺 [ru](../../ru/docs/FEATURES.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FEATURES.md) · 🇯🇵 [ja](../../ja/docs/FEATURES.md) · 🇰🇷 [ko](../../ko/docs/FEATURES.md) · 🇸🇦 [ar](../../ar/docs/FEATURES.md) · 🇮🇳 [in](../../in/docs/FEATURES.md) · 🇹🇭 [th](../../th/docs/FEATURES.md) · 🇻🇳 [vi](../../vi/docs/FEATURES.md) · 🇮🇩 [id](../../id/docs/FEATURES.md) · 🇲🇾 [ms](../../ms/docs/FEATURES.md) · 🇳🇱 [nl](../../nl/docs/FEATURES.md) · 🇵🇱 [pl](../../pl/docs/FEATURES.md) · 🇸🇪 [sv](../../sv/docs/FEATURES.md) · 🇳🇴 [no](../../no/docs/FEATURES.md) · 🇩🇰 [da](../../da/docs/FEATURES.md) · 🇫🇮 [fi](../../fi/docs/FEATURES.md) · 🇵🇹 [pt](../../pt/docs/FEATURES.md) · 🇷🇴 [ro](../../ro/docs/FEATURES.md) · 🇭🇺 [hu](../../hu/docs/FEATURES.md) · 🇧🇬 [bg](../../bg/docs/FEATURES.md) · 🇸🇰 [sk](../../sk/docs/FEATURES.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FEATURES.md) · 🇮🇱 [he](../../he/docs/FEATURES.md) · 🇵🇭 [phi](../../phi/docs/FEATURES.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FEATURES.md)
+
+---
+
+Visual guide to every section of the OmniRoute dashboard.
+
+---
+
+## 🔌 Providers
+
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
+
+
+
+---
+
+## 🎨 Combos
+
+Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
+
+
+
+---
+
+## 📊 Analytics
+
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
+
+
+
+---
+
+## 🏥 System Health
+
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+
+
+
+---
+
+## 🔧 Translator Playground
+
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
+
+
+
+---
+
+## 🎮 Model Playground _(v2.0.9+)_
+
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
+
+---
+
+## 🎨 Themes _(v2.0.5+)_
+
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
+
+## ⚙️ Settings
+
+Comprehensive settings panel with tabs:
+
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning
+- **Advanced** — Configuration overrides
+
+
+
+---
+
+## 🔧 CLI Tools
+
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
+
+
+
+---
+
+## 🤖 CLI Agents _(v2.0.11+)_
+
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
+
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
+
+---
+
+## 🖼️ Media _(v2.0.3+)_
+
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
+
+## 📝 Request Logs
+
+Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
+
+
+
+---
+
+## 🌐 API Endpoint
+
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
+
+
+
+---
+
+## 🔑 API Key Management
+
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
+
+---
+
+## 📋 Audit Log
+
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
+
+---
+
+## 🖥️ Desktop Application
+
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
+
+Key features:
+
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
+
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.
diff --git a/docs/i18n/fr/README.md b/docs/i18n/fr/README.md
index 1e9bfdb2af..01037143df 100644
--- a/docs/i18n/fr/README.md
+++ b/docs/i18n/fr/README.md
@@ -1,24 +1,94 @@
-omniroute.online
-
-
- # 🚀 OmniRoute — La Passerelle IA Gratuite
+# 🚀 OmniRoute — The Free AI Gateway (Français)
-### N'arrêtez jamais de coder. Routage intelligent vers des **modèles IA GRATUITS et économiques** avec fallback automatique.
-
-_Votre proxy API universel — un endpoint, 36+ fournisseurs, zéro temps d'arrêt._
-
-**Chat Completions • Embeddings • Génération d'images • Audio • Reranking • 100% TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Fournisseur IA gratuit pour vos agents de programmation préférés
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Connectez n'importe quel IDE ou outil CLI alimenté par l'IA via OmniRoute — passerelle API gratuite pour un codage illimité._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+` tags no longer leak to clients in SSE streaming responses (#585) |
+| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with per-provider/account quota enforcement, idempotency, SHA-256 storage, and optional GitHub issue reporting |
+| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG → generic fallback chain |
+| 🔄 **Model Auto-Sync** | 24h scheduler and manual UI toggle to sync model lists for built-in and custom OpenAI-compatible providers |
+| 🌐 **OpenCode Zen/Go** | Two new providers from @kang-heewon via PR #530: free tier + subscription tier via `OpencodeExecutor` |
+| 🐛 **Gemini CLI OAuth** | Actionable error when `GEMINI_OAUTH_CLIENT_SECRET` is missing in Docker (was cryptic Google error) |
+| 🐛 **OpenCode config** | `saveOpenCodeConfig()` now correctly writes TOML to `XDG_CONFIG_HOME` |
+| 🐛 **Pinned model override** | `body.model` correctly set to `pinnedModel` on context-cache protection |
+| 🐛 **Codex/Claude loop** | `tool_result` blocks now converted to text to stop infinite loops |
+| 🐛 **Login redirect** | Login no longer freezes after skipping password setup |
+| 🐛 **Windows paths** | MSYS2/Git-Bash paths (`/c/...`) normalized to `C:\...` automatically |
+
+---
+
+## 🖼️ Main Dashboard
+
+
-📡 Tous les agents se connectent via ` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**Stop wasting money and hitting limits:**
-### 🆕 What's New in v3.0.0
+- Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**OmniRoute solves this:**
----
-
-[](https://www.npmjs.com/package/omniroute)
-[](https://hub.docker.com/r/diegosouzapw/omniroute)
-[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
-[](https://omniroute.online)
-[](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-
-[🌐 Site web](https://omniroute.online) • [🚀 Démarrage rapide](#-démarrage-rapide) • [💡 Fonctionnalités](#-fonctionnalités-principales) • [📖 Docs](#-documentation) • [💰 Tarifs](#-aperçu-des-tarifs)
-
-🌐 **Disponible en :** 🇺🇸 [English](../../README.md) | 🇧🇷 [Português (Brasil)](../pt-BR/README.md) | 🇪🇸 [Español](../es/README.md) | 🇫🇷 [Français](../fr/README.md) | 🇮🇹 [Italiano](../it/README.md) | 🇷🇺 [Русский](../ru/README.md) | 🇨🇳 [中文 (简体)](../zh-CN/README.md) | 🇩🇪 [Deutsch](../de/README.md) | 🇮🇳 [हिन्दी](../in/README.md) | 🇹🇭 [ไทย](../th/README.md) | 🇺🇦 [Українська](../uk-UA/README.md) | 🇸🇦 [العربية](../ar/README.md) | 🇯🇵 [日本語](../ja/README.md) | 🇻🇳 [Tiếng Việt](../vi/README.md) | 🇧🇬 [Български](../bg/README.md) | 🇩🇰 [Dansk](../da/README.md) | 🇫🇮 [Suomi](../fi/README.md) | 🇮🇱 [עברית](../he/README.md) | 🇭🇺 [Magyar](../hu/README.md) | 🇮🇩 [Bahasa Indonesia](../id/README.md) | 🇰🇷 [한국어](../ko/README.md) | 🇲🇾 [Bahasa Melayu](../ms/README.md) | 🇳🇱 [Nederlands](../nl/README.md) | 🇳🇴 [Norsk](../no/README.md) | 🇵🇹 [Português (Portugal)](../pt/README.md) | 🇷🇴 [Română](../ro/README.md) | 🇵🇱 [Polski](../pl/README.md) | 🇸🇰 [Slovenčina](../sk/README.md) | 🇸🇪 [Svenska](../sv/README.md) | 🇵🇭 [Filipino](../phi/README.md)
-
-
-
----
-
-## 🖼️
-
-
-
- # 🚀 OmniRoute — La Passerelle IA Gratuite
+# 🚀 OmniRoute — The Free AI Gateway (Français)
-### N'arrêtez jamais de coder. Routage intelligent vers des **modèles IA GRATUITS et économiques** avec fallback automatique.
-
-_Votre proxy API universel — un endpoint, 36+ fournisseurs, zéro temps d'arrêt._
-
-**Chat Completions • Embeddings • Génération d'images • Audio • Reranking • 100% TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Fournisseur IA gratuit pour vos agents de programmation préférés
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Connectez n'importe quel IDE ou outil CLI alimenté par l'IA via OmniRoute — passerelle API gratuite pour un codage illimité._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+
+
+[](https://www.npmjs.com/package/omniroute)
+[](https://www.npmjs.com/package/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
+[](https://omniroute.online)
+[](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)
+
+
+
+🌐 **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)
+
+---
+
+## 🆕 What's New in v3.0.0
+
+> **Upgrading from v2.9.5?** — See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes.
+
+| Area | Change |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection remediation |
+| ✅ **Route Validation** | All 176 API routes now validated with Zod schemas + `validateBody()` — CI `check:route-validation:t06` passes |
+| 🐛 **omniModel Tag Leak** | Internal `
+
+
+
+---
+
+## 📸 Dashboard Preview
+
+
+
+
+
+---
+
+### 🤖 Free AI Provider for your favorite coding agents
+
+_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._
Click to see dashboard screenshots
+ +| Page | Screenshot | +| -------------- | ------------------------------------------------- | +| **Providers** |  | +| **Combos** |  | +| **Analytics** |  | +| **Health** |  | +| **Translator** |  | +| **Settings** |  | +| **CLI Tools** |  | +| **Usage Logs** |  | +| **Endpoints** |  | + +|
-
+
OpenClaw @@ -92,586 +162,527 @@ _Connectez n'importe quel IDE ou outil CLI alimenté par l'IA via OmniRoute — |
http://localhost:20128/v1 ou http://cloud.omniroute.online/v1 — une configuration, modèles et quota illimités
+📡 All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 — one config, unlimited models and quota
---
-### 🆕 What's New in v3.0.0
+## 🤔 Why OmniRoute?
-| Area | Change |
-| ------------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal ` Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `
-
-
-
----
-
-## 📸
-
-
-
-
-
----
-
-## 🤔 Pourquoi OmniRoute ?
-
-**Arrêtez de gaspiller de l'argent et de vous heurter aux limites :**
-
-- ...
- -| # | # | -| ----- | ---------------------------------------- | -| **1** |  | -| **2** |  | -| **3** |  | -| **4** |  | -| **5** |  | -| **6** |  | -| **7** |  | -| **8** |  | -| **9** |  | - - Le quota d'abonnement expire inutilisé chaque mois
-- Les limites de débit vous arrêtent en plein codage
-- APIs coûteuses (20-50 $/mois par fournisseur)
-- Changement manuel entre fournisseurs
-
-**OmniRoute résout ces problèmes :**
-
-- ✅ **Maximisez les abonnements** — Suivez les quotas, utilisez chaque bit avant la réinitialisation
-- ✅ **Fallback automatique** — Abonnement → Clé API → Économique → Gratuit, zéro temps d'arrêt
-- ✅ **Multi-comptes** — Round-robin entre les comptes par fournisseur
-- ✅ **Universel** — Fonctionne avec Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, tout outil CLI
+- ✅ **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
+- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool
---
## 📧 Support
-> 💬 **Rejoignez notre communauté !** [Groupe WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Obtenez de l'aide, partagez des astuces et restez informé.
+> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.
-- **Site web** : [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** : [Groupe communautaire](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Projet original** : [9router par decolua](https://github.com/decolua/9router)
+- **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`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 Comment ça fonctionne
+## 🔄 How It Works
```
┌─────────────┐
-│ Votre CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
+│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
│ Tool │
└──────┬──────┘
│ http://localhost:20128/v1
↓
┌─────────────────────────────────────────┐
-│ OmniRoute (Routeur intelligent) │
-│ • Traduction de format (OpenAI ↔ Claude) │
-│ • Suivi des quotas + Embeddings + Images │
-│ • Renouvellement automatique des tokens │
+│ OmniRoute (Smart Router) │
+│ • Format translation (OpenAI ↔ Claude) │
+│ • Quota tracking + Embeddings + Images │
+│ • Auto token refresh │
└──────┬──────────────────────────────────┘
│
- ├─→ [Tier 1: ABONNEMENT] Claude Code, Codex, Gemini CLI
- │ ↓ quota épuisé
- ├─→ [Tier 2: CLÉ API] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.
- │ ↓ limite de budget
- ├─→ [Tier 3: ÉCONOMIQUE] GLM ($0.6/1M), MiniMax ($0.2/1M)
- │ ↓ limite de budget
- └─→ [Tier 4: GRATUIT] iFlow, Qwen, Kiro (illimité)
+ ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI
+ │ ↓ 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] iFlow, Qwen, Kiro (unlimited)
-Résultat : Ne jamais arrêter de coder, coût minimal
+Result: Never stop coding, minimal cost
```
---
-## 🎯 Ce qu'OmniRoute résout : 30 problèmes réels et cas d'utilisation
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **Tous les développeurs utilisant des outils d'IA sont confrontés quotidiennement à ces problèmes.** OmniRoute a été conçu pour tous les résoudre : des dépassements de coûts aux blocages régionaux, des flux OAuth interrompus aux opérations de protocole et à l'observabilité de l'entreprise.
+> **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.
-
💸 1. "Je paie un abonnement coûteux mais je suis quand même interrompu par des limites"
+💸 1. "I pay for an expensive subscription but still get interrupted by limits"
-Les développeurs paient entre 20 et 200 $/mois pour Claude Pro, Codex Pro ou GitHub Copilot. Même payant, le quota est plafonné : 5 heures d'utilisation, limites hebdomadaires ou limites de tarif à la minute. En cours de session de codage, le fournisseur ne répond plus et le développeur perd en fluidité et en productivité. +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. -**Comment OmniRoute le résout :** +**How OmniRoute solves it:** -- **Smart 4-Tier Fallback** — Si le quota d'abonnement est épuisé, redirige automatiquement vers la clé API → Pas cher → Gratuit sans intervention manuelle -- **Suivi des quotas en temps réel** — Affiche la consommation de jetons en temps réel avec un compte à rebours réinitialisé (5 h, quotidiennement, hebdomadairement) -- **Support multi-comptes** — Plusieurs comptes par fournisseur avec tourniquet automatique — lorsqu'un compte est épuisé, passe au suivant -- **Combos personnalisés** — Chaînes de secours personnalisables avec 6 stratégies d'équilibrage (remplir en premier, round-robin, P2C, aléatoire, les moins utilisées, optimisées en termes de coûts) -- **Codex Business Quotas** — Surveillance des quotas d'espace de travail Business/Équipe directement dans le tableau de bord +- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention +- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly) +- **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 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
-` de modèles comme DeepSeek R1 dans un `reasoning_content` standardisé.
-- **Sortie structurée pour Gemini** — Conversion automatique `json_schema` → `responseMimeType`/`responseSchema`
-- **`stream` est par défaut `false`** — S'aligne sur les spécifications OpenAI, évitant ainsi le SSE inattendu dans les SDK Python/Rust/Go
+- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 67+ 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
🔌 2. "Je dois utiliser plusieurs fournisseurs mais chacun a une API différente"
+🔌 2. "I need to use multiple providers but each has a different API"
-OpenAI utilise un format, Claude (Anthropic) en utilise un autre, Gemini encore un autre. Si un développeur souhaite tester des modèles de différents fournisseurs ou utiliser un modèle de secours entre eux, il doit reconfigurer les SDK, modifier les points de terminaison et gérer les formats incompatibles. Les fournisseurs personnalisés (FriendLI, NIM) ont des points de terminaison de modèle non standard. +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. -**Comment OmniRoute le résout :** +**How OmniRoute solves it:** -- **Point de terminaison unifié** : un seul `http://localhost:20128/v1` sert de proxy pour les plus de 36 fournisseurs. -- **Traduction de format** — Automatique et transparente : OpenAI ↔ Claude ↔ Gemini ↔ API Responses -- **Response Sanitization** — Supprime les champs non standard (`x_groq`, `usage_breakdown`, `service_tier`) qui cassent OpenAI SDK v1.83+ -- **Role Normalization** — Convertit `developer` → `system` pour les fournisseurs non OpenAI ; `system` → `user` pour GLM/ERNIE -- **Think Tag Extraction** — Extrait les blocs `
-
🌐 3. "Mon fournisseur d'IA bloque ma région/pays"
+🌐 3. "My AI provider blocks my region/country"
-Des fournisseurs comme OpenAI/Codex bloquent l’accès depuis certaines régions géographiques. Les utilisateurs obtiennent des erreurs telles que `unsupported_country_region_territory` lors des connexions OAuth et API. Ceci est particulièrement frustrant pour les développeurs des pays en développement. +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. -**Comment OmniRoute le résout :** +**How OmniRoute solves it:** -- **Configuration proxy à 3 niveaux** — Proxy configurable à 3 niveaux : global (tout le trafic), par fournisseur (un seul fournisseur) et par connexion/clé -- **Badges proxy à code couleur** — Indicateurs visuels : 🟢 proxy global, 🟡 proxy fournisseur, 🔵 proxy de connexion, affichant toujours l'adresse IP -- **Échange de jetons OAuth via proxy** — Le flux OAuth passe également par le proxy, résolvant `unsupported_country_region_territory` -- **Tests de connexion via proxy** — Les tests de connexion utilisent le proxy configuré (plus de contournement direct) -- **Support SOCKS5** — Prise en charge complète du proxy SOCKS5 pour le routage sortant -- **TLS Fingerprint Spoofing** — Empreinte digitale TLS de type navigateur via `wreq-js` pour contourner la détection des robots +- **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
-` prefix
-- **Combos gratuits uniquement** — Chaîne `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = 0 $/mois sans temps d'arrêt
-- **Crédits gratuits NVIDIA NIM** — 1 000 crédits gratuits intégrés
-- **Stratégie d'optimisation des coûts** — Stratégie de routage qui choisit automatiquement le fournisseur disponible le moins cher
+- **Free-Only Combos** — Chain `gc/gemini-3-flash → 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
🆓 4. "Je veux utiliser l'IA pour coder mais je n'ai pas d'argent"
+🆓 4. "I want to use AI for coding but I have no money"
-Tout le monde ne peut pas payer entre 20 et 200 $/mois pour des abonnements à l’IA. Les étudiants, les développeurs des pays émergents, les amateurs et les indépendants doivent avoir accès à des modèles de qualité à un coût nul. +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. -**Comment OmniRoute le résout :** +**How OmniRoute solves it:** -- **Fournisseurs gratuits intégrés** — Prise en charge native des fournisseurs 100 % gratuits : iFlow (8 modèles illimités), Qwen (3 modèles illimités), Kiro (Claude gratuit), Gemini CLI (180 000 /mois gratuits) +- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free) - **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/
-
🔒 5. "Je dois protéger ma passerelle IA contre les accès non autorisés"
+🔒 5. "I need to protect my AI gateway from unauthorized access"
-Lors de l'exposition d'une passerelle IA au réseau (LAN, VPS, Docker), toute personne possédant l'adresse peut consommer les jetons/quota du développeur. Sans protection, les API sont vulnérables aux utilisations abusives, aux injections rapides et aux abus. +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. -**Comment OmniRoute le résout :** +**How OmniRoute solves it:** -- **Gestion des clés API** — Génération, rotation et portée par fournisseur avec une page `/dashboard/api-manager` dédiée -- **Autorisations au niveau du modèle** : restreindre les clés API à des modèles spécifiques (`openai/*`, modèles génériques), avec la bascule Autoriser tout/Restreindre -- **API Endpoint Protection** – exige une clé pour `/v1/models` et bloque des fournisseurs spécifiques de la liste -- **Auth Guard + Protection CSRF** — Toutes les routes du tableau de bord protégées avec le middleware `withAuth` + les jetons CSRF -- **Rate Limiter** — Limitation du débit par IP avec fenêtres configurables -- **Filtrage IP** – Liste autorisée/liste de blocage pour le contrôle d'accès -- **Prompt Injection Guard** — Nettoyage contre les modèles d'invite malveillants -- **Chiffrement AES-256-GCM** — Informations d'identification chiffrées au repos +- **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. "Mon fournisseur est tombé en panne et j'ai perdu mon flux de codage"
+🛑 6. "My provider went down and I lost my coding flow"
-Les fournisseurs d’IA peuvent devenir instables, renvoyer des erreurs 5xx ou atteindre des limites de débit temporaires. Si un développeur dépend d'un seul fournisseur, il est interrompu. Sans disjoncteurs, des tentatives répétées peuvent faire planter l’application. +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. -**Comment OmniRoute le résout :** +**How OmniRoute solves it:** -- **Disjoncteur par fournisseur** — Ouverture/fermeture automatique avec seuils et temps de recharge configurables (Fermé/Ouvert/Semi-ouvert) -- **Exponential Backoff** — Délais progressifs entre les tentatives -- **Anti-Thundering Herd** — Protection mutex + sémaphore contre les tempêtes de nouvelles tentatives simultanées -- **Chaînes de secours combinées** — Si le fournisseur principal échoue, passe automatiquement à travers la chaîne sans intervention -- **Combo Circuit Breaker** – Désactive automatiquement les fournisseurs défaillants au sein d'une chaîne combo -- **Tableau de bord de santé** — Surveillance de la disponibilité, états des disjoncteurs, verrouillages, statistiques du cache, latence p50/p95/p99 +- **Circuit Breaker per-model** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks +- **Exponential Backoff** — Progressive retry delays +- **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 +- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain +- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
-
🔧 7. "La configuration de chaque outil d'IA est fastidieuse et répétitive"
+🔧 7. "Configuring each AI tool is tedious and repetitive"
-Les développeurs utilisent Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Chaque outil nécessite une configuration différente (point de terminaison API, clé, modèle). La reconfiguration lors du changement de fournisseur ou de modèle est une perte de temps. +Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time. -**Comment OmniRoute le résout :** +**How OmniRoute solves it:** -- **CLI Tools Dashboard** — Page dédiée avec configuration en un clic pour Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline -- **GitHub Copilot Config Generator** — Génère `chatLanguageModels.json` pour VS Code avec sélection groupée de modèles -- **Assistant d'intégration** — Configuration guidée en 4 étapes pour les nouveaux utilisateurs -- **Un point de terminaison, tous les modèles** – Configurez `http://localhost:20128/v1` une fois, accédez à plus de 36 fournisseurs +- **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 67+ providers
-
🔑 8. "Gérer les jetons OAuth de plusieurs fournisseurs est un enfer"
+🔑 8. "Managing OAuth tokens from multiple providers is hell"
-Claude Code, Codex, Gemini CLI, Copilot — tous utilisent OAuth 2.0 avec des jetons expirant. Les développeurs doivent se réauthentifier constamment, gérer `client_secret is missing`, `redirect_uri_mismatch` et les pannes sur les serveurs distants. OAuth sur LAN/VPS est particulièrement problématique. +Claude Code, Codex, Gemini CLI, 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. -**Comment OmniRoute le résout :** +**How OmniRoute solves it:** -- **Actualisation automatique des jetons** : les jetons OAuth sont actualisés en arrière-plan avant leur expiration. -- **OAuth 2.0 (PKCE) intégré** — Flux automatique pour Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow -- **Multi-Account OAuth** — Plusieurs comptes par fournisseur via l'extraction de jetons JWT/ID -- **OAuth LAN/Remote Fix** — Détection IP privée pour `redirect_uri` + mode URL manuel pour les serveurs distants -- **OAuth derrière Nginx** — Utilise `window.location.origin` pour la compatibilité du proxy inverse -- **Guide OAuth à distance** — Guide étape par étape pour les informations d'identification Google Cloud sur VPS/Docker +- **Auto Token Refresh** — OAuth tokens refresh in background before expiration +- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow +- **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. "Je ne sais pas combien je dépense ni où"
+📊 9. "I don't know how much I'm spending or where"
-Les développeurs utilisent plusieurs fournisseurs payants mais n'ont pas de vue unifiée des dépenses. Chaque fournisseur dispose de son propre tableau de bord de facturation, mais il n'existe pas de vue consolidée. Les coûts inattendus peuvent s’accumuler. +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. -**Comment OmniRoute le résout :** +**How OmniRoute solves it:** -- **Cost Analytics Dashboard** — Suivi des coûts par jeton et gestion du budget par fournisseur -- **Limites budgétaires par niveau** — Plafond de dépenses par niveau qui déclenche un repli automatique -- **Configuration de tarification par modèle** — Prix configurables par modèle -- **Statistiques d'utilisation par clé API** — Nombre de demandes et horodatage de la dernière utilisation par clé -- **Tableau de bord Analytics** — Cartes statistiques, tableau d'utilisation du modèle, tableau des fournisseurs avec taux de réussite et latence +- **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. "Je ne peux pas diagnostiquer les erreurs et les problèmes dans les appels IA"
+🐛 10. "I can't diagnose errors and problems in AI calls"
-Lorsqu'un appel échoue, le développeur ne sait pas s'il s'agit d'une limite de débit, d'un jeton expiré, d'un format incorrect ou d'une erreur du fournisseur. Journaux fragmentés sur différents terminaux. Sans observabilité, le débogage est un essai et une erreur. +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. -**Comment OmniRoute le résout :** +**How OmniRoute solves it:** -- **Tableau de bord des journaux unifiés** — 4 onglets : journaux de requêtes, journaux proxy, journaux d'audit, console -- **Console Log Viewer** — Visualiseur de style terminal en temps réel avec niveaux de code couleur, défilement automatique, recherche, filtre -- **Journaux du proxy SQLite** — Journaux persistants qui survivent aux redémarrages du serveur -- **Translator Playground** — 4 modes de débogage : Playground (traduction de format), Chat Tester (aller-retour), Test Bench (batch), Live Monitor (temps réel) -- **Demande de télémétrie** — latence p50/p95/p99 + traçage X-Request-Id -- **Journalisation basée sur des fichiers avec rotation** — L'intercepteur de console capture tout dans le journal JSON avec une rotation basée sur la taille +- **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 Proxy Logs** — Persistent logs that survive server restarts +- **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 Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation +- **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. "Le déploiement et la maintenance de la passerelle sont complexes"
+🏗️ 11. "Deploying and maintaining the gateway is complex"
-L'installation, la configuration et la maintenance d'un proxy IA dans différents environnements (local, VPS, Docker, cloud) demandent beaucoup de main-d'œuvre. Des problèmes tels que les chemins codés en dur, `EACCES` sur les répertoires, les conflits de ports et les versions multiplateformes ajoutent des frictions. +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. -**Comment OmniRoute le résout :** +**How OmniRoute solves it:** -- **Installation globale npm** — `npm install -g omniroute && omniroute` — terminée -- **Docker Multi-Platform** — AMD64 + ARM64 natif (Apple Silicon, AWS Graviton, Raspberry Pi) -- **Profils Docker Compose** — `base` (pas d'outils CLI) et `cli` (avec Claude Code, Codex, OpenClaw) -- **Electron Desktop App** — Application native pour Windows/macOS/Linux avec barre d'état système, démarrage automatique et mode hors ligne -- **Mode Split-Port** — API et tableau de bord sur des ports séparés pour des scénarios avancés (proxy inverse, réseau de conteneurs) -- **Cloud Sync** – Configurez la synchronisation entre les appareils via Cloudflare Workers -- **Sauvegardes DB** — Sauvegarde, restauration, exportation et importation automatiques de tous les paramètres +- **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
-
🌍 12. "L'interface est uniquement en anglais et mon équipe ne parle pas anglais"
+🌍 12. "The interface is English-only and my team doesn't speak English"
-Les équipes des pays non anglophones, notamment en Amérique latine, en Asie et en Europe, ont du mal à utiliser des interfaces uniquement en anglais. Les barrières linguistiques réduisent l’adoption et augmentent les erreurs de configuration. +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. -**Comment OmniRoute le résout :** +**How OmniRoute solves it:** -- **Tableau de bord i18n — 30 langues** — Plus de 500 touches traduites, dont arabe, bulgare, danois, allemand, espagnol, finnois, français, hébreu, hindi, hongrois, indonésien, italien, japonais, coréen, malais, néerlandais, norvégien, polonais, portugais (PT/BR), roumain, russe, slovaque, suédois, thaï, ukrainien, vietnamien, chinois, philippin, anglais. -- **Support RTL** — Prise en charge de droite à gauche pour l'arabe et l'hébreu -- ** README multilingues ** — 30 traductions complètes de la documentation -- **Sélecteur de langue** — Icône de globe dans l'en-tête pour une commutation en temps réel +- **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. "J'ai besoin de plus que du chat : j'ai besoin d'intégrations, d'images, d'audio"
+🔄 13. "I need more than chat — I need embeddings, images, audio"
-L'IA ne se limite pas à la réalisation de discussions. Les développeurs doivent générer des images, transcrire l'audio, créer des intégrations pour RAG, reclasser les documents et modérer le contenu. Chaque API a un point de terminaison et un format différents. +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. -**Comment OmniRoute le résout :** +**How OmniRoute solves it:** -- **Embeddings** — `/v1/embeddings` avec 6 fournisseurs et plus de 9 modèles -- **Génération d'images** — `/v1/images/generations` avec 10 fournisseurs et plus de 20 modèles (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI) -- **Texte vers vidéo** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) et SD WebUI -- **Texte en musique** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen) -- **Transcription audio** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3 -- **Text-to-Speech** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, Inworld, Cartesia, PlayHT, + fournisseurs existants -- **Modérations** — `/v1/moderations` — Contrôles de sécurité du contenu -- **Reclassement** — `/v1/rerank` — Reclassement de la pertinence du document -- **API Réponses** — Prise en charge complète de `/v1/responses` pour le Codex +- **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. "Je n'ai aucun moyen de tester et de comparer la qualité des modèles"
+🧪 14. "I have no way to test and compare quality across models"
-Les développeurs veulent savoir quel modèle convient le mieux à leur cas d'utilisation (code, traduction, raisonnement) mais la comparaison manuelle est lente. Il n’existe aucun outil d’évaluation intégré. +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. -**Comment OmniRoute le résout :** +**How OmniRoute solves it:** -- **Évaluations LLM** — Tests Golden Set avec 10 cas préchargés couvrant les salutations, les mathématiques, la géographie, la génération de code, la conformité JSON, la traduction, la démarque, le refus de sécurité -- **4 stratégies de correspondance** — `exact`, `contains`, `regex`, `custom` (fonction JS) -- **Banc de test Translator Playground** — Tests par lots avec plusieurs entrées et sorties attendues, comparaison entre fournisseurs -- **Chat Tester** — Aller-retour complet avec rendu de réponse visuelle -- **Live Monitor** — Flux en temps réel de toutes les requêtes transitant par le proxy +- **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. "J'ai besoin d'évoluer sans perdre en performances"
+📈 15. "I need to scale without losing performance"
-À mesure que le volume de demandes augmente, sans mettre en cache les mêmes questions, cela génère des coûts en double. Sans idempotence, les demandes en double gaspillent le traitement. Les limites tarifaires par fournisseur doivent être respectées. +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. -**Comment OmniRoute le résout :** +**How OmniRoute solves it:** -- **Cache sémantique** — Le cache à deux niveaux (signature + sémantique) réduit les coûts et la latence -- **Request Idempotency** — Fenêtre de déduplication de 5 s pour des requêtes identiques -- **Détection de limite de débit** — RPM par fournisseur, écart minimum et suivi simultané maximum -- **Limites de débit modifiables** — Valeurs par défaut configurables dans Paramètres → Résilience avec persistance -- **Cache de validation de clé API** — Cache à 3 niveaux pour les performances de production -- **Tableau de bord de santé avec télémétrie** — latence p50/p95/p99, statistiques de cache, disponibilité +- **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 +- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence +- **API Key Validation Cache** — 3-tier cache for production performance +- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
-
🤖 16. "Je souhaite contrôler le comportement du modèle à l'échelle mondiale"
+🤖 16. "I want to control model behavior globally"
-Les développeurs qui souhaitent que toutes les réponses soient dans une langue spécifique, avec un ton spécifique, ou qui souhaitent limiter les jetons de raisonnement. Configurer cela dans chaque outil/demande n’est pas pratique. +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. -**Comment OmniRoute le résout :** +**How OmniRoute solves it:** -- **Injection d'invite système** — Invite globale appliquée à toutes les requêtes -- **Thinking Budget Validation** — Contrôle d'allocation de jetons de raisonnement par requête (passthrough, automatique, personnalisé, adaptatif) -- **6 Stratégies de routage** – Stratégies globales qui déterminent la façon dont les demandes sont distribuées -- **Wildcard Router** — Les modèles `provider/*` sont acheminés dynamiquement vers n'importe quel fournisseur. -- **Combo Enable/Disable Toggle** — Basculez les combos directement depuis le tableau de bord -- **Provider Toggle** — Activer/désactiver toutes les connexions pour un fournisseur en un seul clic -- **Fournisseurs bloqués** — Exclure des fournisseurs spécifiques de la liste `/v1/models` +- **System Prompt Injection** — Global prompt applied to all requests +- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive) +- **6 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 +- **Provider Toggle** — Enable/disable all connections for a provider with one click +- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
-
🧰 17. "J'ai besoin d'outils MCP en tant que fonctionnalités de produit de première classe"
+🧰 17. "I need MCP tools as first-class product capabilities"
-De nombreuses passerelles IA exposent MCP uniquement en tant que détail d'implémentation caché. Les équipes ont besoin d’une couche opérationnelle visible et gérable. +Many AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer. -**Comment OmniRoute le résout :** +**How OmniRoute solves it:** -- MCP apparaît dans l'onglet de navigation du tableau de bord et de protocole de point de terminaison -- Page de gestion MCP dédiée avec processus, outils, portées et audit -- Démarrage rapide intégré pour `omniroute --mcp` et intégration du client +- 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. "J'ai besoin d'une orchestration A2A avec des chemins de tâches de synchronisation + flux"
+🧠 18. "I need A2A orchestration with sync + stream task paths"
-Les flux de travail des agents nécessitent à la fois des réponses directes et une exécution en continu de longue durée avec contrôle du cycle de vie. +Agent workflows need both direct replies and long-running streamed execution with lifecycle control. -**Comment OmniRoute le résout :** +**How OmniRoute solves it:** -- Point de terminaison A2A JSON-RPC (`POST /a2a`) avec `message/send` et `message/stream` -- Streaming SSE avec propagation de l'état terminal -- API de cycle de vie des tâches pour `tasks/get` et `tasks/cancel` +- 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. "J'ai besoin d'un véritable état de santé du processus MCP, et non d'un état deviné"
+🛰️ 19. "I need real MCP process health, not guessed status"
-Les équipes opérationnelles doivent savoir si MCP est réellement actif, et pas seulement si une API est accessible. +Operational teams need to know if MCP is actually alive, not just whether an API is reachable. -**Comment OmniRoute le résout :** +**How OmniRoute solves it:** -- Fichier de battement de cœur d'exécution avec PID, horodatages, transport, nombre d'outils et mode de portée -- API de statut MCP combinant battement de coeur + activité récente -- Cartes d'état de l'interface utilisateur pour la fraîcheur des processus/disponibilité/battement de cœur +- 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. "J'ai besoin d'une exécution vérifiable de l'outil MCP"
+📋 20. "I need auditable MCP tool execution"
-Lorsque les outils modifient la configuration ou déclenchent des actions opérationnelles, les équipes ont besoin d'une traçabilité médico-légale. +When tools mutate config or trigger ops actions, teams need forensic traceability. -**Comment OmniRoute le résout :** +**How OmniRoute solves it:** -- Journalisation d'audit basée sur SQLite pour les appels d'outils MCP -- Filtres par outil, succès/échec, clé API et pagination -- Tableau d'audit du tableau de bord + points de terminaison de statistiques pour l'automatisation +- 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. "J'ai besoin d'autorisations MCP limitées par intégration"
+🔐 21. "I need scoped MCP permissions per integration"
-Différents clients doivent avoir le moindre privilège d’accès aux catégories d’outils. +Different clients should have least-privilege access to tool categories. -**Comment OmniRoute le résout :** +**How OmniRoute solves it:** -- 9 étendues MCP granulaires pour un accès contrôlé aux outils -- Application de la portée et visibilité dans l'interface utilisateur de gestion MCP -- Posture par défaut sûre pour les outils opérationnels +- 9 granular MCP scopes for controlled tool access +- Scope enforcement and visibility in MCP management UI +- Safe default posture for operational tooling
-
⚙️ 22. "J'ai besoin de contrôles opérationnels sans redéploiement"
+⚙️ 22. "I need operational controls without redeploying"
-Les équipes ont besoin de changements d'exécution rapides lors d'incidents ou d'événements de coûts. +Teams need quick runtime changes during incidents or cost events. -**Comment OmniRoute le résout :** +**How OmniRoute solves it:** -- Activer le combo de commutation directement depuis le tableau de bord MCP -- Appliquer des profils de résilience à partir de packs de politiques prédéfinis -- Réinitialiser l'état du disjoncteur à partir du même panneau de commande +- Switch combo activation directly from MCP dashboard +- Apply resilience profiles from pre-defined policy packs +- Reset circuit breaker state from the same operations panel
-
🔄 23. "J'ai besoin d'une visibilité et d'une annulation en direct du cycle de vie des tâches A2A"
+🔄 23. "I need live A2A task lifecycle visibility and cancellation"
-Sans visibilité sur le cycle de vie, les incidents de tâches deviennent difficiles à trier. +Without lifecycle visibility, task incidents become hard to triage. -**Comment OmniRoute le résout :** +**How OmniRoute solves it:** -- Liste des tâches/filtrage par état/compétence avec pagination -- Analyse approfondie des métadonnées, des événements et des artefacts des tâches -- Point de terminaison d'annulation de tâche et action de l'interface utilisateur avec confirmation +- 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. "J'ai besoin de métriques de flux actif pour la charge A2A"
+🌊 24. "I need active stream metrics for A2A load"
-Les flux de travail de streaming nécessitent une vision opérationnelle de la concurrence et des connexions en direct. +Streaming workflows require operational insight into concurrency and live connections. -**Comment OmniRoute le résout :** +**How OmniRoute solves it:** -- Compteurs de flux actifs intégrés au statut A2A -- Horodatage de la dernière tâche et nombre par état -- Cartes de tableau de bord A2A pour la surveillance des opérations en temps réel +- Active stream counters integrated into A2A status +- Last task timestamp and per-state counts +- A2A dashboard cards for real-time ops monitoring
-
🪪 25. "J'ai besoin d'une découverte d'agent standard pour les clients"
+🪪 25. "I need standard agent discovery for clients"
-Les clients et orchestrateurs externes ont besoin de métadonnées lisibles par machine pour l'intégration. +External clients and orchestrators need machine-readable metadata for onboarding. -**Comment OmniRoute le résout :** +**How OmniRoute solves it:** -- Carte d'agent exposée à `/.well-known/agent.json` -- Capacités et compétences affichées dans l'interface utilisateur de gestion -- L'API de statut A2A inclut des métadonnées de découverte pour l'automatisation +- Agent Card exposed at `/.well-known/agent.json` +- Capabilities and skills shown in management UI +- A2A status API includes discovery metadata for automation
-
🧭 26. "J'ai besoin de la possibilité de découvrir le protocole dans le produit UX"
+🧭 26. "I need protocol discoverability in the product UX"
-Si les utilisateurs ne peuvent pas découvrir les surfaces de protocole, l’adoption et la qualité du support chutent. +If users cannot discover protocol surfaces, adoption and support quality drop. -**Comment OmniRoute le résout :** +**How OmniRoute solves it:** -- Entrées de la barre latérale pour MCP et A2A -- Onglet Protocoles de la page du point de terminaison avec démarrage rapide et état -- Liens depuis l'aperçu vers les tableaux de bord de gestion dédiés +- 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. "J'ai besoin d'une validation de protocole de bout en bout avec de vrais clients"
+🧪 27. "I need end-to-end protocol validation with real clients"
-Les tests simulés ne suffisent pas pour valider la compatibilité des protocoles avant la publication. +Mock tests are not enough to validate protocol compatibility before release. -**Comment OmniRoute le résout :** +**How OmniRoute solves it:** -- Suite E2E qui démarre l'application et utilise un véritable transport client MCP SDK -- Tests client A2A pour les flux de découverte, d'envoi, de streaming, d'obtention et d'annulation -- Vérifier les assertions par rapport aux API d'audit MCP et de tâches A2A +- 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. "J'ai besoin d'une observabilité unifiée sur toutes les interfaces"
+📡 28. "I need unified observability across all interfaces"
-Le fractionnement de l'observabilité par protocole crée des angles morts et un MTTR plus long. +Splitting observability by protocol creates blind spots and longer MTTR. -**Comment OmniRoute le résout :** +**How OmniRoute solves it:** -- Tableaux de bord/journaux/analyses unifiés dans un seul produit -- Santé + audit + télémétrie des demandes sur les couches OpenAI, MCP et A2A -- API opérationnelles pour le statut et l'automatisation +- Unified dashboards/logs/analytics in one product +- Health + audit + request telemetry across OpenAI, MCP, and A2A layers +- Operational APIs for status and automation
-
💼 29. "J'ai besoin d'un environnement d'exécution pour l'orchestration proxy + outils + agent"
+💼 29. "I need one runtime for proxy + tools + agent orchestration"
-L’exécution de nombreux services distincts augmente les coûts opérationnels et les modes de défaillance. +Running many separate services increases operational cost and failure modes. -**Comment OmniRoute le résout :** +**How OmniRoute solves it:** -- Proxy compatible OpenAI, serveur MCP et serveur A2A dans une seule pile -- Authentification partagée, résilience, stockage de données et observabilité -- Modèle de politique cohérent sur toutes les surfaces d'interaction +- 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
-
-### Exemples de playbooks (cas d'utilisation intégrés)
+### Example Playbooks (Integrated Use Cases)
-**Playbook A : Maximisez l'abonnement payant + sauvegarde bon marché**
+**Playbook A: Maximize paid subscription + cheap backup**
```txt
Combo: "maximize-claude"
@@ -683,7 +694,7 @@ Monthly cost: $20 + small backup spend
Outcome: higher quality, near-zero interruption
```
-**Playbook B : pile de codage à coût nul**
+**Playbook B: Zero-cost coding stack**
```txt
Combo: "free-forever"
@@ -695,7 +706,7 @@ Monthly cost: $0
Outcome: stable free coding workflow
```
-**Playbook C : chaîne de secours toujours active 24h/24 et 7j/7**
+**Playbook C: 24/7 always-on fallback chain**
```txt
Combo: "always-on"
@@ -708,65 +719,132 @@ Combo: "always-on"
Outcome: deep fallback depth for deadline-critical workloads
```
-**Playbook D : Opérations d'agent avec MCP + A2A**
+**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/mcp and /dashboard/a2a
-4) Control incidents with resilience profile + task cancellation
+3) Observe via /dashboard/endpoint (MCP and A2A tabs)
+4) Toggle services via inline status controls
```
---
-## ⚡ Démarrage rapide
+## 🆓 Start Free — Zero Configuration Cost
-**1. Installer globalement :**
+> 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 **iFlow** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |
+| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |
+| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |
+| 5 | `/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).
+
+## Démarrage Rapide
+
+### 1) Install and run
```bash
npm install -g omniroute
omniroute
```
-🎉 Le tableau de bord s'ouvre sur `http://localhost:20128`
+> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:
+>
+> ```bash
+> pnpm install -g omniroute
+> pnpm approve-builds -g # Select all packages → approve
+> omniroute
+> ```
-| Commande | Description |
-| ----------------------- | ------------------------------------------- |
-| `omniroute` | Démarrer le serveur (port par défaut 20128) |
-| `omniroute --port 3000` | Utiliser un port personnalisé |
-| `omniroute --no-open` | Ne pas ouvrir le navigateur automatiquement |
-| `omniroute --help` | Afficher l'aide |
+Dashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.
-**2. Connecter un fournisseur GRATUIT :**
+| 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 |
-Tableau de bord → Fournisseurs → Connecter **Claude Code** ou **Antigravity** → Connexion OAuth → Terminé !
+Optional split-port mode:
-**3. Utiliser dans votre outil CLI :**
-
-```
-Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Paramètres :
- Endpoint : http://localhost:20128/v1
- API Key : [copier depuis le tableau de bord]
- Model : if/kimi-k2-thinking
+```bash
+PORT=20128 DASHBOARD_PORT=20129 omniroute
+# API: http://localhost:20128/v1
+# Dashboard: http://localhost:20129
```
-**C'est tout !** Commencez à coder avec des modèles IA GRATUITS.
+### 2) Connect providers and create your API key
-**Alternative — exécuter depuis le code source :**
+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
+
+```txt
+Base URL: http://localhost:20128/v1
+API Key: [copy from Endpoint page]
+Model: if/kimi-k2-thinking (or any provider/model prefix)
+```
+
+Works with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.
+
+### 4) Enable and validate protocols (v2.0)
+
+**MCP (for tool-driven operations):**
+
+```bash
+omniroute --mcp
+```
+
+Then connect your MCP client over `stdio` and test tools like:
+
+- `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 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
+PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev
```
---
## 🐳 Docker
-OmniRoute est disponible en tant qu'image Docker publique sur [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
+OmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
-**Démarrage rapide :**
+**Quick run:**
```bash
docker run -d \
@@ -777,10 +855,10 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Avec fichier d'environnement :**
+**With environment file:**
```bash
-# Copier et modifier le .env d'abord
+# Copy and edit .env first
cp .env.example .env
docker run -d \
@@ -792,297 +870,627 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Avec Docker Compose :**
+**Using Docker Compose:**
```bash
-# Profil de base (sans outils CLI)
+# Base profile (no CLI tools)
docker compose --profile base up -d
-# Profil CLI (Claude Code, Codex, OpenClaw intégrés)
+# CLI profile (Claude Code, Codex, OpenClaw built-in)
docker compose --profile cli up -d
```
-| Image | Tag | Taille | Description |
-| ------------------------ | -------- | ------ | ----------------------- |
-| `diegosouzapw/omniroute` | `latest` | ~250MB | Dernière version stable |
-| `diegosouzapw/omniroute` | `1.0.6` | ~250MB | Version actuelle |
+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.
+- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.
+- 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` | `1.0.3` | ~250MB | Current version |
---
----
+## 🖥️ Desktop App — Offline & Always-On
-## 🖥️
+> 🆕 **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.
-> 🆕 **NOUVEAU !** OmniRoute est maintenant disponible en tant qu'**application de bureau native** pour Windows, macOS et Linux.
+Run OmniRoute as a standalone desktop app — no terminal, no browser, no internet required for local models. The Electron-based app includes:
-Exécutez OmniRoute en tant qu'application de bureau autonome — sans terminal, sans navigateur, sans internet requis pour les modèles locaux.
+- 🖥️ **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
-- 🖥️ **Fenêtre Native** — Fenêtre dédiée avec intégration dans la barre d'état système
-- 🔄 **Démarrage Automatique** — Lancez OmniRoute à la connexion système
-- 🔔 **Notifications Natives** — Alertes pour l'épuisement de quota ou les problèmes
-- ⚡ **Installation en Un Clic** — NSIS (Windows), DMG (macOS), AppImage (Linux)
-- 🌐 **Mode Hors Ligne** — Fonctionne entièrement hors ligne avec serveur intégré
+### Démarrage Rapide
```bash
-npm run electron:dev # Mode développement
-npm run electron:build # Plateforme actuelle
+# 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)
+npm run electron:build:mac # macOS (.dmg) — x64 & arm64
npm run electron:build:linux # Linux (.AppImage)
```
-📖 Documentation complète : [`electron/README.md`](electron/README.md)
+### 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)
---
-## 💰 Aperçu des tarifs
+## 💰 Pricing at a Glance
-| Tier | Fournisseur | Coût | Réinitialisation | Idéal pour |
-| ----------------- | ----------------- | -------------------------- | ------------------- | ----------------------------- |
-| **💳 ABONNEMENT** | Claude Code (Pro) | 20 $/mois | 5h + hebdomadaire | Déjà abonné |
-| | Codex (Plus/Pro) | 20-200 $/mois | 5h + hebdomadaire | Utilisateurs OpenAI |
-| | Gemini CLI | **GRATUIT** | 180K/mois + 1K/jour | Tout le monde ! |
-| | GitHub Copilot | 10-19 $/mois | Mensuel | Utilisateurs GitHub |
-| **🔑 CLÉ API** | NVIDIA NIM | **GRATUIT** (1000 crédits) | Unique | Tests gratuits |
-| | DeepSeek | À l'usage | Aucune | Meilleur rapport qualité-prix |
-| | Groq | Niveau gratuit + payant | Limité | Inférence ultra-rapide |
-| | xAI (Grok) | À l'usage | Aucune | Modèles Grok |
-| | Mistral | Niveau gratuit + payant | Limité | IA européenne |
-| | OpenRouter | À l'usage | Aucune | 100+ modèles |
-| **💰 ÉCONOMIQUE** | GLM-4.7 | 0,6 $/1M | Quotidien 10h | Backup économique |
-| | MiniMax M2.1 | 0,2 $/1M | Rotatif 5h | Option la moins chère |
-| | Kimi K2 | 9 $/mois fixe | 10M tokens/mois | Coût prévisible |
-| **🆓 GRATUIT** | iFlow | 0 $ | Illimité | 8 modèles gratuits |
-| | Qwen | 0 $ | Illimité | 3 modèles gratuits |
-| | Kiro | 0 $ | Illimité | Claude gratuit |
+| 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 |
+| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |
+| | 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** | iFlow | **$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 |
-**💡 Conseil Pro :** Commencez avec Gemini CLI (180K gratuits/mois) + iFlow (illimité gratuit) = 0 $ de coût !
+> 🆕 **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
+iFlow (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.
---
-## 💡 Fonctionnalités principales
+---
-### 🧠 Routage & Intelligence
+## 🆓 Free Models — What You Actually Get
-| Fonctionnalité | Ce qu'elle fait |
-| ------------------------------------- | ------------------------------------------------------------------------------- |
-| 🎯 **Fallback intelligent 4 niveaux** | Auto-routage : Abonnement → Clé API → Économique → Gratuit |
-| 📊 **Suivi des quotas en temps réel** | Comptage de tokens en direct + compte à rebours de réinitialisation |
-| 🔄 **Traduction de format** | OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro transparent |
-| 👥 **Support multi-comptes** | Plusieurs comptes par fournisseur avec sélection intelligente |
-| 🔄 **Renouvellement auto des tokens** | Les tokens OAuth se renouvellent automatiquement avec retry |
-| 🎨 **Combos personnalisés** | 6 stratégies : fill-first, round-robin, p2c, random, least-used, cost-optimized |
-| 🧩 **Modèles personnalisés** | Ajoutez n'importe quel ID de modèle à n'importe quel fournisseur |
-| 🌐 **Routeur wildcard** | Routez les patterns `provider/*` vers n'importe quel fournisseur dynamiquement |
-| 🧠 **Budget de raisonnement** | Modes passthrough, auto, custom et adaptive pour les modèles de raisonnement |
-| 🔀 **Model Aliases** | Auto-forward deprecated model IDs to current replacements (built-in + custom) |
-| ⚡ **Background Degradation** | Auto-route background tasks (titles, summaries) to cheaper models |
-| 💬 **Injection System Prompt** | System prompt global appliqué à toutes les requêtes |
-| 📄 **API Responses** | Support complet de l'API Responses d'OpenAI (`/v1/responses`) pour Codex |
+> 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.
-### 🎵 APIs multi-modales
+### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)
-| Fonctionnalité | Ce qu'elle fait |
+| 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 |
+
+### 🟢 IFLOW MODELS (Free OAuth — No Credit Card)
+
+| 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 |
+
+### 🟡 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) |
+
+### 🟣 GEMINI CLI (Google OAuth)
+
+| Model | Prefix | Limit | Rate Limit |
+| ------------------------ | ------ | --------------------------- | ------------- |
+| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |
+| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |
+
+### ⚫ 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
+> iFlow (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 v2.0 is built as an operational platform, not just a relay proxy.
+
+### 🆕 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 Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |
+| 🤖 **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 (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) |
+| 🤝 **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** | 9 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 combo, apply resilience profiles, reset breakers from one control surface |
+
+### 🧠 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** | 6 balancing strategies + fallback chain control |
+| 🌐 **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) |
+| 💬 **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 |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 🖼️ **Génération d'images** | `/v1/images/generations` — 4 fournisseurs, 9+ modèles |
-| 📐 **Embeddings** | `/v1/embeddings` — 6 fournisseurs, 9+ modèles |
-| 🎤 **Transcription audio** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |
-| 🔊 **Texte vers parole** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) |
-| 🛡️ **Modérations** | `/v1/moderations` — vérifications de sécurité |
-| 🔀 **Reranking** | `/v1/rerank` — reclassement de pertinence des documents |
+| 🖼️ **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 |
-### 🛡️ Résilience & Sécurité
+### 🛡️ Resilience, Security & Governance
-| Fonctionnalité | Ce qu'elle fait |
-| ------------------------------- | -------------------------------------------------------------------------------------- |
-| 🔌 **Circuit Breaker** | Ouverture/fermeture auto par fournisseur avec seuils configurables |
-| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |
-| 🛡️ **Anti-Thundering Herd** | Mutex + sémaphore de rate-limit pour les fournisseurs avec clé API |
-| 🧠 **Cache sémantique** | Cache à deux niveaux (signature + sémantique) réduit coût et latence |
-| ⚡ **Idempotence des requêtes** | Fenêtre de dédup 5s pour les requêtes dupliquées |
-| 🔒 **Spoofing TLS Fingerprint** | Contournement de détection de bot via wreq-js |
-| 🔏 **CLI Fingerprint Matching** | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP** |
-| 🌐 **Filtrage IP** | Allowlist/blocklist pour le contrôle d'accès API |
-| 📊 **Rate limits éditables** | RPM configurable, intervalle minimum, concurrence max |
-| 💾 **Rate Limit Persistence** | Learned limits survive restarts via SQLite with 60s debounce + 24h staleness |
-| 🔄 **Token Refresh Resilience** | Per-provider circuit breaker (5 fails→30min) + 30s timeout per attempt |
+| Feature | What It Does |
+| ----------------------------------- | -------------------------------------------------------------------------------------- |
+| 🔌 **Circuit Breakers** | Per-model trip/recover with threshold controls |
+| 🎯 **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 |
+| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |
+| 🔑 **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 |
-### 📊 Observabilité & Analytique
+### 📊 Observability & Analytics
-| Fonctionnalité | Ce qu'elle fait |
-| --------------------------------- | ------------------------------------------------------------------------- |
-| 📝 **Logs de requêtes** | Mode debug avec logs complets requête/réponse |
-| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |
-| 💾 **Logs SQLite** | Logs proxy persistants survivant aux redémarrages |
-| 📊 **Tableau de bord analytique** | Recharts : cartes de stats, graphique d'utilisation, tableau fournisseurs |
-| 📈 **Suivi de progression** | Événements SSE de progression opt-in pour le streaming |
-| 🧪 **Évaluations LLM** | Tests avec golden set et 4 stratégies de correspondance |
-| 🔍 **Télémétrie des requêtes** | Agrégation de latence p50/p95/p99 + traçage X-Request-Id |
-| 📋 **Logs + Quotas** | Pages dédiées pour navigation des logs et suivi des quotas |
-| 🏥 **Tableau de bord santé** | Uptime, états circuit breaker, lockouts, stats cache |
-| 💰 **Suivi des coûts** | Gestion de budget + configuration des prix par modèle |
+| Feature | What It Does |
+| -------------------------------- | ----------------------------------------------------- |
+| 📝 **Request + Proxy Logging** | Full request/response and proxy logging |
+| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |
+| 📋 **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 |
-### ☁️ Déploiement & Synchronisation
+### ☁️ Deployment & Platform
-| Fonctionnalité | Ce qu'elle fait |
-| --------------------------------- | ------------------------------------------------------------------------------- |
-| 💾 **Cloud Sync** | Synchroniser les paramètres entre appareils via Cloudflare Workers |
-| 🌐 **Déployer partout** | Localhost, VPS, Docker, Cloudflare Workers |
-| 🔑 **Gestion des clés API** | Générer, faire tourner et limiter les clés API par fournisseur |
-| 🧙 **Assistant de configuration** | Setup guidé en 4 étapes pour les nouveaux utilisateurs |
-| 🔧 **Tableau de bord CLI Tools** | Configuration en un clic pour Claude, Codex, Cline, OpenClaw, Kilo, Antigravity |
-| 🔄 **Sauvegardes DB** | Sauvegarde et restauration automatiques de tous les paramètres |
+| Feature | What It Does |
+| ----------------------------- | --------------------------------------------------------- |
+| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |
+| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |
+| 💾 **Cloud Sync** | Configuration sync via cloud worker |
+| 🔄 **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 |
+
+### Feature Deep Dive
+
+#### Smart fallback with practical cost control
+
+```txt
+Combo: "my-coding-stack"
+ 1. cc/claude-opus-4-6
+ 2. nvidia/llama-3.3-70b
+ 3. glm/glm-4.7
+ 4. if/kimi-k2-thinking
+```
+
+When quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.
+
+#### 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)
+
+#### 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)
🚀 30. "Je dois expédier des flux de travail agentiques sans prolifération de codes adhésifs"
+🚀 30. "I need to ship agentic workflows without glue-code sprawl"
-Les équipes perdent de la vitesse lors de l’assemblage de plusieurs services et scripts ad hoc. +Teams lose velocity when stitching multiple ad-hoc services and scripts. -**Comment OmniRoute le résout :** +**How OmniRoute solves it:** -- Stratégie de point de terminaison unifiée pour les clients et les agents -- Interfaces utilisateur de gestion de protocole intégrées et chemins de validation de fumée -- Bases prêtes pour la production (sécurité, journalisation, résilience, sauvegarde) +- Unified endpoint strategy for clients and agents +- Built-in protocol management UIs and smoke validation paths +- Production-ready foundations (security, logging, resilience, backup)
-
-## 🧪 Évaluations (Evals)
+📖 Détails des fonctionnalités
+🧩 MCP Setup (Model Context Protocol)
-### 🎯 Fallback intelligent 4 niveaux +Start MCP transport in stdio mode: -Créez des combos avec fallback automatique : - -``` -Combo : "my-coding-stack" - 1. cc/claude-opus-4-6 (votre abonnement) - 2. nvidia/llama-3.3-70b (API NVIDIA gratuite) - 3. glm/glm-4.7 (backup économique, $0.6/1M) - 4. if/kimi-k2-thinking (fallback gratuit) - -→ Bascule automatiquement lorsque le quota est épuisé ou en cas d'erreurs +```bash +omniroute --mcp ``` -### 📊 Suivi des quotas en temps réel +Recommended validation flow: -- Consommation de tokens par fournisseur -- Compte à rebours de réinitialisation (5 heures, quotidien, hebdomadaire) -- Estimation des coûts pour les niveaux payants -- Rapports de dépenses mensuels +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. -### 🔄 Traduction de format +Useful APIs for automation: -Traduction transparente entre les formats : - -- **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **OpenAI Responses** -- Votre CLI envoie le format OpenAI → OmniRoute traduit → Le fournisseur reçoit le format natif -- Fonctionne avec tout outil supportant les endpoints OpenAI personnalisés - -### 👥 Support multi-comptes - -- Ajouter plusieurs comptes par fournisseur -- Round-robin automatique ou routage par priorité -- Basculement vers le compte suivant lorsqu'un quota est atteint - -### 🔄 Renouvellement automatique des tokens - -- Les tokens OAuth se renouvellent automatiquement avant expiration -- Pas de réauthentification manuelle nécessaire -- Expérience transparente sur tous les fournisseurs - -### 🎨 Combos personnalisés - -- Créer des combinaisons de modèles illimitées -- 6 stratégies : fill-first, round-robin, power-of-two-choices, random, least-used, cost-optimized -- Partager les combos entre appareils avec Cloud Sync - -### 🏥 Tableau de bord santé - -- Statut du système (uptime, version, utilisation mémoire) -- États des circuit breakers par fournisseur (Closed/Open/Half-Open) -- Statut des rate limits et lockouts actifs -- Statistiques du cache de signatures -- Télémétrie de latence (p50/p95/p99) + cache de prompt -- Réinitialisation de la santé en un clic - -### 🔧 Playground du traducteur - -- Déboguer, tester et visualiser les traductions de format d'API -- Envoyer des requêtes et voir comment OmniRoute traduit entre les formats des fournisseurs -- Inestimable pour résoudre les problèmes d'intégration - -### 💾 Cloud Sync - -- Synchroniser fournisseurs, combos et paramètres entre appareils -- Synchronisation en arrière-plan automatique -- Stockage chiffré sécurisé +- `GET /api/mcp/status` +- `GET /api/mcp/tools` +- `GET /api/mcp/audit` +- `GET /api/mcp/audit/stats`
+
🤝 A2A Setup (Agent2Agent)
-OmniRoute inclut un framework d'évaluation intégré pour tester la qualité des réponses LLM contre un golden set. Accès via **Analytics → Evals** dans le tableau de bord. +Discover the agent: -### Set intégré +```bash +curl http://localhost:20128/.well-known/agent.json +``` -Le « OmniRoute Golden Set » préchargé contient 10 cas de test : +Send a task: -- Salutations, mathématiques, géographie, génération de code -- Conformité format JSON, traduction, markdown -- Rejet de sécurité (contenu nocif), comptage, logique booléenne +```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."}]}}' +``` -### Stratégies d'évaluation +Manage lifecycle: -| Stratégie | Description | Exemple | -| ---------- | -------------------------------------------------------------- | -------------------------------- | -| `exact` | La sortie doit correspondre exactement | `"4"` | -| `contains` | La sortie doit contenir la sous-chaîne (insensible à la casse) | `"Paris"` | -| `regex` | La sortie doit correspondre au motif regex | `"1.*2.*3"` | -| `custom` | Fonction JS personnalisée retourne true/false | `(output) => output.length > 10` | +- `GET /api/a2a/status` +- `GET /api/a2a/tasks` +- `GET /api/a2a/tasks/:id` +- `POST /api/a2a/tasks/:id/cancel` ---- +Operational UI: -## 📖 Guide de configuration +- `/dashboard/a2a` for task/state/stream observability and smoke actions + +
-
+
+💳 Fournisseurs par abonnement
+🧪 End-to-end protocol validation
+ +Validate both protocols with real clients: + +```bash +npm run test:protocols:e2e +``` + +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) ```bash -Tableau de bord → Fournisseurs → Connecter Claude Code -→ Connexion OAuth → Renouvellement auto des tokens -→ Suivi de quota 5h + hebdomadaire +Dashboard → Providers → Connect Claude Code +→ OAuth login → Auto token refresh +→ 5-hour + weekly quota tracking -Modèles : +Models: cc/claude-opus-4-6 cc/claude-sonnet-4-5-20250929 cc/claude-haiku-4-5-20251001 ``` -**Conseil Pro :** Utilisez Opus pour les tâches complexes, Sonnet pour la vitesse. OmniRoute suit les quotas par modèle ! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! ### OpenAI Codex (Plus/Pro) ```bash -Tableau de bord → Fournisseurs → Connecter Codex -→ Connexion OAuth (port 1455) -→ Reset 5h + hebdomadaire +Dashboard → Providers → Connect Codex +→ OAuth login (port 1455) +→ 5-hour + weekly reset -Modèles : +Models: cx/gpt-5.2-codex cx/gpt-5.1-codex-max ``` -### Gemini CLI (GRATUIT 180K/mois !) +#### 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). + +### Gemini CLI (FREE 180K/month!) ```bash -Tableau de bord → Fournisseurs → Connecter Gemini CLI +Dashboard → Providers → Connect Gemini CLI → Google OAuth -→ 180K completions/mois + 1K/jour +→ 180K completions/month + 1K/day -Modèles : +Models: gc/gemini-3-flash-preview gc/gemini-2.5-pro ``` -**Meilleure valeur :** Niveau gratuit énorme ! Utilisez avant les niveaux payants. +**Best Value:** Huge free tier! Use this before paid tiers. ### GitHub Copilot ```bash -Tableau de bord → Fournisseurs → Connecter GitHub +Dashboard → Providers → Connect GitHub → OAuth via GitHub -→ Reset mensuel (1er du mois) +→ Monthly reset (1st of month) -Modèles : +Models: gh/gpt-5 gh/claude-4.5-sonnet gh/gemini-3-pro @@ -1091,95 +1499,95 @@ Modèles :
-
🔑 Fournisseurs par clé API
+🔑 API Key Providers
-### NVIDIA NIM (GRATUIT 1000 crédits !) +### NVIDIA NIM (FREE developer access — 70+ models) -1. S'inscrire : [build.nvidia.com](https://build.nvidia.com) -2. Obtenir une clé API gratuite (1000 crédits d'inférence inclus) -3. Tableau de bord → Ajouter fournisseur → NVIDIA NIM : - - API Key : `nvapi-your-key` +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` -**Modèles :** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct` et 50+ autres +**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more -**Conseil Pro :** API compatible OpenAI — fonctionne parfaitement avec la traduction de format d'OmniRoute ! +**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation! ### DeepSeek -1. S'inscrire : [platform.deepseek.com](https://platform.deepseek.com) -2. Obtenir une clé API -3. Tableau de bord → Ajouter fournisseur → DeepSeek +1. Sign up: [platform.deepseek.com](https://platform.deepseek.com) +2. Get API key +3. Dashboard → Add Provider → DeepSeek -**Modèles :** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` +**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` -### Groq (Niveau gratuit disponible !) +### Groq (Free Tier Available!) -1. S'inscrire : [console.groq.com](https://console.groq.com) -2. Obtenir une clé API (niveau gratuit inclus) -3. Tableau de bord → Ajouter fournisseur → Groq +1. Sign up: [console.groq.com](https://console.groq.com) +2. Get API key (free tier included) +3. Dashboard → Add Provider → Groq -**Modèles :** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` +**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` -**Conseil Pro :** Inférence ultra-rapide — idéal pour le codage en temps réel ! +**Pro Tip:** Ultra-fast inference — best for real-time coding! -### OpenRouter (100+ modèles) +### OpenRouter (100+ Models) -1. S'inscrire : [openrouter.ai](https://openrouter.ai) -2. Obtenir une clé API -3. Tableau de bord → Ajouter fournisseur → OpenRouter +1. Sign up: [openrouter.ai](https://openrouter.ai) +2. Get API key +3. Dashboard → Add Provider → OpenRouter -**Modèles :** Accès à 100+ modèles de tous les grands fournisseurs via une seule clé API. +**Models:** Access 100+ models from all major providers through a single API key.
-
💰 Fournisseurs économiques (Backup)
+💰 Cheap Providers (Backup)
-### GLM-4.7 (Reset quotidien, $0.6/1M) +### GLM-4.7 (Daily reset, $0.6/1M) -1. S'inscrire : [Zhipu AI](https://open.bigmodel.cn/) -2. Obtenir une clé API du Coding Plan -3. Tableau de bord → Ajouter clé API : - - Fournisseur : `glm` - - API Key : `your-key` +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` -**Utilisez :** `glm/glm-4.7` +**Use:** `glm/glm-4.7` -**Conseil Pro :** Le Coding Plan offre 3× le quota à 1/7 du coût ! Reset quotidien à 10h. +**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -### MiniMax M2.1 (Reset 5h, $0.20/1M) +### MiniMax M2.1 (5h reset, $0.20/1M) -1. S'inscrire : [MiniMax](https://www.minimax.io/) -2. Obtenir une clé API -3. Tableau de bord → Ajouter clé API +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key +3. Dashboard → Add API Key -**Utilisez :** `minimax/MiniMax-M2.1` +**Use:** `minimax/MiniMax-M2.1` -**Conseil Pro :** L'option la moins chère pour le contexte long (1M tokens) ! +**Pro Tip:** Cheapest option for long context (1M tokens)! -### Kimi K2 (9 $/mois fixe) +### Kimi K2 ($9/month flat) -1. S'abonner : [Moonshot AI](https://platform.moonshot.ai/) -2. Obtenir une clé API -3. Tableau de bord → Ajouter clé API +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key +3. Dashboard → Add API Key -**Utilisez :** `kimi/kimi-latest` +**Use:** `kimi/kimi-latest` -**Conseil Pro :** 9 $/mois fixe pour 10M tokens = 0,90 $/1M de coût effectif ! +**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
-
🆓 Fournisseurs GRATUITS (Backup d'urgence)
+🆓 FREE Providers (Emergency Backup)
-### iFlow (8 modèles GRATUITS) +### iFlow (5 FREE models via OAuth) ```bash -Tableau de bord → Connecter iFlow -→ Connexion OAuth iFlow -→ Utilisation illimitée +Dashboard → Connect iFlow +→ iFlow OAuth login +→ Unlimited usage -Modèles : +Models: if/kimi-k2-thinking if/qwen3-coder-plus if/glm-4.7 @@ -1187,26 +1595,26 @@ Modèles : if/deepseek-r1 ``` -### Qwen (3 modèles GRATUITS) +### Qwen (4 FREE models via Device Code) ```bash -Tableau de bord → Connecter Qwen -→ Autorisation par code d'appareil -→ Utilisation illimitée +Dashboard → Connect Qwen +→ Device code authorization +→ Unlimited usage -Modèles : +Models: qw/qwen3-coder-plus qw/qwen3-coder-flash ``` -### Kiro (Claude GRATUIT) +### Kiro (Claude FREE) ```bash -Tableau de bord → Connecter Kiro -→ AWS Builder ID ou Google/GitHub -→ Utilisation illimitée +Dashboard → Connect Kiro +→ AWS Builder ID or Google/GitHub +→ Unlimited usage -Modèles : +Models: kr/claude-sonnet-4.5 kr/claude-haiku-4.5 ``` @@ -1214,51 +1622,51 @@ Modèles :
-
🎨 Créer des combos
+🎨 Create Combos
-### Exemple 1 : Maximiser l'abonnement → Backup économique +### Example 1: Maximize Subscription → Cheap Backup ``` -Tableau de bord → Combos → Créer nouveau +Dashboard → Combos → Create New -Nom : premium-coding -Modèles : - 1. cc/claude-opus-4-6 (Abonnement principal) - 2. glm/glm-4.7 (Backup économique, $0.6/1M) - 3. minimax/MiniMax-M2.1 (Fallback le moins cher, $0.20/1M) +Name: premium-coding +Models: + 1. cc/claude-opus-4-6 (Subscription primary) + 2. glm/glm-4.7 (Cheap backup, $0.6/1M) + 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M) -Utilisez en CLI : premium-coding +Use in CLI: premium-coding ``` -### Exemple 2 : Gratuit uniquement (Zéro coût) +### Example 2: Free-Only (Zero Cost) ``` -Nom : free-combo -Modèles : - 1. gc/gemini-3-flash-preview (180K gratuits/mois) - 2. if/kimi-k2-thinking (illimité) - 3. qw/qwen3-coder-plus (illimité) +Name: free-combo +Models: + 1. gc/gemini-3-flash-preview (180K free/month) + 2. if/kimi-k2-thinking (unlimited) + 3. qw/qwen3-coder-plus (unlimited) -Coût : 0 $ pour toujours ! +Cost: $0 forever! ```
-
---
-## 🐛 Dépannage
+## Dépannage
🔧 Intégration CLI
+🔧 CLI Integration
### Cursor IDE ``` -Paramètres → Modèles → Avancé : - OpenAI API Base URL : http://localhost:20128/v1 - OpenAI API Key : [du tableau de bord OmniRoute] - Model : cc/claude-opus-4-6 +Settings → Models → Advanced: + OpenAI API Base URL: http://localhost:20128/v1 + OpenAI API Key: [from OmniRoute dashboard] + Model: cc/claude-opus-4-6 ``` ### Claude Code -Utilisez la page **CLI Tools** dans le tableau de bord pour la configuration en un clic, ou modifiez `~/.claude/settings.json` manuellement. +Use the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually. ### Codex CLI @@ -1271,13 +1679,13 @@ codex "your prompt" ### OpenClaw -**Option 1 — Tableau de bord (recommandé) :** +**Option 1 — Dashboard (recommended):** ``` -Tableau de bord → CLI Tools → OpenClaw → Sélectionner modèle → Appliquer +Dashboard → CLI Tools → OpenClaw → Select Model → Apply ``` -**Option 2 — Manuel :** Modifier `~/.openclaw/openclaw.json` : +**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`: ```json { @@ -1293,155 +1701,420 @@ Tableau de bord → CLI Tools → OpenClaw → Sélectionner modèle → Appliqu } ``` -> **Note :** OpenClaw fonctionne uniquement avec OmniRoute local. Utilisez `127.0.0.1` au lieu de `localhost` pour éviter les problèmes de résolution IPv6. +> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues. ### Cline / Continue / RooCode ``` -Paramètres → Configuration API : - Fournisseur : OpenAI Compatible - Base URL : http://localhost:20128/v1 - API Key : [du tableau de bord OmniRoute] - Model : if/kimi-k2-thinking +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. +
-
-- **Runtime** : Node.js 20+
-- **Langage** : TypeScript 5.9 — **100% TypeScript** dans `src/` et `open-sse/` (v1.0.6)
-- **Framework** : Next.js 16 + React 19 + Tailwind CSS 4
-- **Base de données** : LowDB (JSON) + SQLite (état du domaine + logs proxy)
-- **Streaming** : Server-Sent Events (SSE)
-- **Auth** : OAuth 2.0 (PKCE) + JWT + API Keys
-- **Tests** : Node.js test runner (368+ tests unitaires)
-- **CI/CD** : GitHub Actions (publication automatique npm + Docker Hub lors du release)
-- **Site web** : [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)
-- **Résilience** : Circuit breaker, backoff exponentiel, anti-thundering herd, spoofing TLS
+## 🛠️ Tech Stack
+
+Cliquez pour développer le guide de dépannage
+Click to expand troubleshooting guide
-**« Language model did not provide messages »** +**"Language model did not provide messages"** -- Quota du fournisseur épuisé → Vérifiez le suivi de quota dans le tableau de bord -- Solution : Utilisez un combo avec fallback ou passez à un niveau moins cher +- Provider quota exhausted → Check dashboard quota tracker +- Solution: Use combo fallback or switch to cheaper tier **Rate limiting** -- Quota d'abonnement épuisé → Fallback vers GLM/MiniMax -- Ajoutez un combo : `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Subscription quota out → Fallback to GLM/MiniMax +- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -**Token OAuth expiré** +**OAuth token expired** -- Renouvelé automatiquement par OmniRoute -- Si le problème persiste : Tableau de bord → Fournisseur → Reconnecter +- Auto-refreshed by OmniRoute +- If issues persist: Dashboard → Provider → Reconnect -**Coûts élevés** +**High costs** -- Vérifiez les statistiques d'utilisation dans Tableau de bord → Coûts -- Changez le modèle principal pour GLM/MiniMax -- Utilisez le niveau gratuit (Gemini CLI, iFlow) pour les tâches non critiques +- Check usage stats in Dashboard → Costs +- Switch primary model to GLM/MiniMax +- Use free tier (Gemini CLI, iFlow) for non-critical tasks -**Le tableau de bord s'ouvre sur le mauvais port** +**Dashboard/API ports are wrong** -- Définissez `PORT=20128` et `NEXT_PUBLIC_BASE_URL=http://localhost:20128` +- `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) -**Erreurs de cloud sync** +**Cloud sync errors** -- Vérifiez que `BASE_URL` pointe vers votre instance en cours d'exécution -- Vérifiez que `CLOUD_URL` pointe vers le point de terminaison cloud attendu -- Gardez les valeurs `NEXT_PUBLIC_*` alignées avec les valeurs du serveur +- 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 -**Le premier login ne fonctionne pas** +**First login not working** -- Vérifiez `INITIAL_PASSWORD` dans `.env` -- Si non défini, le mot de passe par défaut est `123456` +- Check `INITIAL_PASSWORD` in `.env` +- If unset, fallback password is `123456` -**Pas de logs de requêtes** +**No request logs** -- Définissez `ENABLE_REQUEST_LOGS=true` dans `.env` +- Set `ENABLE_REQUEST_LOGS=true` in `.env` -**Le test de connexion affiche « Invalid » pour les fournisseurs compatibles OpenAI** +**Connection test shows "Invalid" for OpenAI-compatible providers** -- Beaucoup de fournisseurs n'exposent pas le point de terminaison `/models` -- OmniRoute v1.0.6+ inclut une validation de secours via chat completions -- Assurez-vous que l'URL de base inclut le suffixe `/v1` +- 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** + +#### Why does Antigravity / Gemini CLI OAuth fail on remote servers? + +The **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console. + +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 + +# For Gemini CLI: +GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com +GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +``` + +**6. Restart OmniRoute** + +```bash +# npm: +npm run dev + +# Docker: +docker restart omniroute +``` + +**7. Try connecting again** + +Dashboard → Providers → Antigravity (or Gemini CLI) → OAuth + +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. + +--- + +
+
---
-## 🛠️
+🇧🇷 Versão em Português
+ +#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos? + +Os provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo. + +As credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticação com: + +``` +Error 400: redirect_uri_mismatch +``` + +#### Solução: Configure suas próprias credenciais OAuth + +Você precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor. + +#### Passo a passo + +**1. Acesse o Google Cloud Console** + +Abra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) + +**2. Crie um novo OAuth 2.0 Client ID** + +- Clique em **"+ Create Credentials"** → **"OAuth client ID"** +- Tipo de aplicativo: **"Web application"** +- Nome: escolha qualquer nome (ex: `OmniRoute Remote`) + +**3. Adicione as Authorized Redirect URIs** + +No campo **"Authorized redirect URIs"**, adicione: + +``` +https://seu-servidor.com/callback +``` + +> Substitua `seu-servidor.com` pelo domínio ou IP do seu servidor (inclua a porta se necessário, ex: `http://45.33.32.156:20128/callback`). + +**4. Salve e copie as credenciais** + +Após criar, o Google mostrará o **Client ID** e o **Client Secret**. + +**5. Configure as variáveis de ambiente** + +No seu `.env` (ou nas variáveis de ambiente do Docker): + +```bash +# Para Antigravity: +ANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com +ANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret + +# Para Gemini CLI: +GEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com +GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret +GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret +``` + +**6. Reinicie o OmniRoute** + +```bash +# Se usando npm: +npm run dev + +# Se usando Docker: +docker restart omniroute +``` + +**7. Tente conectar novamente** + +Dashboard → Providers → Antigravity (ou Gemini CLI) → OAuth + +Agora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará. + +--- + +#### Workaround temporário (sem configurar credenciais próprias) + +Se não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**: + +1. O OmniRoute abrirá a URL de autorização do Google +2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto) +3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue) +4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute +5. Clique em **"Connect"** + +> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.
+
---
-## 📖 Documentation
+## Documentation
-| Document | Description |
-| ------------------------------------------ | --------------------------------------------------- |
-| [Guide utilisateur](docs/USER_GUIDE.md) | Fournisseurs, combos, intégration CLI, déploiement |
-| [Référence API](docs/API_REFERENCE.md) | Tous les endpoints avec exemples |
-| [Dépannage](docs/TROUBLESHOOTING.md) | Problèmes courants et solutions |
-| [Architecture](docs/ARCHITECTURE.md) | Architecture système et détails internes |
-| [Contribuer](CONTRIBUTING.md) | Configuration de développement et directives |
-| [Spécification OpenAPI](docs/openapi.yaml) | Spécification OpenAPI 3.0 |
-| [Politique de sécurité](SECURITY.md) | Signalement de vulnérabilités et pratiques sécurité |
+| Document | Description |
+| ---------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 16 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/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
+| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
-## 🗺️
+## 🗺️ Roadmap
-## 👥 Contributeurs
+OmniRoute has **210+ 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, P2C account selection |
+| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |
+| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |
+| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider 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
[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
-### Comment contribuer
+### How to Contribute
-1. Forkez le dépôt
-2. Créez votre branche de fonctionnalité (`git checkout -b feature/amazing-feature`)
-3. Committez vos changements (`git commit -m 'Add amazing feature'`)
-4. Poussez vers la branche (`git push origin feature/amazing-feature`)
-5. Ouvrez une Pull Request
+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
-Consultez [CONTRIBUTING.md](CONTRIBUTING.md) pour les directives détaillées.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
-### Publier une nouvelle version
+### Releasing a New Version
```bash
-# Créer un release — la publication npm est automatique
-gh release create v1.0.6 --title "v1.0.6" --generate-notes
+# Create a release — npm publish happens automatically
+gh release create v2.0.0 --title "v2.0.0" --generate-notes
```
---
-## 📊 Historique des Stars
+## 📊 Star History
## Stargazers over time
## [](https://starchart.cc/diegosouzapw/OmniRoute)
-## 🙏 Remerciements
+## 🙏 Acknowledgments
-Remerciements spéciaux à **[9router](https://github.com/decolua/9router)** par **[decolua](https://github.com/decolua)** — le projet original qui a inspiré ce fork. OmniRoute construit sur cette base incroyable avec des fonctionnalités supplémentaires, des APIs multi-modales et une réécriture complète en TypeScript.
+Special thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.
-Remerciements spéciaux à **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — l'implémentation originale en Go qui a inspiré ce portage en JavaScript.
+Special thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.
---
-## 📄 Licence
+## Licence
-Licence MIT — voir [LICENSE](LICENSE) pour les détails.
+MIT License - see [LICENSE](LICENSE) for details.
---
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**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions) +- **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 + +
- Fait avec ❤️ pour les développeurs qui codent 24/7
+ Built with ❤️ for developers who code 24/7
omniroute.online
+
diff --git a/docs/i18n/fr/docs/FEATURES.md b/docs/i18n/fr/docs/FEATURES.md
new file mode 100644
index 0000000000..7d7826febb
--- /dev/null
+++ b/docs/i18n/fr/docs/FEATURES.md
@@ -0,0 +1,145 @@
+# OmniRoute — Dashboard Features Gallery (Français)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/FEATURES.md) · 🇪🇸 [es](../../es/docs/FEATURES.md) · 🇫🇷 [fr](../../fr/docs/FEATURES.md) · 🇩🇪 [de](../../de/docs/FEATURES.md) · 🇮🇹 [it](../../it/docs/FEATURES.md) · 🇷🇺 [ru](../../ru/docs/FEATURES.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FEATURES.md) · 🇯🇵 [ja](../../ja/docs/FEATURES.md) · 🇰🇷 [ko](../../ko/docs/FEATURES.md) · 🇸🇦 [ar](../../ar/docs/FEATURES.md) · 🇮🇳 [in](../../in/docs/FEATURES.md) · 🇹🇭 [th](../../th/docs/FEATURES.md) · 🇻🇳 [vi](../../vi/docs/FEATURES.md) · 🇮🇩 [id](../../id/docs/FEATURES.md) · 🇲🇾 [ms](../../ms/docs/FEATURES.md) · 🇳🇱 [nl](../../nl/docs/FEATURES.md) · 🇵🇱 [pl](../../pl/docs/FEATURES.md) · 🇸🇪 [sv](../../sv/docs/FEATURES.md) · 🇳🇴 [no](../../no/docs/FEATURES.md) · 🇩🇰 [da](../../da/docs/FEATURES.md) · 🇫🇮 [fi](../../fi/docs/FEATURES.md) · 🇵🇹 [pt](../../pt/docs/FEATURES.md) · 🇷🇴 [ro](../../ro/docs/FEATURES.md) · 🇭🇺 [hu](../../hu/docs/FEATURES.md) · 🇧🇬 [bg](../../bg/docs/FEATURES.md) · 🇸🇰 [sk](../../sk/docs/FEATURES.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FEATURES.md) · 🇮🇱 [he](../../he/docs/FEATURES.md) · 🇵🇭 [phi](../../phi/docs/FEATURES.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FEATURES.md)
+
+---
+
+Visual guide to every section of the OmniRoute dashboard.
+
+---
+
+## 🔌 Providers
+
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
+
+
+
+---
+
+## 🎨 Combos
+
+Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
+
+
+
+---
+
+## 📊 Analytics
+
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
+
+
+
+---
+
+## 🏥 System Health
+
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+
+
+
+---
+
+## 🔧 Translator Playground
+
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
+
+
+
+---
+
+## 🎮 Model Playground _(v2.0.9+)_
+
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
+
+---
+
+## 🎨 Themes _(v2.0.5+)_
+
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
+
+## ⚙️ Settings
+
+Comprehensive settings panel with tabs:
+
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning
+- **Advanced** — Configuration overrides
+
+
+
+---
+
+## 🔧 CLI Tools
+
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
+
+
+
+---
+
+## 🤖 CLI Agents _(v2.0.11+)_
+
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
+
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
+
+---
+
+## 🖼️ Media _(v2.0.3+)_
+
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
+
+## 📝 Request Logs
+
+Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
+
+
+
+---
+
+## 🌐 API Endpoint
+
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
+
+
+
+---
+
+## 🔑 API Key Management
+
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
+
+---
+
+## 📋 Audit Log
+
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
+
+---
+
+## 🖥️ Desktop Application
+
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
+
+Key features:
+
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
+
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.
diff --git a/docs/i18n/he/README.md b/docs/i18n/he/README.md
index c07cc4921b..51d84073a2 100644
--- a/docs/i18n/he/README.md
+++ b/docs/i18n/he/README.md
@@ -1,24 +1,94 @@
-omniroute.online
-
-
- # 🚀 OmniRoute — שער הבינה המלאכותית החינמית
+# 🚀 OmniRoute — The Free AI Gateway (עברית)
-### לעולם אל תפסיק לקוד. ניתוב חכם לדגמי בינה מלאכותית **בחינם ובעלות נמוכה** עם חזרה אוטומטית.
-
-_שרת ה-API האוניברסלי שלך - נקודת קצה אחת, 36+ ספקים, אפס זמן השבתה._
-
-**השלמות צ'אט • הטמעות • יצירת תמונות • אודיו • דירוג מחדש • 100% TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 ספק AI בחינם עבור סוכני הקידוד המועדפים עליך
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_חבר כל כלי IDE או CLI המופעל על ידי AI דרך OmniRoute - שער API בחינם לקידוד בלתי מוגבל._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+` tags no longer leak to clients in SSE streaming responses (#585) |
+| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with per-provider/account quota enforcement, idempotency, SHA-256 storage, and optional GitHub issue reporting |
+| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG → generic fallback chain |
+| 🔄 **Model Auto-Sync** | 24h scheduler and manual UI toggle to sync model lists for built-in and custom OpenAI-compatible providers |
+| 🌐 **OpenCode Zen/Go** | Two new providers from @kang-heewon via PR #530: free tier + subscription tier via `OpencodeExecutor` |
+| 🐛 **Gemini CLI OAuth** | Actionable error when `GEMINI_OAUTH_CLIENT_SECRET` is missing in Docker (was cryptic Google error) |
+| 🐛 **OpenCode config** | `saveOpenCodeConfig()` now correctly writes TOML to `XDG_CONFIG_HOME` |
+| 🐛 **Pinned model override** | `body.model` correctly set to `pinnedModel` on context-cache protection |
+| 🐛 **Codex/Claude loop** | `tool_result` blocks now converted to text to stop infinite loops |
+| 🐛 **Login redirect** | Login no longer freezes after skipping password setup |
+| 🐛 **Windows paths** | MSYS2/Git-Bash paths (`/c/...`) normalized to `C:\...` automatically |
+
+---
+
+## 🖼️ Main Dashboard
+
+
-📡 כל הסוכנים מתחברים דרך ` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**Stop wasting money and hitting limits:**
-### 🆕 What's New in v3.0.0
+- Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**OmniRoute solves this:**
+
+- ✅ **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
+- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool
---
-[](https://www.npmjs.com/package/omniroute)
-[](https://hub.docker.com/r/diegosouzapw/omniroute)
-[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
-[](https://omniroute.online)
-[](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
+## 📧 Support
-[🌐 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)
+> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.
-🌐 **Available in:** 🇺🇸 [English](../../README.md) | 🇧🇷 [Português (Brasil)](../pt-BR/README.md) | 🇪🇸 [Español](../es/README.md) | 🇫🇷 [Français](../fr/README.md) | 🇮🇹 [Italiano](../it/README.md) | 🇷🇺 [Русский](../ru/README.md) | 🇨🇳 [中文 (简体)](../zh-CN/README.md) | 🇩🇪 [Deutsch](../de/README.md) | 🇮🇳 [हिन्दी](../in/README.md) | 🇹🇭 [ไทย](../th/README.md) | 🇺🇦 [Українська](../uk-UA/README.md) | 🇸🇦 [العربية](../ar/README.md) | 🇯🇵 [日本語](../ja/README.md) | 🇻🇳 [Tiếng Việt](../vi/README.md) | 🇧🇬 [Български](../bg/README.md) | 🇩🇰 [Dansk](../da/README.md) | 🇫🇮 [Suomi](../fi/README.md) | 🇮🇱 [עברית](../he/README.md) | 🇭🇺 [Magyar](../hu/README.md) | 🇮🇩 [Bahasa Indonesia](../id/README.md) | 🇰🇷 [한국어](../ko/README.md) | 🇲🇾 [Bahasa Melayu](../ms/README.md) | 🇳🇱 [Nederlands](../nl/README.md) | 🇳🇴 [Norsk](../no/README.md) | 🇵🇹 [Português (Portugal)](../pt/README.md) | 🇷🇴 [Română](../ro/README.md) | 🇵🇱 [Polski](../pl/README.md) | 🇸🇰 [Slovenčina](../sk/README.md) | 🇸🇪 [Svenska](../sv/README.md) | 🇵🇭 [Filipino](../phi/README.md)
-
-
-
----
-
-## 🖼️
-
-
-
- # 🚀 OmniRoute — שער הבינה המלאכותית החינמית
+# 🚀 OmniRoute — The Free AI Gateway (עברית)
-### לעולם אל תפסיק לקוד. ניתוב חכם לדגמי בינה מלאכותית **בחינם ובעלות נמוכה** עם חזרה אוטומטית.
-
-_שרת ה-API האוניברסלי שלך - נקודת קצה אחת, 36+ ספקים, אפס זמן השבתה._
-
-**השלמות צ'אט • הטמעות • יצירת תמונות • אודיו • דירוג מחדש • 100% TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 ספק AI בחינם עבור סוכני הקידוד המועדפים עליך
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_חבר כל כלי IDE או CLI המופעל על ידי AI דרך OmniRoute - שער API בחינם לקידוד בלתי מוגבל._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+
+
+[](https://www.npmjs.com/package/omniroute)
+[](https://www.npmjs.com/package/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
+[](https://omniroute.online)
+[](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)
+
+
+
+🌐 **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)
+
+---
+
+## 🆕 What's New in v3.0.0
+
+> **Upgrading from v2.9.5?** — See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes.
+
+| Area | Change |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection remediation |
+| ✅ **Route Validation** | All 176 API routes now validated with Zod schemas + `validateBody()` — CI `check:route-validation:t06` passes |
+| 🐛 **omniModel Tag Leak** | Internal `
+
+
+
+---
+
+## 📸 Dashboard Preview
+
+
+
+
+
+---
+
+### 🤖 Free AI Provider for your favorite coding agents
+
+_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._
Click to see dashboard screenshots
+ +| Page | Screenshot | +| -------------- | ------------------------------------------------- | +| **Providers** |  | +| **Combos** |  | +| **Analytics** |  | +| **Health** |  | +| **Translator** |  | +| **Settings** |  | +| **CLI Tools** |  | +| **Usage Logs** |  | +| **Endpoints** |  | + +|
-
+
OpenClaw @@ -92,113 +162,52 @@ _חבר כל כלי IDE או CLI המופעל על ידי AI דרך OmniRoute - |
http://localhost:20128/v1 או http://cloud.omniroute.online/v1 , —limited one config מכסה
+📡 All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 — one config, unlimited models and quota
---
-### 🆕 What's New in v3.0.0
+## 🤔 Why OmniRoute?
-| Area | Change |
-| ------------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal ` Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `
-
-
-
----
-
-## 📸
-
-
-
-
-
----
-
-## 🤔 למה OmniRoute?
-
-**הפסיקו לבזבז כסף ולהגיע לגבולות:**
-
-- ...
- -| # | # | -| ----- | ---------------------------------------- | -| **1** |  | -| **2** |  | -| **3** |  | -| **4** |  | -| **5** |  | -| **6** |  | -| **7** |  | -| **8** |  | -| **9** |  | - - מכסת המנויים מסתיימת ללא שימוש בכל חודש
-- מגבלות קצב עוצרות אותך בקידוד באמצע
-- ממשקי API יקרים ($20-50 לחודש לכל ספק)
-- מעבר ידני בין ספקים
-
-**OmniRoute פותר את זה:**
-
-- ✅ **מקסם מנויים** - עקוב אחר מכסת, השתמש בכל סיביות לפני האיפוס
-- ✅ **החזר אוטומטי** - מנוי → מפתח API → זול → חינם, אפס זמן השבתה
-- ✅ **ריבוי חשבונות** - סיבוב בין חשבונות לכל ספק
-- ✅ **אוניברסלי** - עובד עם קלוד קוד, Codex, Gemini CLI, Cursor, Cline, OpenClaw, כל כלי CLI
-
----
-
-## 📧 תמיכה
-
-> 💬 **הצטרפו לקהילה שלנו!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — קבל עזרה, שתף טיפים והישאר מעודכן.
-
-- **אתר**: [omniroute.online](https://omniroute.online)
+- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **בעיות**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **וואטסאפ**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **פרויקט מקורי**: [9router by decolua](https://github.com/decolua/9router)
+- **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`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 איך זה עובד
+## 🔄 How It Works
```
┌─────────────┐
@@ -227,451 +236,453 @@ Result: Never stop coding, minimal cost
---
-## 🎯 מה OmniRoute פותר - 30 נקודות כאב אמיתיות ומקרי שימוש
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **כל מפתח המשתמש בכלי בינה מלאכותית מתמודד עם הבעיות הללו מדי יום.** OmniRoute נבנתה כדי לפתור את כולן - החל מחריפות עלויות ועד לחסימות אזוריות, מזרימות OAuth שבורות ועד פעולות פרוטוקול וצפייה ארגונית.
+> **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.
-
💸 1. "אני משלם עבור מנוי יקר אבל עדיין מופרע על ידי גבולות"
+💸 1. "I pay for an expensive subscription but still get interrupted by limits"
-מפתחים משלמים $20-200 לחודש עבור Claude Pro, Codex Pro או GitHub Copilot. אפילו בתשלום, למכסה יש תקרה - 5 שעות שימוש, מגבלות שבועיות או מגבלות תעריף לדקה. סשן קידוד באמצע, הספק מפסיק להגיב והמפתח מאבד זרימה ופרודוקטיביות. +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. -**איך OmniRoute פותר את זה:** +**How OmniRoute solves it:** -- **Smart 4-Tier Fallback** - אם מכסת המנויים נגמרת, מפנה אוטומטית למפתח API → זול → חינם עם אפס התערבות ידנית -- **מעקב מכסות בזמן אמת** - מציג צריכת אסימונים בזמן אמת עם ספירה לאחור מאפס (5 שעות, יומי, שבועי) -- **תמיכה בריבוי חשבונות** - מספר חשבונות לכל ספק עם סבב אוטומטי - כאשר אחד אוזל, עובר לאחר -- **שילובים מותאמים אישית** - שרשראות ניתנות להתאמה אישית עם 6 אסטרטגיות איזון (מילוי ראשון, סיבוב סיבובי, P2C, אקראי, הכי פחות בשימוש, אופטימיזציה לעלות) -- **Codex Business Quotas** - ניטור מכסות סביבת עבודה עסקית/צוותית ישירות בלוח המחוונים +- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention +- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly) +- **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 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
-` מדגמים כמו DeepSeek R1 לתוך `reasoning_content` הסטנדרטי
-- **פלט מובנה עבור מזל תאומים** — `json_schema` → `responseMimeType`/`responseSchema` המרה אוטומטית
-- **`stream` ברירת המחדל היא `false`** - מתיישר עם מפרט OpenAI, הימנעות SSE בלתי צפוי ב- Python/Rust/Go SDK
+- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 67+ 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
🔌 2. "אני צריך להשתמש במספר ספקים אבל לכל אחד יש API אחר"
+🔌 2. "I need to use multiple providers but each has a different API"
-OpenAI משתמש בפורמט אחד, קלוד (אנתרופיק) משתמש בפורמט אחר, תאומים בנוסח אחר. אם מפתח רוצה לבחון דגמים מספקים שונים או לחלוף ביניהם, הוא צריך להגדיר מחדש SDK, לשנות נקודות קצה, להתמודד עם פורמטים לא תואמים. לספקים מותאמים אישית (FriendLI, NIM) יש נקודות קצה לא סטנדרטיות במודל. +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. -**איך OmniRoute פותר את זה:** +**How OmniRoute solves it:** -- **נקודת קצה מאוחדת** - `http://localhost:20128/v1` יחיד משמש כ-proxy עבור כל 36+ הספקים -- **תרגום פורמט** — אוטומטי ושקוף: OpenAI ↔ Claude ↔ Gemini ↔ Responses API -- **חיטוי תגובה** - מסיר שדות לא סטנדרטיים (`x_groq`, `usage_breakdown`, `service_tier`) שמפרקים את OpenAI SDK v1.83+ -- **נורמליזציה של תפקידים** — ממירה `developer` → `system` עבור ספקים שאינם OpenAI; `system` → `user` עבור GLM/ERNIE -- **Think Tag Extraction** — מחלץ בלוקים `
-
🌐 3. "ספק הבינה המלאכותית שלי חוסם את האזור/המדינה שלי"
+🌐 3. "My AI provider blocks my region/country"
-ספקים כמו OpenAI/Codex חוסמים גישה מאזורים גיאוגרפיים מסוימים. משתמשים מקבלים שגיאות כמו `unsupported_country_region_territory` במהלך חיבורי OAuth ו-API. זה מתסכל במיוחד עבור מפתחים ממדינות מתפתחות. +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. -**איך OmniRoute פותר את זה:** +**How OmniRoute solves it:** -- **תצורת פרוקסי בשלוש רמות** - פרוקסי ניתן להגדרה ב-3 רמות: גלובלית (כל התעבורה), לכל ספק (ספק אחד בלבד), ולכל חיבור/מפתח -- **תגי פרוקסי מקודדים בצבע** - אינדיקטורים חזותיים: 🟢 פרוקסי גלובלי, 🟡 פרוקסי ספק, 🔵 פרוקסי חיבור, תמיד מציג את ה-IP -- **החלפת אסימונים של OAuth באמצעות פרוקסי** - זרימת OAuth עוברת גם דרך ה-proxy, ופותרת את `unsupported_country_region_territory` -- **בדיקות חיבור באמצעות פרוקסי** - בדיקות חיבור משתמשות בפרוקסי המוגדר (לא עוד מעקף ישיר) -- **תמיכה SOCKS5** — תמיכה מלאה ב-Proxy SOCKS5 לניתוב יוצא -- **זיוף טביעות אצבע TLS** - טביעת אצבע TLS דמוית דפדפן באמצעות `wreq-js` כדי לעקוף את זיהוי הבוטים +- **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
-` prefix
-- **שילובים בחינם בלבד** — שרשרת `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0 לחודש עם אפס זמן השבתה
-- **קרדיטים חינם של NVIDIA NIM** - 1000 זיכויים חינם משולבים
-- **אסטרטגיית אופטימיזציה לעלות** — אסטרטגיית ניתוב שבוחרת אוטומטית את הספק הזמין הזול ביותר
+- **Free-Only Combos** — Chain `gc/gemini-3-flash → 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
🆓 4. "אני רוצה להשתמש ב-AI לקידוד אבל אין לי כסף"
+🆓 4. "I want to use AI for coding but I have no money"
-לא כולם יכולים לשלם 20-200 $ לחודש עבור מנויי AI. סטודנטים, מפתחים ממדינות מתפתחות, חובבים ופרילנסרים צריכים גישה לדגמים איכותיים בעלות אפסית. +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. -**איך OmniRoute פותר את זה:** +**How OmniRoute solves it:** -- **ספקי שכבת חינם מובנית** - תמיכה מקורית עבור 100% ספקים בחינם: iFlow (8 דגמים ללא הגבלה), Qwen (3 דגמים ללא הגבלה), Kiro (קלוד בחינם), Gemini CLI (180K/חודש חינם) +- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free) - **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/
-
🔒 5. "אני צריך להגן על שער הבינה המלאכותית שלי מגישה לא מורשית"
+🔒 5. "I need to protect my AI gateway from unauthorized access"
-בעת חשיפת שער AI לרשת (LAN, VPS, Docker), כל מי שיש לו את הכתובת יכול לצרוך את האסימונים/מכסה של המפתח. ללא הגנה, ממשקי API חשופים לשימוש לרעה, הזרקה מהירה וניצול לרעה. +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. -**איך OmniRoute פותר את זה:** +**How OmniRoute solves it:** -- **ניהול מפתחות API** - יצירה, סיבוב והיקף לכל ספק עם דף `/dashboard/api-manager` ייעודי -- **הרשאות ברמת הדגם** - הגבל מפתחות API לדגמים ספציפיים (`openai/*`, דפוסי תווים כלליים), עם החלפת מצב אפשר הכל/הגבל -- **הגנה על נקודות קצה של API** - דרוש מפתח עבור `/v1/models` וחסום ספקים ספציפיים מהרישום -- **Auth Guard + CSRF Protection** — כל מסלולי לוח המחוונים מוגנים באמצעות תוכנת ביניים `withAuth` + אסימוני CSRF -- ** מגביל קצב** - הגבלת קצב לפי IP עם חלונות הניתנים להגדרה -- **סינון IP** — רשימת הרשאות/רשימת חסימות לבקרת גישה -- **משמר הזרקה מהירה** - חיטוי נגד דפוסי הנחיה זדוניים -- **הצפנת AES-256-GCM** - אישורים מוצפנים בזמן מנוחה +- **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. "הספק שלי נפל ואיבדתי את זרימת הקידוד"
+🛑 6. "My provider went down and I lost my coding flow"
-ספקי בינה מלאכותית עלולים להפוך לבלתי יציבים, להחזיר שגיאות 5xx או לפגוע במגבלות קצב זמניות. אם מפתח תלוי בספק יחיד, הם מופרעים. ללא מפסקים, נסיונות חוזרים ונשנים עלולים לקרוס את האפליקציה. +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. -**איך OmniRoute פותר את זה:** +**How OmniRoute solves it:** -- **מפסק מעגלים לכל ספק** - פתיחה/סגירה אוטומטית עם ספים ניתנים להגדרה והתקררות (סגור/פתוח/חצי פתוח) -- **גיבוי אקספוננציאלי** - עיכובים מתקדמים בניסיון חוזר -- **עדר נגד רעמים** - הגנה על מוטקס + סמפור מפני סופות ניסיונות חוזרות במקביל -- **שרשראות משולבות Fallback** - אם הספק הראשי נכשל, נופל אוטומטית בשרשרת ללא התערבות -- **מפסק משולב** - משבית אוטומטית ספקים כושלים בשרשרת משולבת -- **לוח מחוונים לבריאות** - ניטור זמן פעולה, מצבי מפסק זרם, נעילות, סטטיסטיקות מטמון, זמן אחזור p50/p95/p99 +- **Circuit Breaker per-model** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks +- **Exponential Backoff** — Progressive retry delays +- **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 +- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain +- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
-
🔧 7. "הגדרת כל כלי בינה מלאכותית היא מייגעת וחוזרת על עצמה"
+🔧 7. "Configuring each AI tool is tedious and repetitive"
-מפתחים משתמשים ב-Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... כל כלי צריך תצורה שונה (נקודת קצה, מפתח, מודל API). הגדרה מחדש בעת החלפת ספקים או דגמים היא בזבוז זמן. +Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time. -**איך OmniRoute פותר את זה:** +**How OmniRoute solves it:** -- **לוח המחוונים של CLI Tools** - דף ייעודי עם הגדרה בלחיצה אחת עבור Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline -- **GitHub Copilot Config Generator** — מייצר `chatLanguageModels.json` עבור קוד VS עם בחירת דגמים בכמות גדולה -- **אשף ההטמעה** — הגדרה מודרכת בת 4 שלבים למשתמשים ראשונים -- **נקודת קצה אחת, כל הדגמים** - הגדר את `http://localhost:20128/v1` פעם אחת, גש ל-36+ ספקים +- **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 67+ providers
-
🔑 8. "ניהול אסימוני OAuth ממספר ספקים זה גיהנום"
+🔑 8. "Managing OAuth tokens from multiple providers is hell"
-Claude Code, Codex, Gemini CLI, Copilot - כולם משתמשים ב-OAuth 2.0 עם אסימונים שפג תוקפם. מפתחים צריכים לבצע אימות מחדש כל הזמן, להתמודד עם `client_secret is missing`, `redirect_uri_mismatch` וכשלים בשרתים מרוחקים. OAuth ב-LAN/VPS בעייתי במיוחד. +Claude Code, Codex, Gemini CLI, 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. -**איך OmniRoute פותר את זה:** +**How OmniRoute solves it:** -- **רענון אסימון אוטומטי** - אסימוני OAuth מתרעננים ברקע לפני פקיעת תוקף -- **OAuth 2.0 (PKCE) מובנה** - זרימה אוטומטית עבור Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow -- ** OAuth מרובה חשבונות** - מספר חשבונות לכל ספק באמצעות חילוץ אסימון JWT/ID -- **OAuth LAN/תיקון מרחוק** - זיהוי IP פרטי עבור `redirect_uri` + מצב כתובת URL ידני עבור שרתים מרוחקים -- **OAuth Behind Nginx** - משתמש ב-`window.location.origin` עבור תאימות פרוקסי הפוכה -- **מדריך OAuth מרחוק** - מדריך שלב אחר שלב לאישורי Google Cloud ב-VPS/Docker +- **Auto Token Refresh** — OAuth tokens refresh in background before expiration +- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow +- **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. "אני לא יודע כמה אני מוציא או איפה"
+📊 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. -**איך OmniRoute פותר את זה:** +**How OmniRoute solves it:** -- **לוח מחוונים של ניתוח עלויות** - מעקב אחר עלויות לפי אסימון וניהול תקציב לכל ספק -- **מגבלות תקציב לכל שכבה** - תקרת הוצאה לכל שכבה שמפעילה נפילה אוטומטית -- **תצורת תמחור לפי דגם** — מחירים הניתנים להגדרה לכל דגם -- **סטטיסטיקת שימוש לכל מפתח API** - ספירת בקשות וחותמת זמן אחרונה בשימוש לכל מפתח -- **לוח המחוונים של אנליטיקס** - כרטיסי סטטיסטיקה, טבלת שימוש במודל, טבלת ספקים עם אחוזי הצלחה והשהייה +- **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. "אני לא יכול לאבחן שגיאות ובעיות בשיחות AI"
+🐛 10. "I can't diagnose errors and problems in AI calls"
-כאשר שיחה נכשלת, ה-dev לא יודע אם זו הייתה מגבלת תעריף, אסימון שפג תוקפו, פורמט שגוי או שגיאת ספק. יומנים מפוצלים על פני מסופים שונים. ללא צפייה, איתור באגים הוא ניסוי וטעייה. +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. -**איך OmniRoute פותר את זה:** +**How OmniRoute solves it:** -- **לוח מחוונים של יומנים מאוחדים** - 4 כרטיסיות: יומני בקשות, יומני פרוקסי, יומני ביקורת, מסוף -- **מציג יומן מסוף** - מציג בזמן אמת בסגנון טרמינל עם רמות מקודדות צבע, גלילה אוטומטית, חיפוש, סינון -- **SQLite Proxy Logs** - יומנים מתמשכים ששורדים אתחול מחדש של השרת -- **מגרש משחקים לתרגום** - 4 מצבי ניפוי באגים: מגרש משחקים (תרגום פורמט), בודק צ'אט (הלוך ושוב), ספסל בדיקה (אצווה), צג חי (בזמן אמת) -- **Request Telemetry** — חביון p50/p95/p99 + X-Request-Id מעקב -- **רישום מבוסס קבצים עם סיבוב** - מיירט המסוף לוכד הכל ליומן JSON עם סיבוב מבוסס גודל +- **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 Proxy Logs** — Persistent logs that survive server restarts +- **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 Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation +- **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. "פריסה ותחזוקה של השער מורכבת"
+🏗️ 11. "Deploying and maintaining the gateway is complex"
-התקנה, הגדרה ותחזוקה של פרוקסי בינה מלאכותית בסביבות שונות (מקומי, VPS, Docker, ענן) היא עתירת עבודה. בעיות כמו נתיבים מקודדים קשיחים, `EACCES` על ספריות, התנגשויות יציאות ובנייה בין פלטפורמות מוסיפות חיכוך. +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. -**איך OmniRoute פותר את זה:** +**How OmniRoute solves it:** -- **התקנה גלובלית npm** — `npm install -g omniroute && omniroute` — בוצעה -- **Docker Multi-Platform** - מקורי AMD64 + ARM64 (Apple Silicon, AWS Graviton, Raspberry Pi) -- **Docker Compose Profiles** — `base` (ללא כלי CLI) ו-`cli` (עם קוד קלוד, Codex, OpenClaw) -- **אפליקציית Electron Desktop** — אפליקציה מקורית עבור Windows/macOS/Linux עם מגש מערכת, הפעלה אוטומטית, מצב לא מקוון -- **מצב יציאות מפוצלות** - API ולוח מחוונים ביציאות נפרדות עבור תרחישים מתקדמים (פרוקסי הפוך, רשת קונטיינר) -- **Cloud Sync** - הגדרת סנכרון בין מכשירים באמצעות Cloudflare Workers -- **גיבויי DB** - גיבוי, שחזור, ייצוא וייבוא אוטומטי של כל ההגדרות +- **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
-
🌍 12. "הממשק הוא באנגלית בלבד והצוות שלי לא מדבר אנגלית"
+🌍 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. -**איך OmniRoute פותר את זה:** +**How OmniRoute solves it:** -- **לוח המחוונים i18n — 30 שפות** — כל 500+ המקשים מתורגמים כולל ערבית, בולגרית, דנית, גרמנית, ספרדית, פינית, צרפתית, עברית, הינדית, הונגרית, אינדונזית, איטלקית, יפנית, קוריאנית, מלאית, הולנדית, נורווגית, פולנית, פורטוגזית (PT/BR), רומנית, רוסית, סלובקית, שוודית, תאילנדית, סלובקית, שוודית, סינית, סלובקית, וייטנאם -- **תמיכה ב-RTL** — תמיכה מימין לשמאל לערבית ולעברית -- ** README מרובים שפות** - 30 תרגומי תיעוד מלאים -- **בורר שפה** - סמל גלובוס בכותרת למעבר בזמן אמת +- **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. "אני צריך יותר מצ'אט - אני צריך הטמעות, תמונות, אודיו"
+🔄 13. "I need more than chat — I need embeddings, images, audio"
-AI זה לא רק השלמת צ'אט. מפתחים צריכים ליצור תמונות, לתמלל אודיו, ליצור הטמעות עבור RAG, לדרג מחדש מסמכים ולתת תוכן. לכל API יש נקודת קצה ופורמט שונים. +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. -**איך OmniRoute פותר את זה:** +**How OmniRoute solves it:** -- **הטמעות** — `/v1/embeddings` עם 6 ספקים ו-9+ דגמים -- **יצירת תמונות** — `/v1/images/generations` עם 10 ספקים ו-20+ דגמים (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI) -- **טקסט לווידאו** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) ו-SD WebUI -- **טקסט למוזיקה** — `/v1/music/generations` — ComfyUI (פתוח אודיו יציב, MusicGen) -- **תמלול אודיו** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3 -- **טקסט לדיבור** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, Inworld, Cartesia, PlayHT, + ספקים קיימים -- **מודציות** — `/v1/moderations` — בדיקות בטיחות תוכן -- **דירוג מחדש** — `/v1/rerank` — דירוג מחדש של רלוונטיות המסמך -- **Responses API** — תמיכה מלאה ב-`/v1/responses` עבור Codex +- **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. "אין לי דרך לבדוק ולהשוות איכות בין דגמים"
+🧪 14. "I have no way to test and compare quality across models"
-מפתחים רוצים לדעת איזה דגם הוא הטוב ביותר עבור מקרה השימוש שלהם - קוד, תרגום, הנמקה - אבל ההשוואה ידנית היא איטית. לא קיימים כלי eval משולבים. +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. -**איך OmniRoute פותר את זה:** +**How OmniRoute solves it:** -- **הערכות LLM** - בדיקת סט זהב עם 10 מקרים טעונים מראש המכסים ברכות, מתמטיקה, גיאוגרפיה, יצירת קוד, תאימות ל-JSON, תרגום, סימון, סירוב בטיחות -- **4 אסטרטגיות התאמה** — `exact`, `contains`, `regex`, `custom` (פונקציית JS) -- **ספסל בדיקה במגרש משחקים של מתרגם** - בדיקות אצווה עם מספר כניסות ויציאות צפויות, השוואה בין ספקים -- ** בודק צ'אט** - הלוך ושוב מלא עם עיבוד תגובה ויזואלית -- **מעקב חי** - זרם בזמן אמת של כל הבקשות הזורמות דרך ה-proxy +- **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. "אני צריך לשנות קנה מידה מבלי לאבד ביצועים"
+📈 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. -**איך OmniRoute פותר את זה:** +**How OmniRoute solves it:** -- **מטמון סמנטי** - מטמון דו-שכבתי (חתימה + סמנטי) מפחית את העלות והשהייה -- **Request Idempotency** — חלון מניעת כפילויות של 5 שניות לבקשות זהות -- **זיהוי מגבלת תעריף** - RPM לכל ספק, פער מינימלי ומעקב מרבי בו-זמנית -- **מגבלות קצב הניתנות לעריכה** - ברירות מחדל הניתנות להגדרה בהגדרות ← חוסן עם התמדה -- **מטמון מפתח API** - מטמון בן 3 שכבות לביצועי ייצור -- **לוח מחוונים לבריאות עם טלמטריה** - זמן אחזור p50/p95/p99, סטטיסטיקות מטמון, זמן פעולה +- **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 +- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence +- **API Key Validation Cache** — 3-tier cache for production performance +- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
-
🤖 16. "אני רוצה לשלוט בהתנהגות המודל באופן גלובלי"
+🤖 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. -**איך OmniRoute פותר את זה:** +**How OmniRoute solves it:** -- **הזרקת הנחיית מערכת** - הנחיה גלובלית חלה על כל הבקשות -- **אימות תקציב חשיבה** - בקרת הקצאת אסימונים בהיגיון לכל בקשה (מעבר, אוטומטי, מותאם אישית, אדפטיבי) -- **6 אסטרטגיות ניתוב** - אסטרטגיות גלובליות הקובעות את אופן הפצת הבקשות -- **נתב תווים כלליים** — תבניות `provider/*` מנותבות באופן דינמי לכל ספק -- **הפעל/השבת שילוב של החלפה** — החלף שילובים ישירות מלוח המחוונים -- **החלפת ספק** — הפעל/השבת את כל החיבורים עבור ספק בלחיצה אחת -- **ספקים חסומים** — אל תכלול ספקים ספציפיים מרשימת `/v1/models` +- **System Prompt Injection** — Global prompt applied to all requests +- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive) +- **6 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 +- **Provider Toggle** — Enable/disable all connections for a provider with one click +- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
-
🧰 17. "אני צריך כלי MCP כיכולות מוצר מהשורה הראשונה"
+🧰 17. "I need MCP tools as first-class product capabilities"
-שערי AI רבים חושפים את MCP רק כפרט יישום נסתר. צוותים צריכים שכבת פעולה גלויה וניתנת לניהול. +Many AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer. -**איך OmniRoute פותר את זה:** +**How OmniRoute solves it:** -- MCP מופיע בכרטיסיית הניווט של לוח המחוונים ופרוטוקול נקודת הקצה -- דף ניהול MCP ייעודי עם תהליך, כלים, היקפים וביקורת -- התחלה מהירה מובנית עבור `omniroute --mcp` וכניסה ללקוח +- 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. "אני צריך תזמור A2A עם נתיבי משימות סינכרון + זרם"
+🧠 18. "I need A2A orchestration with sync + stream task paths"
-זרימות עבודה של סוכן זקוקות הן לתשובות ישירות והן לביצוע זרימה ארוך טווח עם בקרת מחזור חיים. +Agent workflows need both direct replies and long-running streamed execution with lifecycle control. -**איך OmniRoute פותר את זה:** +**How OmniRoute solves it:** -- נקודת קצה A2A JSON-RPC (`POST /a2a`) עם `message/send` ו-`message/stream` -- הזרמת SSE עם הפצת מצב מסוף -- ממשקי API של מחזור חיים של משימות עבור `tasks/get` ו-`tasks/cancel` +- 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. "אני צריך בריאות של תהליך MCP אמיתי, מצב לא מנחש"
+🛰️ 19. "I need real MCP process health, not guessed status"
-צוותים תפעוליים צריכים לדעת אם MCP באמת חי, לא רק אם ניתן להגיע ל-API. +Operational teams need to know if MCP is actually alive, not just whether an API is reachable. -**איך OmniRoute פותר את זה:** +**How OmniRoute solves it:** -- קובץ פעימות לב בזמן ריצה עם PID, חותמות זמן, תחבורה, ספירת כלים ומצב היקף -- MCP status API המשלב פעימות לב + פעילות אחרונה -- כרטיסי סטטוס ממשק משתמש עבור תהליך/זמן פעולה/רעננות פעימות לב +- 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. "אני צריך ביצוע כלי MCP שניתן לביקורת"
+📋 20. "I need auditable MCP tool execution"
-כאשר כלים משתנים בתצורה או מפעילים פעולות מבצעיות, הצוותים זקוקים למעקב פורנזי. +When tools mutate config or trigger ops actions, teams need forensic traceability. -**איך OmniRoute פותר את זה:** +**How OmniRoute solves it:** -- רישום ביקורת מגובה SQLite עבור קריאות לכלי MCP -- מסננים לפי כלי, הצלחה/כישלון, מפתח API ועימוד -- טבלת ביקורת לוח המחוונים + נקודות קצה סטטיסטיקות לאוטומציה +- 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. "אני צריך הרשאות MCP בטווחים לכל אינטגרציה"
+🔐 21. "I need scoped MCP permissions per integration"
-ללקוחות שונים צריכה להיות גישה בעלת הרשאות מינימליות לקטגוריות כלים. +Different clients should have least-privilege access to tool categories. -**איך OmniRoute פותר את זה:** +**How OmniRoute solves it:** -- 9 היקפי MCP גרגירים לגישה מבוקרת לכלי -- אכיפה של היקף ונראות בממשק המשתמש של ניהול MCP -- תנוחת ברירת מחדל בטוחה עבור כלי עבודה תפעוליים +- 9 granular MCP scopes for controlled tool access +- Scope enforcement and visibility in MCP management UI +- Safe default posture for operational tooling
-
⚙️ 22. "אני צריך בקרות תפעוליות בלי לפרוס מחדש"
+⚙️ 22. "I need operational controls without redeploying"
-צוותים זקוקים לשינויים מהירים בזמן ריצה במהלך אירועים או אירועי עלות. +Teams need quick runtime changes during incidents or cost events. -**איך OmniRoute פותר את זה:** +**How OmniRoute solves it:** -- החלף הפעלה משולבת ישירות מלוח המחוונים של MCP -- החל פרופילי חוסן מחבילות מדיניות מוגדרות מראש -- אפס את מצב מפסק החשמל מאותו לוח פעולות +- Switch combo activation directly from MCP dashboard +- Apply resilience profiles from pre-defined policy packs +- Reset circuit breaker state from the same operations panel
-
🔄 23. "אני צריך נראות וביטול של מחזור החיים של משימות A2A בשידור חי"
+🔄 23. "I need live A2A task lifecycle visibility and cancellation"
-ללא נראות של מחזור חיים, אירועי משימות הופכים קשים לבדיקה. +Without lifecycle visibility, task incidents become hard to triage. -**איך OmniRoute פותר את זה:** +**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. "אני צריך מדדי סטרימינג פעילים עבור טעינת A2A"
+🌊 24. "I need active stream metrics for A2A load"
-זרימות עבודה בסטרימינג דורשות תובנה תפעולית לגבי חיבורים במקביל וחיבורים חיים. +Streaming workflows require operational insight into concurrency and live connections. -**איך OmniRoute פותר את זה:** +**How OmniRoute solves it:** -- מוני זרמים פעילים משולבים בסטטוס A2A -- חותמת הזמן האחרונה של המשימה וספירות לכל מדינה -- כרטיסי לוח מחוונים A2A לניטור פעולות בזמן אמת +- Active stream counters integrated into A2A status +- Last task timestamp and per-state counts +- A2A dashboard cards for real-time ops monitoring
-
🪪 25. "אני צריך גילוי סוכן סטנדרטי עבור לקוחות"
+🪪 25. "I need standard agent discovery for clients"
-לקוחות חיצוניים ומתזמרים זקוקים למטא-נתונים הניתנים לקריאת מכונה לצורך הצטרפות. +External clients and orchestrators need machine-readable metadata for onboarding. -**איך OmniRoute פותר את זה:** +**How OmniRoute solves it:** -- כרטיס סוכן חשוף ב-`/.well-known/agent.json` -- יכולות ומיומנויות המוצגות בממשק המשתמש לניהול -- API לסטטוס A2A כולל מטא נתונים של גילוי לאוטומציה +- Agent Card exposed at `/.well-known/agent.json` +- Capabilities and skills shown in management UI +- A2A status API includes discovery metadata for automation
-
🧭 26. "אני צריך גילוי פרוטוקול ב-UX של המוצר"
+🧭 26. "I need protocol discoverability in the product UX"
-אם משתמשים לא יכולים לגלות משטחי פרוטוקול, האימוץ והתמיכה יורדים. +If users cannot discover protocol surfaces, adoption and support quality drop. -**איך OmniRoute פותר את זה:** +**How OmniRoute solves it:** -- ערכים בסרגל הצד עבור MCP ו-A2A -- כרטיסיית פרוטוקולים של דף נקודות קצה עם התחלה מהירה ומצב -- קישורים מסקירה כללית ללוחות ניהול ייעודיים +- 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. "אני צריך אימות פרוטוקול מקצה לקצה עם לקוחות אמיתיים"
+🧪 27. "I need end-to-end protocol validation with real clients"
-בדיקות מדומה אינן מספיקות כדי לאמת תאימות פרוטוקול לפני השחרור. +Mock tests are not enough to validate protocol compatibility before release. -**איך OmniRoute פותר את זה:** +**How OmniRoute solves it:** -- חבילת E2E המאתחלת אפליקציה ומשתמשת בהעברת לקוח MCP SDK אמיתית -- בדיקות לקוח A2A לאיתור, לשלוח, להזרים, לקבל ולבטל זרימות -- צלב הצהרות מול ביקורת MCP ומשימות A2A APIs +- 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. "אני צריך צפייה מאוחדת בכל הממשקים"
+📡 28. "I need unified observability across all interfaces"
-פיצול צפיות לפי פרוטוקול יוצר כתמים עיוורים ו-MTTR ארוך יותר. +Splitting observability by protocol creates blind spots and longer MTTR. -**איך OmniRoute פותר את זה:** +**How OmniRoute solves it:** -- לוחות מחוונים/יומנים/ניתוח מאוחדים במוצר אחד -- בריאות + ביקורת + טלמטריית בקשה על פני שכבות OpenAI, MCP ו-A2A -- APIs תפעוליים לסטטוס ואוטומציה +- Unified dashboards/logs/analytics in one product +- Health + audit + request telemetry across OpenAI, MCP, and A2A layers +- Operational APIs for status and automation
-
💼 29. "אני צריך זמן ריצה אחד עבור פרוקסי + כלים + תזמור סוכן"
+💼 29. "I need one runtime for proxy + tools + agent orchestration"
-הפעלת שירותים נפרדים רבים מגדילה את העלות התפעולית ואת מצבי הכשל. +Running many separate services increases operational cost and failure modes. -**איך OmniRoute פותר את זה:** +**How OmniRoute solves it:** -- פרוקסי תואם OpenAI, שרת MCP ושרת A2A בערימה אחת -- אימות משותף, חוסן, מאגר נתונים וצפייה -- מודל מדיניות עקבי בכל משטחי האינטראקציה +- 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
-
-### ספרי הפעלה לדוגמה (מקרי שימוש משולבים)
+### Example Playbooks (Integrated Use Cases)
-**Playbook A: מקסום מנוי בתשלום + גיבוי זול**
+**Playbook A: Maximize paid subscription + cheap backup**
```txt
Combo: "maximize-claude"
@@ -683,7 +694,7 @@ Monthly cost: $20 + small backup spend
Outcome: higher quality, near-zero interruption
```
-**Playbook B: ערימת קידוד בעלות אפסית**
+**Playbook B: Zero-cost coding stack**
```txt
Combo: "free-forever"
@@ -695,7 +706,7 @@ Monthly cost: $0
Outcome: stable free coding workflow
```
-**Playbook C: שרשרת ניצול תמיד 24/7**
+**Playbook C: 24/7 always-on fallback chain**
```txt
Combo: "always-on"
@@ -708,65 +719,132 @@ Combo: "always-on"
Outcome: deep fallback depth for deadline-critical workloads
```
-**Playbook D: סוכן מבצע עם MCP + A2A**
+**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/mcp and /dashboard/a2a
-4) Control incidents with resilience profile + task cancellation
+3) Observe via /dashboard/endpoint (MCP and A2A tabs)
+4) Toggle services via inline status controls
```
---
-## ⚡ התחלה מהירה
+## 🆓 Start Free — Zero Configuration Cost
-**1. התקן ברחבי העולם:**
+> 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 **iFlow** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |
+| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |
+| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |
+| 5 | `/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).
+
+## התחלה מהירה
+
+### 1) Install and run
```bash
npm install -g omniroute
omniroute
```
-🎉 לוח המחוונים נפתח ב-`http://localhost:20128`
+> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:
+>
+> ```bash
+> pnpm install -g omniroute
+> pnpm approve-builds -g # Select all packages → approve
+> omniroute
+> ```
-| פקודה | תיאור |
-| ----------------------- | --------------------------------- |
-| `omniroute` | התחל שרת (יציאת ברירת מחדל 20128) |
-| `omniroute --port 3000` | השתמש ביציאה מותאמת אישית |
-| `omniroute --no-open` | אל תפתח אוטומטית את הדפדפן |
-| `omniroute --help` | הצג עזרה |
+Dashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.
-**2. חבר ספק חינמי:**
+| 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 |
-לוח מחוונים ← ספקים ← התחבר **קוד קלוד** או **אנטי כבידה** ← התחברות OAuth ← בוצע!
+Optional split-port mode:
-**3. השתמש בכלי ה-CLI שלך:**
-
-```
-Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Settings:
- Endpoint: http://localhost:20128/v1
- API Key: [copy from dashboard]
- Model: if/kimi-k2-thinking
+```bash
+PORT=20128 DASHBOARD_PORT=20129 omniroute
+# API: http://localhost:20128/v1
+# Dashboard: http://localhost:20129
```
-**זהו זה!** התחל לקודד עם דגמי AI בחינם.
+### 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
+
+```txt
+Base URL: http://localhost:20128/v1
+API Key: [copy from Endpoint page]
+Model: if/kimi-k2-thinking (or any provider/model prefix)
+```
+
+Works with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.
+
+### 4) Enable and validate protocols (v2.0)
+
+**MCP (for tool-driven operations):**
+
+```bash
+omniroute --mcp
+```
+
+Then connect your MCP client over `stdio` and test tools like:
+
+- `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 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
+PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev
```
---
-## 🐳 דוקר
+## 🐳 Docker
-OmniRoute זמין כתמונת Docker ציבורית ב-[Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
+OmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
-**ריצה מהירה:**
+**Quick run:**
```bash
docker run -d \
@@ -777,7 +855,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**עם קובץ סביבה:**
+**With environment file:**
```bash
# Copy and edit .env first
@@ -792,7 +870,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**שימוש ב-Docker Compose:**
+**Using Docker Compose:**
```bash
# Base profile (no CLI tools)
@@ -802,257 +880,552 @@ docker compose --profile base up -d
docker compose --profile cli up -d
```
-| תמונה | תג | גודל | תיאור |
-| ------------------------ | -------- | ------ | ---------------------- |
-| `diegosouzapw/omniroute` | `latest` | ~250MB | המהדורה היציבה האחרונה |
-| `diegosouzapw/omniroute` | `1.0.3` | ~250MB | גרסה נוכחית |
+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.
+- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.
+- 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` | `1.0.3` | ~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
+### התחלה מהירה
+
```bash
-npm run electron:dev # Development mode
+# 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)
+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
-| שכבה | ספק | עלות | איפוס מכסה | הטוב ביותר עבור |
-| --------------- | ---------------- | ----------------------- | ------------------------ | ------------------------ |
-| **💳 מנוי** | קלוד קוד (פרו) | 20 דולר לחודש | 5 שעות + שבועי | כבר נרשמת |
-| | קודקס (פלוס/פרו) | $20-200 לחודש | 5 שעות + שבועי | משתמשי OpenAI |
-| | Gemini CLI | **חינם** | 180K/Mo + 1K/יום | כֹּל אֶחָד! |
-| | GitHub Copilot | $10-19 לחודש | חודשי | משתמשי GitHub |
-| **🔑 מפתח API** | NVIDIA NIM | **חינם** (1000 קרדיטים) | חד פעמי | בדיקת שכבות חינם |
-| | DeepSeek | תשלום לפי שימוש | אין | המחיר/איכות הטובים ביותר |
-| | גרוק | שכבה חינם + בתשלום | תעריף מוגבל | הסקה מהירה במיוחד |
-| | xAI (Grok) | תשלום לפי שימוש | אין | דגמי גרוק |
-| | מיסטרל | שכבה חינם + בתשלום | תעריף מוגבל | AI אירופאי |
-| | OpenRouter | תשלום לפי שימוש | אין | 100+ דגמים |
-| **💰 זול** | GLM-4.7 | $0.6/1 מיליון | כל יום 10:00 | גיבוי תקציבי |
-| | MiniMax M2.1 | $0.2/1 מיליון | גלגול של 5 שעות | האפשרות הזולה ביותר |
-| | קימי K2 | 9 $ לחודש דירה | 10 מיליון אסימונים לחודש | עלות צפויה |
-| **🆓 חינם** | iFlow | $0 | ללא הגבלה | 8 דגמים חינם |
-| | קוון | $0 | ללא הגבלה | 3 דגמים חינם |
-| | קירו | $0 | ללא הגבלה | קלוד חופשי |
+| 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 |
+| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |
+| | 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** | iFlow | **$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 |
-**💡 טיפ מקצועי:** התחל עם Gemini CLI (180K חינם/חודש) + שילוב של iFlow (ללא הגבלה בחינם) = עלות של $0!
+> 🆕 **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
+iFlow (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
-| תכונה | מה זה עושה |
-| ----------------------------- | -------------------------------------------------------------------------------- |
-| 🎯 **Smart 4-tier Fallback** | מסלול אוטומטי: מנוי → מפתח API → זול → חינם |
-| 📊 **מעקב מכסות בזמן אמת** | ספירת אסימונים חיה + איפוס ספירה לאחור לכל ספק |
-| 🔄 **תרגום פורמט** | OpenAI ↔ קלוד ↔ תאומים ↔ סמן ↔ Kiro חלקה + חיטוי תגובה |
-| 👥 **תמיכה בריבוי חשבונות** | מספר חשבונות לכל ספק עם בחירה חכמה |
-| 🔄 **רענון אסימון אוטומטי** | אסימוני OAuth מתרעננים אוטומטית עם ניסיון חוזר |
-| 🎨 **שילובים מותאמים אישית** | 6 אסטרטגיות: מילוי ראשון, עגול רובין, p2c, אקראי, פחות בשימוש, אופטימיזציה לעלות |
-| 🧩 **דגמים מותאמים אישית** | הוסף כל מזהה דגם לכל ספק |
-| 🌐 **נתב תווים כלליים** | נתב דפוסי `provider/*` לכל ספק באופן דינמי |
-| 🧠 **תקציב חשיבה** | מצבי מעבר, אוטומטי, מותאמים אישית והתאמה למודלים של חשיבה |
-| 🔀 **Model Aliases** | Auto-forward deprecated model IDs to current replacements (built-in + custom) |
-| ⚡ **Background Degradation** | Auto-route background tasks (titles, summaries) to cheaper models |
-| 💬 **הזרקת מערכת מיידית** | הודעת מערכת גלובלית הוחלה בכל הבקשות |
-| 📄 **Responses API** | תמיכה מלאה של OpenAI Responses API (`/v1/responses`) עבור Codex |
+> 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.
-### 🎵 ממשקי API רב-מודאליים
+### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)
-| תכונה | מה זה עושה |
-| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 🖼️ **יצירת תמונות** | `/v1/images/generations` — 4 ספקים, 9+ דגמים |
-| 📐 **הטבעות** | `/v1/embeddings` — 6 ספקים, 9+ דגמים |
-| 🎤 **תמלול אודיו** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |
-| 🔊 **טקסט לדיבור** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) |
-| 🛡️ **מנחים** | `/v1/moderations` — בדיקות בטיחות תוכן |
-| 🔀 **דירוג מחדש** | `/v1/rerank` — דירוג מחדש של רלוונטיות המסמך |
+| 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 |
-### 🛡️ חוסן וביטחון
+### 🟢 IFLOW MODELS (Free OAuth — No Credit Card)
-| תכונה | מה זה עושה |
-| ------------------------------------ | ---------------------------------------------------------------------------- |
-| 🔌 **מפסק מעגלים** | פתיחה/סגירה אוטומטית לכל ספק עם ערכי סף הניתנים להגדרה |
-| 🛡️ **עדר נגד רעמים** | Mutex + מגבלת קצב סמפור עבור ספקי מפתח API |
-| 🧠 **מטמון סמנטי** | מטמון דו-שכבתי (חתימה + סמנטי) מפחית את העלות והשהייה |
-| ⚡ **בקש אימפוטנציה** | חלון ביטול 5s עבור בקשות כפולות |
-| 🔒 **זיוף טביעות אצבע TLS** | עוקף זיהוי בוט מבוסס TLS באמצעות wreq-js |
-| 🌐 **סינון IP** | רשימת הרשאות/רשימת חסימות עבור בקרת גישה ל-API |
-| 📊 **מגבלות תעריפים הניתנות לעריכה** | RPM ניתן להגדרה, פער מינימלי ומקסימום במקביל ברמת המערכת |
-| 💾 **Rate Limit Persistence** | Learned limits survive restarts via SQLite with 60s debounce + 24h staleness |
-| 🔄 **Token Refresh Resilience** | Per-provider circuit breaker (5 fails→30min) + 30s timeout per attempt |
-| 🛡 **הגנת נקודת קצה API** | Auth gating + חסימת ספק עבור נקודת הקצה `/models` |
-| 🔒 **נראות פרוקסי** | תגים מקודדים בצבע: 🟢 גלובלי, 🟡 ספק, 🔵 לכל חיבור עם תצוגת IP |
-| 🌐 **תצורת פרוקסי בשלוש רמות** | הגדר פרוקסי ברמה גלובלית, לכל ספק או לכל חיבור |
+| 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 |
-### 📊 יכולת תצפית וניתוח
+### 🟡 QWEN MODELS (Device Code Auth)
-| תכונה | מה זה עושה |
-| -------------------------------- | ---------------------------------------------------------------------- |
-| 📝 **בקש רישום** | מצב ניפוי באגים עם יומני בקשות/תגובות מלאים |
-| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |
-| 💾 **יומני פרוקסי של SQLite** | יומני פרוקסי מתמשכים שורדים אתחול מחדש של השרת |
-| 📊 **לוח המחוונים של אנליטיקס** | מופעל מחדש ב-Recharts: כרטיסי סטטיסטיקה, טבלת שימוש במודל, טבלת ספקים |
-| 📈 **מעקב התקדמות** | הצטרפות לאירועי התקדמות SSE לסטרימינג |
-| 🧪 **LM Evaluations** | בדיקת סט זהב עם 4 אסטרטגיות התאמה |
-| 🔍 **בקש טלמטריה** | צבירת זמן אחזור p50/p95/p99 + מעקב אחר X-Request-Id |
-| 📋 **לוח מחוונים יומני** | עמוד מאוחד בן 4 לשוניות: יומני בקשות, יומני פרוקסי, יומני ביקורת, מסוף |
-| 🖥️ **מציג יומן מסוף** | מציג בסגנון טרמינל בזמן אמת עם מסנן רמות, חיפוש, גלילה אוטומטית |
-| 📑 **רישום מבוסס קבצים** | מיירט מסוף לוכד את כל הפלט לקובץ יומן JSON עם סיבוב |
-| 🏥 **לוח מחוונים לבריאות** | זמן פעילות מערכת, מצבי מפסק זרם, נעילות, סטטיסטיקות מטמון |
-| 💰 **מעקב עלויות** | ניהול תקציב + תצורת תמחור לפי דגם |
+| 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) |
-### ☁️ פריסה וסנכרון
+### 🟣 GEMINI CLI (Google OAuth)
-| תכונה | מה זה עושה |
-| ---------------------------------- | --------------------------------------------------------------------- |
-| 💾 **סנכרון ענן** | סנכרון תצורה בין מכשירים באמצעות Cloudflare Workers |
-| 🌐 **פרוס בכל מקום** | Localhost, VPS, Docker, Cloudflare Workers |
-| 🔑 **ניהול מפתחות API** | צור, סובב והיקף מפתחות API לכל ספק |
-| 🧙 **אשף העלייה למטוס** | הגדרה מודרכת בת 4 שלבים למשתמשים חדשים |
-| 🔧 **לוח המחוונים של כלי CLI** | הגדר בלחיצה אחת את Claude, Codex, Cline, OpenClaw, Kilo, Antigravity |
-| 🔄 **גיבויים של DB** | גיבוי, שחזור, ייצוא וייבוא אוטומטי עבור כל ההגדרות |
-| 🌐 **בינלאומיות** | i18n מלא עם next-intl — תמיכה באנגלית + פורטוגזית (ברזיל) |
-| 🌍 **בורר שפה** | סמל גלובוס בכותרת למעבר שפה בזמן אמת (🇺🇸/🇧🇷) |
-| 🧹 **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 |
-| 📂 **ספריית נתונים מותאמים אישית** | `DATA_DIR` env var כדי לעקוף את ברירת המחדל `~/.omniroute` נתיב אחסון |
+| Model | Prefix | Limit | Rate Limit |
+| ------------------------ | ------ | --------------------------- | ------------- |
+| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |
+| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |
+
+### ⚫ 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
+> iFlow (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 v2.0 is built as an operational platform, not just a relay proxy.
+
+### 🆕 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 Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |
+| 🤖 **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 (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) |
+| 🤝 **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** | 9 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 combo, apply resilience profiles, reset breakers from one control surface |
+
+### 🧠 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** | 6 balancing strategies + fallback chain control |
+| 🌐 **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) |
+| 💬 **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 |
+| ----------------------------------- | -------------------------------------------------------------------------------------- |
+| 🔌 **Circuit Breakers** | Per-model trip/recover with threshold controls |
+| 🎯 **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 |
+| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |
+| 🔑 **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 |
+
+### 📊 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 |
+| 📋 **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 |
+
+### ☁️ Deployment & Platform
+
+| Feature | What It Does |
+| ----------------------------- | --------------------------------------------------------- |
+| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |
+| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |
+| 💾 **Cloud Sync** | Configuration sync via cloud worker |
+| 🔄 **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 |
+
+### Feature Deep Dive
+
+#### Smart fallback with practical cost control
+
+```txt
+Combo: "my-coding-stack"
+ 1. cc/claude-opus-4-6
+ 2. nvidia/llama-3.3-70b
+ 3. glm/glm-4.7
+ 4. if/kimi-k2-thinking
+```
+
+When quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.
+
+#### 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)
+
+#### 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)
🚀 30. "אני צריך לשלוח זרימות עבודה סוכניות ללא התפשטות קוד דבק"
+🚀 30. "I need to ship agentic workflows without glue-code sprawl"
-צוותים מאבדים מהירות בעת תפירת שירותים ותסריטים אד-הוק מרובים. +Teams lose velocity when stitching multiple ad-hoc services and scripts. -**איך OmniRoute פותר את זה:** +**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)
-` בלוקים → `reasoning_content` למודלים חושבים
-- **פלט מובנה** — `json_schema` → `responseMimeType`/`responseSchema` של Gemini
-
-### 👥 תמיכה בריבוי חשבונות
-
-- הוסף מספר חשבונות לכל ספק
-- ניתוב סבב אוטומטי או מבוסס עדיפות
-- חזרה לחשבון הבא כאשר אחד מגיע למכסה
-
-### 🔄 רענון אסימון אוטומטי
-
-- אסימוני OAuth מתרעננים אוטומטית לפני פקיעת התוקף
-- אין צורך באימות מחדש ידני
-- חוויה חלקה בכל הספקים
-
-### 🎨 שילובים מותאמים אישית
-
-- צור שילובי דגמים ללא הגבלה
-- 6 אסטרטגיות: מילוי ראשון, עגול, כוח משתי בחירות, אקראי, פחות בשימוש, אופטימיזציית עלות
-- שתף שילובים בין מכשירים עם Cloud Sync
-
-### 🏥 לוח מחוונים לבריאות
-
-- מצב מערכת (זמן פעילות, גרסה, שימוש בזיכרון)
-- מצבי מפסק לכל ספק (סגור/פתוח/חצי פתוח)
-- מצב מגבלת תעריף ונעילה אקטיבית
-- סטטיסטיקת מטמון חתימה
-- טלמטריית אחזור (p50/p95/p99) + מטמון פקודות
-- אפס מצב בריאותי בלחיצה אחת
-
-### 🔧 מגרש משחקים למתרגמים
-
-OmniRoute כולל מגרש משחקי מתרגמים מובנה רב עוצמה עם **4 מצבים** לניפוי באגים, בדיקה וניטור תרגומי API:
-
-| מצב | תיאור |
-| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **💻 מגרש משחקים** | תרגום פורמט ישיר - הדבק כל גוף בקשת API וראה באופן מיידי כיצד OmniRoute מתרגם אותו בין פורמטים של ספקים (OpenAI ↔ Claude ↔ Gemini ↔ Responses API). כולל תבניות לדוגמה וזיהוי אוטומטי של פורמטים. |
-| **💬 בודק צ'אט** | שלח בקשות צ'אט אמיתיות דרך OmniRoute וראה את המסלול המלא הלוך ושוב: הקלט שלך, הבקשה המתורגמת, תגובת הספק והתגובה המתורגמת חזרה. לא יסולא בפז עבור אימות ניתוב משולב. |
-| **🧪 ספסל מבחן** | מצב בדיקת אצווה - הגדירו מקרי בדיקה מרובים עם תשומות ותפוקות צפויות שונות, הפעל את כולם בבת אחת והשווה תוצאות בין ספקים ודגמים. |
-| **📱 צג חי** | ניטור בקשות בזמן אמת - צפה בבקשות נכנסות כשהן זורמות דרך OmniRoute, ראה תרגומי פורמטים המתרחשים בשידור חי וזיהוי בעיות באופן מיידי. |
-
-**גישה:** לוח מחוונים ← מתרגם (סרגל צד)
-
-### 💾 סנכרון ענן
-
-- סנכרון ספקים, שילובים והגדרות בין מכשירים
-- סנכרון רקע אוטומטי
-- אחסון מוצפן מאובטח
+- `GET /api/mcp/status`
+- `GET /api/mcp/tools`
+- `GET /api/mcp/audit`
+- `GET /api/mcp/audit/stats`
-## 🧪 הערכות (הערכות)
+📖 פרטי תכונה
+🧩 MCP Setup (Model Context Protocol)
-### 🎯 4 שכבות סתירה חכמה +Start MCP transport in stdio mode: -צור שילובים עם נפילה אוטומטית: - -``` -Combo: "my-coding-stack" - 1. cc/claude-opus-4-6 (your subscription) - 2. nvidia/llama-3.3-70b (free NVIDIA API) - 3. glm/glm-4.7 (cheap backup, $0.6/1M) - 4. if/kimi-k2-thinking (free fallback) - -→ Auto switches when quota runs out or errors occur +```bash +omniroute --mcp ``` -### 📊 מעקב מכסות בזמן אמת +Recommended validation flow: -- צריכת אסימונים לכל ספק -- אפס ספירה לאחור (5 שעות, יומי, שבועי) -- הערכת עלויות עבור שכבות בתשלום -- דוחות הוצאות חודשיים +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: -תרגום חלק בין פורמטים: - -- **OpenAI** ↔ **קלוד** ↔ **תאומים** ↔ **תגובות OpenAI** -- כלי ה-CLI שלך שולח פורמט OpenAI → OmniRoute מתרגם → הספק מקבל פורמט מקורי -- עובד עם כל כלי התומך בנקודות קצה מותאמות אישית של OpenAI -- **חיטוי תגובה** - מסיר שדות לא סטנדרטיים לצורך תאימות קפדנית של OpenAI SDK -- **נורמליזציה של תפקידים** — `developer` → `system` עבור לא-OpenAI; `system` → `user` עבור דגמי GLM/ERNIE -- **חילוץ תג חשיבה** — `
+
🤝 A2A Setup (Agent2Agent)
-OmniRoute כולל מסגרת הערכה מובנית לבדיקת איכות תגובת LLM מול סט מוזהב. גש אליו דרך **Analytics → Evals** בלוח המחוונים. +Discover the agent: -### סט מוזהב מובנה +```bash +curl http://localhost:20128/.well-known/agent.json +``` -ה-"OmniRoute Golden Set" הנטען מראש מכיל 10 מקרי בדיקה המכסים: +Send a task: -- ברכות, מתמטיקה, גיאוגרפיה, יצירת קוד -- תאימות לפורמט JSON, תרגום, סימון -- סירוב בטיחותי (תוכן מזיק), ספירה, היגיון בוליאני +```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."}]}}' +``` -### אסטרטגיות הערכה +Manage lifecycle: -| אסטרטגיה | תיאור | דוגמה | -| ---------- | ------------------------------------------ | -------------------------------- | -| `exact` | הפלט חייב להתאים בדיוק | `"4"` | -| `contains` | הפלט חייב להכיל תת מחרוזת (לא תלוי רישיות) | `"Paris"` | -| `regex` | הפלט חייב להתאים לדפוס הרקס | `"1.*2.*3"` | -| `custom` | פונקציית JS מותאמת מחזירה true/false | `(output) => output.length > 10` | +- `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: + +```bash +npm run test:protocols:e2e +``` + +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) ```bash Dashboard → Providers → Connect Claude Code @@ -1065,9 +1438,9 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**טיפ מקצוען:** השתמש ב-Opus למשימות מורכבות, בסונט למהירות. OmniRoute עוקב אחר מכסה לכל דגם! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! -### OpenAI Codex (פלוס/פרו) +### OpenAI Codex (Plus/Pro) ```bash Dashboard → Providers → Connect Codex @@ -1079,7 +1452,24 @@ Models: cx/gpt-5.1-codex-max ``` -### Gemini CLI (180K בחינם לחודש!) +#### 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). + +### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -1091,7 +1481,7 @@ Models: gc/gemini-2.5-pro ``` -**הערך הטוב ביותר:** שכבת חינם ענקית! השתמש בזה לפני שכבות בתשלום. +**Best Value:** Huge free tier! Use this before paid tiers. ### GitHub Copilot @@ -1109,88 +1499,88 @@ Models:
-
🔑 ספקי מפתח API
+🔑 API Key Providers
-### NVIDIA NIM (1000 קרדיטים בחינם!) +### NVIDIA NIM (FREE developer access — 70+ models) -1. הירשם: [build.nvidia.com](https://build.nvidia.com) -2. קבל מפתח API בחינם (כולל 1000 קרדיטים להסקה) -3. לוח מחוונים ← הוסף ספק ← NVIDIA NIM: - - מפתח API: `nvapi-your-key` +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` -**דגמים:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct` ועוד 50+ +**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more -**טיפ מקצועי:** API תואם OpenAI - עובד בצורה חלקה עם תרגום הפורמט של OmniRoute! +**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation! ### DeepSeek -1. הירשם: [platform.deepseek.com](https://platform.deepseek.com) -2. קבל מפתח API -3. לוח מחוונים ← הוסף ספק ← DeepSeek +1. Sign up: [platform.deepseek.com](https://platform.deepseek.com) +2. Get API key +3. Dashboard → Add Provider → DeepSeek -**דגמים:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` +**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` -### Groq (רמה חינם זמינה!) +### Groq (Free Tier Available!) -1. הירשם: [console.groq.com](https://console.groq.com) -2. קבל מפתח API (כלול שכבת חינם) -3. לוח מחוונים ← הוסף ספק ← Groq +1. Sign up: [console.groq.com](https://console.groq.com) +2. Get API key (free tier included) +3. Dashboard → Add Provider → Groq -**דגמים:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` +**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` -**טיפ מקצועי:** הסקה מהירה במיוחד - הטוב ביותר לקידוד בזמן אמת! +**Pro Tip:** Ultra-fast inference — best for real-time coding! -### OpenRouter (100+ דגמים) +### OpenRouter (100+ Models) -1. הירשם: [openrouter.ai](https://openrouter.ai) -2. קבל מפתח API -3. לוח מחוונים ← הוסף ספק ← OpenRouter +1. Sign up: [openrouter.ai](https://openrouter.ai) +2. Get API key +3. Dashboard → Add Provider → OpenRouter -**דגמים:** גישה ל-100+ דגמים מכל הספקים הגדולים באמצעות מפתח API יחיד. +**Models:** Access 100+ models from all major providers through a single API key.
-
💰 ספקים זולים (גיבוי)
+💰 Cheap Providers (Backup)
-### GLM-4.7 (איפוס יומי, $0.6/1 מיליון) +### GLM-4.7 (Daily reset, $0.6/1M) -1. הירשם: [Zhipu AI](https://open.bigmodel.cn/) -2. קבל מפתח API מ-Coding Plan -3. לוח מחוונים ← הוסף מפתח API: - - ספק: `glm` - - מפתח API: `your-key` +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` -**השתמש:** `glm/glm-4.7` +**Use:** `glm/glm-4.7` -**טיפ למקצוענים:** תוכנית קידוד מציעה מכסה של 3× בעלות של 1/7! איפוס כל יום 10:00 בבוקר. +**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -### MiniMax M2.1 (איפוס של 5 שעות, $0.20/1 מיליון דולר) +### MiniMax M2.1 (5h reset, $0.20/1M) -1. הירשם: [MiniMax](https://www.minimax.io/) -2. קבל מפתח API -3. לוח מחוונים ← הוסף מפתח API +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key +3. Dashboard → Add API Key -**השתמש:** `minimax/MiniMax-M2.1` +**Use:** `minimax/MiniMax-M2.1` -**טיפ מקצועי:** האפשרות הזולה ביותר להקשר ארוך (1 מיליון אסימונים)! +**Pro Tip:** Cheapest option for long context (1M tokens)! -### Kimi K2 (דירה של $9 לחודש) +### Kimi K2 ($9/month flat) -1. הירשם: [Moonshot AI](https://platform.moonshot.ai/) -2. קבל מפתח API -3. לוח מחוונים ← הוסף מפתח API +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key +3. Dashboard → Add API Key -**השתמש:** `kimi/kimi-latest` +**Use:** `kimi/kimi-latest` -**טיפ מקצועי:** 9$ קבוע לחודש עבור 10 מיליון אסימונים = 0.90$/1 מיליון עלות אפקטיבית! +**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
-
🆓 ספקים בחינם (גיבוי חירום)
+🆓 FREE Providers (Emergency Backup)
-### iFlow (8 דגמים בחינם) +### iFlow (5 FREE models via OAuth) ```bash Dashboard → Connect iFlow @@ -1205,7 +1595,7 @@ Models: if/deepseek-r1 ``` -### Qwen (3 דגמים בחינם) +### Qwen (4 FREE models via Device Code) ```bash Dashboard → Connect Qwen @@ -1217,7 +1607,7 @@ Models: qw/qwen3-coder-flash ``` -### קירו (קלוד בחינם) +### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro @@ -1232,9 +1622,9 @@ Models:
-
🎨 צור שילובים
+🎨 Create Combos
-### דוגמה 1: הגדלת מנוי ← גיבוי זול +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -1248,7 +1638,7 @@ Models: Use in CLI: premium-coding ``` -### דוגמה 2: חינם בלבד (עלות אפס) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -1263,9 +1653,9 @@ Cost: $0 forever!
-
---
-## 🐛 פתרון בעיות
+## פתרון בעיות
🔧 שילוב CLI
+🔧 CLI Integration
-### סמן IDE +### Cursor IDE ``` Settings → Models → Advanced: @@ -1274,9 +1664,9 @@ Settings → Models → Advanced: Model: cc/claude-opus-4-6 ``` -### קלוד קוד +### Claude Code -השתמש בדף **כלי CLI** בלוח המחוונים עבור תצורה בלחיצה אחת, או ערוך את `~/.claude/settings.json` באופן ידני. +Use the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually. ### Codex CLI @@ -1289,13 +1679,13 @@ codex "your prompt" ### OpenClaw -**אפשרות 1 - לוח מחוונים (מומלץ):** +**Option 1 — Dashboard (recommended):** ``` Dashboard → CLI Tools → OpenClaw → Select Model → Apply ``` -**אפשרות 2 — ידני:** ערוך `~/.openclaw/openclaw.json`: +**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`: ```json { @@ -1311,7 +1701,7 @@ Dashboard → CLI Tools → OpenClaw → Select Model → Apply } ``` -> **הערה:** OpenClaw עובד רק עם OmniRoute מקומי. השתמש ב-`127.0.0.1` במקום ב-`localhost` כדי להימנע מבעיות ברזולוציה של IPv6. +> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues. ### Cline / Continue / RooCode @@ -1323,108 +1713,243 @@ Settings → API Configuration: 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. +
-
-- **זמן ריצה**: Node.js 18–22 LTS (⚠️ Node.js 24+ **לא נתמך** - `better-sqlite3` קבצים בינאריים מקוריים אינם תואמים)
-- **שפה**: TypeScript 5.9 — **100% TypeScript** על פני `src/` ו`open-sse/` (v1.0.6)
-- **מסגרת**: Next.js 16 + React 19 + Tailwind CSS 4
-- **מסד נתונים**: LowDB (JSON) + SQLite (מצב תחום + יומני proxy)
-- **סטרימינג**: אירועים שנשלחו על ידי שרת (SSE)
-- **אישור**: OAuth 2.0 (PKCE) + JWT + מפתחות API
-- **בדיקות**: רץ מבחן Node.js (בדיקות 368+ יחידות)
-- **CI/CD**: פעולות GitHub (פרסום אוטומטי של npm + Docker Hub בשחרור)
-- **אתר**: [omniroute.online](https://omniroute.online)
-- **חבילה**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
-- **דוקר**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
-- **חוסן**: מפסק מעגלים, גיבוי אקספוננציאלי, עדר נגד רעמים, זיוף TLS
-
----
-
-## 📖 תיעוד
-
-| מסמך | תיאור |
-| -------------------------------------------- | ----------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | ספקים, שילובים, שילוב CLI, פריסה |
-| [API Reference](docs/API_REFERENCE.md) | כל נקודות הקצה עם דוגמאות |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | בעיות ופתרונות נפוצים |
-| [Architecture](docs/ARCHITECTURE.md) | ארכיטקטורת מערכת ופנים |
-| [Contributing](CONTRIBUTING.md) | מערך פיתוח והנחיות |
-| [OpenAPI Spec](docs/openapi.yaml) | מפרט OpenAPI 3.0 |
-| [Security Policy](SECURITY.md) | דיווח על פגיעות ונהלי אבטחה |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | מדריך שלם: הגדרות VM + nginx + Cloudflare |
-| [Features Gallery](docs/FEATURES.md) | סיור חזותי בלוח המחוונים עם צילומי מסך |
-
-### 📸 תצוגה מקדימה של לוח המחוונים
+## 🛠️ Tech Stack
לחץ כדי להרחיב את המדריך לפתרון בעיות
+Click to expand troubleshooting guide
-**"מודל השפה לא סיפק הודעות"** +**"Language model did not provide messages"** -- מיצתה מכסת הספק ← בדוק את עוקב המכסות של לוח המחוונים -- פתרון: השתמש ב-combo fallback או עבור לשכבה זולה יותר +- Provider quota exhausted → Check dashboard quota tracker +- Solution: Use combo fallback or switch to cheaper tier -**הגבלת תעריפים** +**Rate limiting** -- מכסת מנויים נגמרת ← Fallback ל-GLM/MiniMax -- הוסף שילוב: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Subscription quota out → Fallback to GLM/MiniMax +- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -**פג תוקפו של אסימון OAuth** +**OAuth token expired** -- רענון אוטומטי על ידי OmniRoute -- אם הבעיות נמשכות: לוח מחוונים ← ספק ← התחבר מחדש +- Auto-refreshed by OmniRoute +- If issues persist: Dashboard → Provider → Reconnect -**עלויות גבוהות** +**High costs** -- בדוק סטטיסטיקת שימוש בלוח המחוונים ← עלויות -- החלף את הדגם הראשי ל-GLM/MiniMax -- השתמש בשכבה חינמית (Gemini CLI, iFlow) עבור משימות לא קריטיות +- Check usage stats in Dashboard → Costs +- Switch primary model to GLM/MiniMax +- Use free tier (Gemini CLI, iFlow) for non-critical tasks -**לוח המחוונים נפתח ביציאה שגויה** +**Dashboard/API ports are wrong** -- הגדר `PORT=20128` ו`NEXT_PUBLIC_BASE_URL=http://localhost:20128` +- `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** -- אמת `BASE_URL` נקודות למופע הריצה שלך -- אמת `CLOUD_URL` נקודות לנקודת הקצה הצפויה שלך בענן -- שמור על ערכי `NEXT_PUBLIC_*` מיושרים עם ערכי צד השרת +- 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** -- בדוק את `INITIAL_PASSWORD` ב-`.env` -- אם לא מוגדרת, סיסמת החלפה היא `123456` +- Check `INITIAL_PASSWORD` in `.env` +- If unset, fallback password is `123456` -**ללא יומני בקשות** +**No request logs** -- הגדר `ENABLE_REQUEST_LOGS=true` ב-`.env` +- Set `ENABLE_REQUEST_LOGS=true` in `.env` -**בדיקת חיבור מראה "לא חוקי" עבור ספקים תואמי OpenAI** +**Connection test shows "Invalid" for OpenAI-compatible providers** -- ספקים רבים אינם חושפים נקודת קצה `/models` -- OmniRoute v1.0.6+ כולל אימות חוזר באמצעות השלמת צ'אט -- ודא שכתובת האתר הבסיסית כוללת את הסיומת `/v1` +- 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 +### 🔐 OAuth on a Remote Server + -> **⚠️ חשוב עבור שימוש ב-OmniRoute עם מרחוק VPS/Docker/שרת** +> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server** -### האם אפשר לעשות אנטי כבידה / CLI מזל תאומים על שירותים מרוחקים? +#### Why does Antigravity / Gemini CLI OAuth fail on remote servers? -שימוש ב-**Antigravity** ו-**Gemini CLI** בשימוש ב-**Google OAuth 2.0** עבור אוטנטיקה. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo. +The **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console. -As credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (לדוגמה: `https://omniroute.meuservidor.com`), o Google rejeita a autenticação com: +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 ``` -### פתרון: הגדר את התצורה של OAuth +#### Solution: Configure your own OAuth credentials -קרא בדיוק את **OAuth 2.0 Client ID** ללא Google Cloud Console com a URI do seu service. +You need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI. -#### פסו אפס +#### Step-by-step -**1. גישה ל-Google Cloud Console** +**1. Open Google Cloud Console** -אברה: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) +Go to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) -**2. Crie um novo OAuth 2.0 מזהה לקוח** +**2. Create a new OAuth 2.0 Client ID** -- לחץ על **"+ צור אישורים"** → **"זיהוי לקוח OAuth"** -- טיפו דה אפליקטיבי: **"יישום אינטרנט"** -- שם: escolha qualquer nome (לדוגמה: `OmniRoute Remote`) +- Click **"+ Create Credentials"** → **"OAuth client ID"** +- Application type: **"Web application"** +- Name: anything you like (e.g. `OmniRoute Remote`) -**3. Adicone ככתובות URI מורשות להפניה מחדש** +**3. Add Authorized Redirect URIs** -אין קמפו **"כתובות URI מורשות להפניה מחדש"**, adicione: +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 + +# For Gemini CLI: +GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com +GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +``` + +**6. Restart OmniRoute** + +```bash +# npm: +npm run dev + +# Docker: +docker restart omniroute +``` + +**7. Try connecting again** + +Dashboard → Providers → Antigravity (or Gemini CLI) → OAuth + +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. + +--- + +
+
---
-## 🛠️
+🇧🇷 Versão em Português
+ +#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos? + +Os provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo. + +As credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticação com: + +``` +Error 400: redirect_uri_mismatch +``` + +#### Solução: Configure suas próprias credenciais OAuth + +Você precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor. + +#### Passo a passo + +**1. Acesse o Google Cloud Console** + +Abra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) + +**2. Crie um novo OAuth 2.0 Client ID** + +- Clique em **"+ Create Credentials"** → **"OAuth client ID"** +- Tipo de aplicativo: **"Web application"** +- Nome: escolha qualquer nome (ex: `OmniRoute Remote`) + +**3. Adicione as Authorized Redirect URIs** + +No campo **"Authorized redirect URIs"**, adicione: ``` https://seu-servidor.com/callback ``` -> Substitua `seu-servidor.com` pelo domínio או IP do seu servidor (כולל א porta se necessário, למשל: `http://45.33.32.156:20128/callback`). +> Substitua `seu-servidor.com` pelo domínio ou IP do seu servidor (inclua a porta se necessário, ex: `http://45.33.32.156:20128/callback`). -**4. שמור את העותק כ-credenciais** +**4. Salve e copie as credenciais** -אפóס קריאר, o Google mostrará o **זיהוי לקוח** או **סוד לקוח**. +Após criar, o Google mostrará o **Client ID** e o **Client Secret**. -**5. הגדר כ-variáveis de ambiente** +**5. Configure as variáveis de ambiente** No seu `.env` (ou nas variáveis de ambiente do Docker): @@ -1451,151 +1976,145 @@ docker restart omniroute **7. Tente conectar novamente** -לוח מחוונים ← ספקים ← אנטי כבידה (או Gemini CLI) ← OAuth +Dashboard → Providers → Antigravity (ou Gemini CLI) → OAuth -Agora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e autenticação funcionará. +Agora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará. --- -### זמני פתרון לעקיפת הבעיה +#### Workaround temporário (sem configurar credenciais próprias) Se não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**: 1. O OmniRoute abrirá a URL de autorização do Google 2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto) -3. **העתק כתובת URL מלאה** da barra de endereço do seu דפדפן (mesmo que a página não carregue) +3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue) 4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute -5. לחץ על **"התחבר"** +5. Clique em **"Connect"** -> פתרון עקיפת הבעיה או קוד אוטומטי של כתובת ה-URL או עצמאית להפנות את החשבון או לא. +> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.
-
---
-## 🗺️
+## תיעוד
-ל-OmniRoute יש **210+ תכונות מתוכננות** לאורך שלבי פיתוח מרובים. להלן תחומי המפתח:
-
-| קטגוריה | תכונות מתוכננות | הבהרה |
-| ---------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
-| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |
-| 🧠 **ניתוב ומודיעין** | 25+ | ניתוב עם זמן האחזור הנמוך ביותר, ניתוב מבוסס תגים, בדיקה מוקדמת של מכסה, בחירת חשבון P2C |
-| 🔒 **אבטחה ותאימות** | 20+ | הקשחת SSRF, הסוואה של אישורים, הגבלת קצב לכל נקודת קצה, היקף מפתח ניהול |
-| 📊 **צפיות** | 15+ | אינטגרציה של OpenTelemetry, ניטור מכסות בזמן אמת, מעקב עלויות לכל דגם |
-| 🔄 **שילובי ספקים** | 20+ | רישום מודלים דינמיים, צינון ספקים, Codex מרובה חשבונות, ניתוח מכסת Copilot |
-| ⚡ **ביצועים** | 15+ | שכבת מטמון כפולה, מטמון הנחיה, מטמון תגובה, סטרימינג Keepalive, API אצווה |
-| 🌐 **מערכת אקולוגית** | 10+ | WebSocket API, טעינה חוזרת של תצורה, חנות תצורה מבוזרת, מצב מסחרי |
-
-### 🔜 בקרוב
-
-- 🔗 **שילוב OpenCode** - תמיכה בספק מקורי עבור IDE קידוד AI של OpenCode
-- 🔗 **TRAE Integration** — תמיכה מלאה במסגרת הפיתוח של TRAE AI
-- 📦 **אצווה API** - עיבוד אצווה אסינכרוני עבור בקשות בכמות גדולה
-- 🎯 **ניתוב מבוסס תגים** — בקשות ניתוב המבוססות על תגים ומטא נתונים מותאמים אישית
-- 💰 **אסטרטגיית העלות הנמוכה ביותר** — בחר אוטומטית את הספק הזמין הזול ביותר
-
-> 📝 מפרטי תכונה מלאים זמינים ב-[link](docs/new-features/) (217 מפרטים מפורטים)
+| Document | Description |
+| ---------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 16 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/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
+| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
-## 👥 תורמים
+## 🗺️ Roadmap
+
+OmniRoute has **210+ 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, P2C account selection |
+| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |
+| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |
+| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider 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
[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
-### כיצד לתרום
+### How to Contribute
-1. מזלג את המאגר
-2. צור את ענף התכונה שלך (`git checkout -b feature/amazing-feature`)
-3. בצע את השינויים שלך (`git commit -m 'Add amazing feature'`)
-4. דחף לסניף (`git push origin feature/amazing-feature`)
-5. פתחו בקשת משיכה
+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
-ראה [CONTRIBUTING.md](CONTRIBUTING.md) להנחיות מפורטות.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
-### שחרור גרסה חדשה
+### Releasing a New Version
```bash
# Create a release — npm publish happens automatically
-gh release create v1.0.6 --title "v1.0.6" --generate-notes
+gh release create v2.0.0 --title "v2.0.0" --generate-notes
```
---
-## 📊 היסטוריית כוכבים
+## 📊 Star History
## Stargazers over time
## [](https://starchart.cc/diegosouzapw/OmniRoute)
-## 🙏 תודות
+## 🙏 Acknowledgments
-תודה מיוחדת ל**[9router](https://github.com/decolua/9router)** מאת **[decolua](https://github.com/decolua)** - הפרויקט המקורי שהיווה השראה למזלג הזה. OmniRoute בונה על הבסיס המדהים הזה עם תכונות נוספות, ממשקי API רב-מודאליים ושכתוב מלא של TypeScript.
+Special thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.
-תודה מיוחדת ל**[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** - היישום המקורי של Go שימש השראה ליציאת JavaScript הזו.
+Special thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.
---
-## 📄 רישיון
+## רישיון
-רישיון MIT - ראה [LICENSE](LICENSE) לפרטים.
+MIT License - see [LICENSE](LICENSE) for details.
---
לחץ כדי לראות צילומי מסך של לוח המחוונים
+Click to expand tech stack details
-| עמוד | צילום מסך | -| --------------- | ------------------------------------------------- | -| **ספקים** |  | -| **שילובים** |  | -| **אנליטיקה** |  | -| **בריאות** |  | -| **מתרגם** |  | -| **הגדרות** |  | -| **כלי CLI** |  | -| **יומני שימוש** |  | -| **נקודת קצה** |  | +- **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**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions) +- **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
- נבנה עם ❤️ למפתחים שמקודדים 24/7
+ Built with ❤️ for developers who code 24/7
omniroute.online
+
diff --git a/docs/i18n/he/docs/FEATURES.md b/docs/i18n/he/docs/FEATURES.md
new file mode 100644
index 0000000000..bdf0c52381
--- /dev/null
+++ b/docs/i18n/he/docs/FEATURES.md
@@ -0,0 +1,145 @@
+# OmniRoute — Dashboard Features Gallery (עברית)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/FEATURES.md) · 🇪🇸 [es](../../es/docs/FEATURES.md) · 🇫🇷 [fr](../../fr/docs/FEATURES.md) · 🇩🇪 [de](../../de/docs/FEATURES.md) · 🇮🇹 [it](../../it/docs/FEATURES.md) · 🇷🇺 [ru](../../ru/docs/FEATURES.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FEATURES.md) · 🇯🇵 [ja](../../ja/docs/FEATURES.md) · 🇰🇷 [ko](../../ko/docs/FEATURES.md) · 🇸🇦 [ar](../../ar/docs/FEATURES.md) · 🇮🇳 [in](../../in/docs/FEATURES.md) · 🇹🇭 [th](../../th/docs/FEATURES.md) · 🇻🇳 [vi](../../vi/docs/FEATURES.md) · 🇮🇩 [id](../../id/docs/FEATURES.md) · 🇲🇾 [ms](../../ms/docs/FEATURES.md) · 🇳🇱 [nl](../../nl/docs/FEATURES.md) · 🇵🇱 [pl](../../pl/docs/FEATURES.md) · 🇸🇪 [sv](../../sv/docs/FEATURES.md) · 🇳🇴 [no](../../no/docs/FEATURES.md) · 🇩🇰 [da](../../da/docs/FEATURES.md) · 🇫🇮 [fi](../../fi/docs/FEATURES.md) · 🇵🇹 [pt](../../pt/docs/FEATURES.md) · 🇷🇴 [ro](../../ro/docs/FEATURES.md) · 🇭🇺 [hu](../../hu/docs/FEATURES.md) · 🇧🇬 [bg](../../bg/docs/FEATURES.md) · 🇸🇰 [sk](../../sk/docs/FEATURES.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FEATURES.md) · 🇮🇱 [he](../../he/docs/FEATURES.md) · 🇵🇭 [phi](../../phi/docs/FEATURES.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FEATURES.md)
+
+---
+
+Visual guide to every section of the OmniRoute dashboard.
+
+---
+
+## 🔌 Providers
+
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
+
+
+
+---
+
+## 🎨 Combos
+
+Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
+
+
+
+---
+
+## 📊 Analytics
+
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
+
+
+
+---
+
+## 🏥 System Health
+
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+
+
+
+---
+
+## 🔧 Translator Playground
+
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
+
+
+
+---
+
+## 🎮 Model Playground _(v2.0.9+)_
+
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
+
+---
+
+## 🎨 Themes _(v2.0.5+)_
+
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
+
+## ⚙️ Settings
+
+Comprehensive settings panel with tabs:
+
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning
+- **Advanced** — Configuration overrides
+
+
+
+---
+
+## 🔧 CLI Tools
+
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
+
+
+
+---
+
+## 🤖 CLI Agents _(v2.0.11+)_
+
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
+
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
+
+---
+
+## 🖼️ Media _(v2.0.3+)_
+
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
+
+## 📝 Request Logs
+
+Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
+
+
+
+---
+
+## 🌐 API Endpoint
+
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
+
+
+
+---
+
+## 🔑 API Key Management
+
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
+
+---
+
+## 📋 Audit Log
+
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
+
+---
+
+## 🖥️ Desktop Application
+
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
+
+Key features:
+
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
+
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.
diff --git a/docs/i18n/hu/README.md b/docs/i18n/hu/README.md
index f54a2328a6..5f1a2eaed6 100644
--- a/docs/i18n/hu/README.md
+++ b/docs/i18n/hu/README.md
@@ -1,24 +1,94 @@
-omniroute.online
-
-
- # 🚀 OmniRoute – Az ingyenes mesterséges intelligencia átjáró
+# 🚀 OmniRoute — The Free AI Gateway (Magyar)
-### Soha ne hagyd abba a kódolást. Intelligens útválasztás **INGYENES és alacsony költségű mesterséges intelligencia modellekhez** automatikus visszaállítással.
-
-_Az univerzális API-proxy – egy végpont, 36+ szolgáltató, nulla állásidő._
-
-**Csevegés befejezése • Beágyazások • Képgenerálás • Hang • Újrarangsorolás • 100% TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Ingyenes mesterséges intelligencia szolgáltató kedvenc kódoló ügynökei számára
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Csatlakoztasson bármilyen mesterséges intelligencia-alapú IDE-t vagy CLI-eszközt az OmniRoute-on keresztül – ingyenes API-átjáró a korlátlan kódoláshoz._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+` tags no longer leak to clients in SSE streaming responses (#585) |
+| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with per-provider/account quota enforcement, idempotency, SHA-256 storage, and optional GitHub issue reporting |
+| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG → generic fallback chain |
+| 🔄 **Model Auto-Sync** | 24h scheduler and manual UI toggle to sync model lists for built-in and custom OpenAI-compatible providers |
+| 🌐 **OpenCode Zen/Go** | Two new providers from @kang-heewon via PR #530: free tier + subscription tier via `OpencodeExecutor` |
+| 🐛 **Gemini CLI OAuth** | Actionable error when `GEMINI_OAUTH_CLIENT_SECRET` is missing in Docker (was cryptic Google error) |
+| 🐛 **OpenCode config** | `saveOpenCodeConfig()` now correctly writes TOML to `XDG_CONFIG_HOME` |
+| 🐛 **Pinned model override** | `body.model` correctly set to `pinnedModel` on context-cache protection |
+| 🐛 **Codex/Claude loop** | `tool_result` blocks now converted to text to stop infinite loops |
+| 🐛 **Login redirect** | Login no longer freezes after skipping password setup |
+| 🐛 **Windows paths** | MSYS2/Git-Bash paths (`/c/...`) normalized to `C:\...` automatically |
+
+---
+
+## 🖼️ Main Dashboard
+
+
-📡 Minden ügyintéző a ` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**Stop wasting money and hitting limits:**
-### 🆕 What's New in v3.0.0
+- Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**OmniRoute solves this:**
+
+- ✅ **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
+- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool
---
-[](https://www.npmjs.com/package/omniroute)
-[](https://hub.docker.com/r/diegosouzapw/omniroute)
-[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
-[](https://omniroute.online)
-[](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
+## 📧 Support
-[🌐 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)
+> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.
-🌐 **Available in:** 🇺🇸 [English](../../README.md) | 🇧🇷 [Português (Brasil)](../pt-BR/README.md) | 🇪🇸 [Español](../es/README.md) | 🇫🇷 [Français](../fr/README.md) | 🇮🇹 [Italiano](../it/README.md) | 🇷🇺 [Русский](../ru/README.md) | 🇨🇳 [中文 (简体)](../zh-CN/README.md) | 🇩🇪 [Deutsch](../de/README.md) | 🇮🇳 [हिन्दी](../in/README.md) | 🇹🇭 [ไทย](../th/README.md) | 🇺🇦 [Українська](../uk-UA/README.md) | 🇸🇦 [العربية](../ar/README.md) | 🇯🇵 [日本語](../ja/README.md) | 🇻🇳 [Tiếng Việt](../vi/README.md) | 🇧🇬 [Български](../bg/README.md) | 🇩🇰 [Dansk](../da/README.md) | 🇫🇮 [Suomi](../fi/README.md) | 🇮🇱 [עברית](../he/README.md) | 🇭🇺 [Magyar](../hu/README.md) | 🇮🇩 [Bahasa Indonesia](../id/README.md) | 🇰🇷 [한국어](../ko/README.md) | 🇲🇾 [Bahasa Melayu](../ms/README.md) | 🇳🇱 [Nederlands](../nl/README.md) | 🇳🇴 [Norsk](../no/README.md) | 🇵🇹 [Português (Portugal)](../pt/README.md) | 🇷🇴 [Română](../ro/README.md) | 🇵🇱 [Polski](../pl/README.md) | 🇸🇰 [Slovenčina](../sk/README.md) | 🇸🇪 [Svenska](../sv/README.md) | 🇵🇭 [Filipino](../phi/README.md)
-
-
-
----
-
-## 🖼️
-
-
-
- # 🚀 OmniRoute – Az ingyenes mesterséges intelligencia átjáró
+# 🚀 OmniRoute — The Free AI Gateway (Magyar)
-### Soha ne hagyd abba a kódolást. Intelligens útválasztás **INGYENES és alacsony költségű mesterséges intelligencia modellekhez** automatikus visszaállítással.
-
-_Az univerzális API-proxy – egy végpont, 36+ szolgáltató, nulla állásidő._
-
-**Csevegés befejezése • Beágyazások • Képgenerálás • Hang • Újrarangsorolás • 100% TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Ingyenes mesterséges intelligencia szolgáltató kedvenc kódoló ügynökei számára
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Csatlakoztasson bármilyen mesterséges intelligencia-alapú IDE-t vagy CLI-eszközt az OmniRoute-on keresztül – ingyenes API-átjáró a korlátlan kódoláshoz._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+
+
+[](https://www.npmjs.com/package/omniroute)
+[](https://www.npmjs.com/package/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
+[](https://omniroute.online)
+[](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)
+
+
+
+🌐 **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)
+
+---
+
+## 🆕 What's New in v3.0.0
+
+> **Upgrading from v2.9.5?** — See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes.
+
+| Area | Change |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection remediation |
+| ✅ **Route Validation** | All 176 API routes now validated with Zod schemas + `validateBody()` — CI `check:route-validation:t06` passes |
+| 🐛 **omniModel Tag Leak** | Internal `
+
+
+
+---
+
+## 📸 Dashboard Preview
+
+
+
+
+
+---
+
+### 🤖 Free AI Provider for your favorite coding agents
+
+_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._
Click to see dashboard screenshots
+ +| Page | Screenshot | +| -------------- | ------------------------------------------------- | +| **Providers** |  | +| **Combos** |  | +| **Analytics** |  | +| **Health** |  | +| **Translator** |  | +| **Settings** |  | +| **CLI Tools** |  | +| **Usage Logs** |  | +| **Endpoints** |  | + +|
-
+
OpenClaw @@ -92,113 +162,52 @@ _Csatlakoztasson bármilyen mesterséges intelligencia-alapú IDE-t vagy CLI-esz |
http://localhost:20128/v1 vagy http://cloud.omni_TOKEN_244\_\_http://cloud.omniroute_EN_2NI4/v_1_TO_2.online-on keresztül csatlakozik konfiguráció, korlátlan modellek és kvóta
+📡 All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 — one config, unlimited models and quota
---
-### 🆕 What's New in v3.0.0
+## 🤔 Why OmniRoute?
-| Area | Change |
-| ------------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal ` Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `
-
-
-
----
-
-## 📸
-
-
-
-
-
----
-
-## 🤔 Miért az OmniRoute?
-
-**Ne pazarolja a pénzt, és ne lépje túl a limiteket:**
-
-- ...
- -| # | # | -| ----- | ---------------------------------------- | -| **1** |  | -| **2** |  | -| **3** |  | -| **4** |  | -| **5** |  | -| **6** |  | -| **7** |  | -| **8** |  | -| **9** |  | - - Az előfizetési kvóta minden hónapban fel nem használt
-- A sebességkorlátok megakadályozzák a közbenső kódolást
-- Drága API-k (20-50 USD/hó szolgáltatónként)
-- Manuális váltás a szolgáltatók között
-
-**Az OmniRoute ezt megoldja:**
-
-- ✅ **Az előfizetések maximalizálása** - Kövesse nyomon a kvótát, használjon fel minden bitet a visszaállítás előtt
-- ✅ **Automatikus tartalék** - Előfizetés → API-kulcs → Olcsó → Ingyenes, nulla állásidő
-- ✅ **Több fiók** - Kör-robin a fiókok között szolgáltatónként
-- ✅ **Univerzális** - Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, bármilyen CLI eszközzel működik
-
----
-
-## 📧 Támogatás
-
-> 💬 **Csatlakozzon közösségünkhöz!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Kérjen segítséget, ossza meg tippjeit, és naprakész legyen.
-
-- **Webhely**: [omniroute.online](https://omniroute.online)
+- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Problémák**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Eredeti projekt**: [9router by decolua](https://github.com/decolua/9router)
+- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 Hogyan működik
+## 🔄 How It Works
```
┌─────────────┐
@@ -227,452 +236,453 @@ Result: Never stop coding, minimal cost
---
-## 🎯 Mit old meg az OmniRoute – 30 valódi fájdalompont és használati eset
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **Minden mesterséges intelligencia-eszközöket használó fejlesztő naponta szembesül ezekkel a problémákkal.** Az OmniRoute úgy készült, hogy ezeket mind megoldja – a költségtúllépésektől a regionális blokkokig, a megszakadt OAuth-folyamatoktól a protokollműveletekig és a vállalati megfigyelhetőségig.
+> **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.
-
💸 1. "Drága előfizetésért fizetek, de még mindig megszakítanak a korlátozások"
+💸 1. "I pay for an expensive subscription but still get interrupted by limits"
-A fejlesztők havi 20–200 dollárt fizetnek a Claude Pro, Codex Pro vagy GitHub Copilotért. A kvótának még fizetés esetén is van felső határa – 5 óra használat, heti limitek vagy percdíjkorlátok. A kódolási munkamenet közepén a szolgáltató leáll, és a fejlesztő elveszíti a folyamatot és a termelékenységet. +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. -**Hogyan oldja meg az OmniRoute:** +**How OmniRoute solves it:** -- **Smart 4-Tier Fallback** – Ha az előfizetési kvóta kimerül, automatikusan átirányítja az API-kulcs → Olcsó → Ingyenes, manuális beavatkozás nélkül -- **Valós idejű kvótakövetés** – Valós időben mutatja a token felhasználást, visszaszámlálással (5 óra, napi, heti) -- **Több fiók támogatása** - Több fiók szolgáltatónként automatikus körváltással - ha az egyik elfogy, átvált a következőre -- **Egyéni kombók** — Testreszabható tartalék láncok 6 kiegyensúlyozási stratégiával (fill-first, round-robin, P2C, véletlenszerű, legkevésbé használt, költségoptimalizált) -- **Codex üzleti kvóták** — Üzleti/csapat munkaterület-kvóta figyelése közvetlenül az irányítópulton +- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention +- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly) +- **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 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
-` blokkokat bont ki olyan modellekből, mint a DeepSeek R1 szabványos `reasoning_content`-be
-- **Strukturált kimenet a Gemini számára** — `json_schema` → `responseMimeType`/`responseSchema` automatikus átalakítás
-- **`stream` az alapértelmezett `false`** - Az OpenAI specifikációhoz igazodik, elkerülve a váratlan SSE-t a Python/Rust/Go SDK-kban
+- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 67+ 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
🔌 2. "Több szolgáltatót kell használnom, de mindegyiknek más API"
+🔌 2. "I need to use multiple providers but each has a different API"
-Az OpenAI egy formátumot használ, a Claude (Anthropic) egy másikat, a Gemini pedig egy másikat. Ha egy fejlesztő különböző szolgáltatók modelljeit szeretné tesztelni, vagy tartalékot szeretne közöttük, akkor újra kell konfigurálnia az SDK-kat, módosítania kell a végpontokat, és kezelnie kell az inkompatibilis formátumokat. Az egyéni szolgáltatók (FriendLI, NIM) nem szabványos modellvégpontokkal rendelkeznek. +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. -**Hogyan oldja meg az OmniRoute:** +**How OmniRoute solves it:** -- **Egységes végpont** - Egy `http://localhost:20128/v1` proxyként szolgál mind a 36+ szolgáltató számára -- **Formátumfordítás** - Automatikus és átlátható: OpenAI ↔ Claude ↔ Gemini ↔ Responses API -- **Response Sanitization** – Eltávolítja azokat a nem szabványos mezőket (`x_groq`, `usage_breakdown`, `service_tier`), amelyek megszakítják az OpenAI SDK v1.83+ verzióját -- **Szerepek normalizálása** — `developer` → `system` konvertálása nem OpenAI szolgáltatók számára; `system` → `user` a GLM/ERNIE számára -- **Think Tag Extraction** – `
-
🌐 3. „Az AI-szolgáltatóm blokkolja a régiómat/országomat”
+🌐 3. "My AI provider blocks my region/country"
-Az olyan szolgáltatók, mint az OpenAI/Codex, blokkolják a hozzáférést bizonyos földrajzi régiókból. A felhasználók OAuth- és API-kapcsolatok során olyan hibákat kapnak, mint az `unsupported_country_region_territory`. Ez különösen frusztráló a fejlődő országok fejlesztői számára. +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. -**Hogyan oldja meg az OmniRoute:** +**How OmniRoute solves it:** -- **3-szintű proxykonfiguráció** – 3 szinten konfigurálható proxy: globális (teljes forgalom), szolgáltatónként (csak egy szolgáltató) és kapcsolatonként/kulcsonként -- **Színes proxy jelvények** - Vizuális jelzők: 🟢 globális proxy, 🟡 szolgáltató proxy, 🔵 kapcsolat proxy, mindig az IP-t mutatja -- **OAuth-tokencsere proxyn keresztül** — Az OAuth-folyamat a proxyn keresztül is megy, megoldva az `unsupported_country_region_territory` problémát -- **Kapcsolódási tesztek proxyn keresztül** - A csatlakozási tesztek a konfigurált proxyt használják (nincs többé közvetlen kiiktatás) -- **SOCKS5 támogatás** — Teljes SOCKS5 proxy támogatás a kimenő útválasztáshoz -- **TLS-ujjlenyomat-hamisítás** — Böngészőszerű TLS-ujjlenyomat az `wreq-js`-n keresztül a botészlelés megkerüléséhez +- **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
-` prefix
-- **Csak ingyenes kombók** — `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` lánc = 0 USD/hó nulla állásidővel
-- **NVIDIA NIM ingyenes kreditek** – 1000 ingyenes kredit integrálva
-- **Költségoptimalizált stratégia** — Útválasztási stratégia, amely automatikusan a legolcsóbb elérhető szolgáltatót választja
+- **Free-Only Combos** — Chain `gc/gemini-3-flash → 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
🆓 4. "MI-t akarok használni kódoláshoz, de nincs pénzem"
+🆓 4. "I want to use AI for coding but I have no money"
-Nem mindenki fizethet havi 20–200 dollárt az AI-előfizetésekért. A feltörekvő országok diákjainak, fejlesztőinek, amatőröknek és szabadúszóknak nulla költséggel kell hozzáférniük a minőségi modellekhez. +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. -**Hogyan oldja meg az OmniRoute:** +**How OmniRoute solves it:** -- **Beépített ingyenes szolgáltatók** - Natív támogatás 100%-ban ingyenes szolgáltatókhoz: iFlow (8 korlátlan modell), Qwen (3 korlátlan modell), Kiro (Claude ingyenes), Gemini CLI (180 000/hónap ingyenes) +- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free) - **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/
-
🔒 5. "Meg kell védenem a mesterséges intelligencia átjárómat a jogosulatlan hozzáféréstől"
+🔒 5. "I need to protect my AI gateway from unauthorized access"
-Ha AI átjárót teszünk ki a hálózatnak (LAN, VPS, Docker), a cím birtokában bárki felhasználhatja a fejlesztő tokenjeit/kvótáját. Védelem nélkül az API-k sebezhetőek a visszaélésekkel, azonnali befecskendezéssel és visszaélésekkel szemben. +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. -**Hogyan oldja meg az OmniRoute:** +**How OmniRoute solves it:** -- **API-kulcskezelés** — Generálás, rotáció és hatókör szolgáltatónként egy dedikált `/dashboard/api-manager`-oldallal -- **Modellszintű engedélyek** - API-kulcsok korlátozása adott modellekre (`openai/*`, helyettesítő karakteres minták), az Összes engedélyezése/Korlátozása kapcsolóval -- **API Endpoint Protection** — Kulcs szükséges az `/v1/models` számára, és bizonyos szolgáltatók letiltása a listáról -- **Auth Guard + CSRF védelem** - Minden irányítópult-útvonal `withAuth` köztes szoftverrel + CSRF tokenekkel védett -- **Rate Limiter** — IP-nkénti sebességkorlátozás konfigurálható ablakokkal -- **IP-szűrés** — Engedélyezési lista/blokkolólista a hozzáférés-vezérléshez -- **Prompt Injection Guard** – fertőtlenítés a rosszindulatú felszólítási minták ellen -- **AES-256-GCM titkosítás** - A hitelesítő adatok nyugalmi állapotban titkosítva +- **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. "A szolgáltatóm leállt, és elvesztettem a kódolási folyamatomat"
+🛑 6. "My provider went down and I lost my coding flow"
-Az AI-szolgáltatók instabillá válhatnak, 5xx-es hibákat adnak vissza, vagy elérhetik az ideiglenes sebességkorlátokat. Ha egy fejlesztő egyetlen szolgáltatótól függ, akkor megszakad. Megszakítók nélkül az ismételt újrapróbálkozások összeomolhatják az alkalmazást. +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. -**Hogyan oldja meg az OmniRoute:** +**How OmniRoute solves it:** -- **Megszakító szolgáltatónként** - Automatikus nyitás/zárás konfigurálható küszöbértékekkel és lehűtéssel (zárt/nyitott/félig nyitott) -- **Exponenciális visszalépés** — Progresszív újrapróbálkozási késések -- **Mennydörgés elleni csorda** - Mutex + szemafor védelem az egyidejű újrapróbálkozási viharok ellen -- **Kombinált tartalék láncok** – Ha az elsődleges szolgáltató meghibásodik, automatikusan, beavatkozás nélkül átesik a láncon -- **Combo Circuit Breaker** – Automatikusan letiltja a hibás szolgáltatókat a kombinált láncon belül - | 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format | -- **Egészségügyi irányítópult** — Üzemidő-figyelés, áramkör-megszakító állapotok, zárolások, gyorsítótár-statisztika, p50/p95/p99 késleltetés +- **Circuit Breaker per-model** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks +- **Exponential Backoff** — Progressive retry delays +- **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 +- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain +- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
-
🔧 7. "Az egyes AI-eszközök konfigurálása fárasztó és ismétlődő"
+🔧 7. "Configuring each AI tool is tedious and repetitive"
-A fejlesztők Cursort, Claude Code-ot, Codex CLI-t, OpenClaw-ot, Gemini CLI-t, Kilo Code-ot használnak... Minden eszköznek más konfigurációra van szüksége (API végpont, kulcs, modell). Az újrakonfigurálás szolgáltató- vagy modellváltáskor időpocsékolás. +Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time. -**Hogyan oldja meg az OmniRoute:** +**How OmniRoute solves it:** -- **CLI Tools Dashboard** - Dedikált oldal egykattintásos beállítással a Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline számára -- **GitHub másodpilóta konfigurációs generátor** — `chatLanguageModels.json` kódot generál VS kódhoz tömeges modellválasztással -- **Bevezető varázsló** – Irányított 4 lépéses beállítás első felhasználók számára -- **Egy végpont, minden modell** — Az `http://localhost:20128/v1` egyszeri konfigurálása, 36+ szolgáltató elérése +- **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 67+ providers
-
🔑 8. "A több szolgáltatótól származó OAuth-tokenek kezelése pokol"
+🔑 8. "Managing OAuth tokens from multiple providers is hell"
-Claude Code, Codex, Gemini CLI, Copilot – mindegyik az OAuth 2.0-t használja lejáró tokenekkel. A fejlesztőknek folyamatosan újra kell hitelesíteniük, kezelniük kell az `client_secret is missing`, `redirect_uri_mismatch` és a távoli szerverek hibáit. Az OAuth a LAN/VPS-en különösen problémás. +Claude Code, Codex, Gemini CLI, 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. -**Hogyan oldja meg az OmniRoute:** +**How OmniRoute solves it:** -- **Automatikus tokenfrissítés** - Az OAuth-tokenek a háttérben frissülnek a lejárat előtt -- **OAuth 2.0 (PKCE) beépített** - Automatikus áramlás Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow számára -- **Multi-Account OAuth** - Több fiók szolgáltatónként a JWT/ID token kivonattal -- **OAuth LAN/Távoli javítás** - Privát IP-észlelés `redirect_uri`-hez + kézi URL mód távoli szerverekhez -- **OAuth az Nginx mögött** - `window.location.origin`-t használ a fordított proxy kompatibilitás érdekében -- **Távoli OAuth útmutató** – Lépésről lépésre útmutató a Google Cloud hitelesítő adataihoz VPS/Docker rendszeren +- **Auto Token Refresh** — OAuth tokens refresh in background before expiration +- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow +- **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. "Nem tudom, mennyit költök vagy hova"
+📊 9. "I don't know how much I'm spending or where"
-A fejlesztők több fizetős szolgáltatót használnak, de nincs egységes nézetük a kiadásokról. Minden szolgáltató saját számlázási irányítópulttal rendelkezik, de nincs összevont nézet. A váratlan költségek felhalmozódhatnak. +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. -**Hogyan oldja meg az OmniRoute:** +**How OmniRoute solves it:** -- **Költségelemzési irányítópult** – Tokenenkénti költségkövetés és költségkeret-kezelés szolgáltatónként -- **Költségkeret-korlátok rétegenként** - Költési felső határ szintenként, amely automatikus visszalépést vált ki -- **Modellenkénti árképzés** - Konfigurálható árak modellenként -- **Használati statisztika API-kulcsonként** — A kérések száma és az utoljára használt időbélyeg kulcsonként -- **Analytics Dashboard** — Statisztikai kártyák, modellhasználati diagram, szolgáltatói táblázat sikerarányokkal és késleltetéssel +- **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. "Nem tudom diagnosztizálni a hibákat és problémákat az AI-hívásoknál"
+🐛 10. "I can't diagnose errors and problems in AI calls"
-Ha egy hívás meghiúsul, a fejlesztő nem tudja, hogy sebességkorlátozás, lejárt token, rossz formátum vagy szolgáltatói hiba volt-e. Töredezett naplók különböző terminálokon. Megfigyelhetőség nélkül a hibakeresés próba és hiba. +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. -**Hogyan oldja meg az OmniRoute:** +**How OmniRoute solves it:** -- **Egységes naplók irányítópultja** - 4 lap: Kérelemnaplók, Proxynaplók, Auditnaplók, Konzol -- **Konzolnapló-nézegető** — Valós idejű terminál stílusú megjelenítő színkódolt szintekkel, automatikus görgetés, keresés, szűrés -- **SQLite proxynaplók** – Állandó naplók, amelyek túlélik a szerver újraindítását -- **Translator Playground** – 4 hibakeresési mód: Playground (formátum fordítás), Chat Tester (oda-vissza út), Tesztpad (kötegelt), Élő monitor (valós idejű) -- **Request Telemetria** – p50/p95/p99 késleltetés + X-Request-Id nyomkövetés -- **Fájlalapú naplózás elforgatással** - A konzolelfogó mindent JSON-naplóba rögzít méretalapú elforgatással +- **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 Proxy Logs** — Persistent logs that survive server restarts +- **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 Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation +- **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. "Az átjáró telepítése és karbantartása összetett"
+🏗️ 11. "Deploying and maintaining the gateway is complex"
-Az AI-proxy telepítése, konfigurálása és karbantartása különböző környezetekben (helyi, VPS, Docker, felhő) munkaigényes. Az olyan problémák, mint a keménykódolt elérési utak, az `EACCES` a könyvtárakon, a portütközések és a többplatformos buildek súrlódást okoznak. +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. -**Hogyan oldja meg az OmniRoute:** +**How OmniRoute solves it:** -- **npm globális telepítés** — `npm install -g omniroute && omniroute` — kész -- **Docker Multi-Platform** – AMD64 + ARM64 natív (Apple Silicon, AWS Graviton, Raspberry Pi) -- **Docker Compose Profiles** — `base` (nincs CLI-eszközök) és `cli` (Claude Code-al, Codex-szel, OpenClaw-val) -- **Electron Desktop App** – Natív alkalmazás Windows/macOS/Linux rendszerhez rendszertálcával, automatikus indítással, offline móddal -- **Split-Port Mode** – API és irányítópult külön portokon haladó forgatókönyvekhez (fordított proxy, konténerhálózat) -- **Cloud Sync** – Szinkronizálás konfigurálása az eszközök között a Cloudflare Workers segítségével -- **DB biztonsági mentések** — Az összes beállítás automatikus biztonsági mentése, visszaállítása, exportálása és importálása +- **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
-
🌍 12. "A felület csak angol nyelvű, és a csapatom nem beszél angolul"
+🌍 12. "The interface is English-only and my team doesn't speak English"
-A nem angol nyelvű országokban, különösen Latin-Amerikában, Ázsiában és Európában működő csapatok csak angol nyelvű felületekkel küszködnek. A nyelvi akadályok csökkentik az átvételt és növelik a konfigurációs hibákat. +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. -**Hogyan oldja meg az OmniRoute:** +**How OmniRoute solves it:** -- ** Irányítópult i18n – 30 nyelv** – Mind az 500+ billentyű lefordítva, beleértve arab, bolgár, dán, német, spanyol, finn, francia, héber, hindi, magyar, indonéz, olasz, japán, koreai, maláj, holland, norvég, lengyel, portugál (PT/BR), román, thai, orosz, szlovák, svéd, filippínó, angol, thai, orosz, kínai, filippínó -- **RTL támogatás** – Jobbról balra haladó arab és héber nyelv támogatása -- **Többnyelvű README-k** — 30 teljes dokumentáció fordítás -- **Nyelvválasztó** — Globe ikon a fejlécben a valós idejű váltáshoz +- **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. "Többre van szükségem, mint csevegésre – beágyazásra, képekre, hangra van szükségem"
+🔄 13. "I need more than chat — I need embeddings, images, audio"
-Az AI nem csak a csevegés befejezése. A fejlesztőknek képeket kell generálniuk, hangot kell átírniuk, beágyazást kell létrehozniuk a RAG számára, át kell sorolniuk a dokumentumokat, és moderálniuk kell a tartalmat. Minden API más végponttal és formátummal rendelkezik. +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. -**Hogyan oldja meg az OmniRoute:** +**How OmniRoute solves it:** -- **Beágyazások** — `/v1/embeddings` 6 szolgáltatóval és 9+ modellel -- **Képgenerálás** — `/v1/images/generations` 10 szolgáltatóval és 20+ modellel (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI) -- **Text-to-Video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) és SD WebUI +- **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 átírás** - `/v1/audio/transcriptions` - Whisper + Nvidia NIM, HuggingFace, Qwen3 -- **Szövegfelolvasó** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, Inworld, Cartesia, PlayHT, + meglévő szolgáltatók -- **Moderálás** — `/v1/moderations` — Tartalombiztonsági ellenőrzések -- **Átsorolás** — `/v1/rerank` — Dokumentumreleváns átsorolás -- **Responses API** - Teljes `/v1/responses` támogatás a Codexhez +- **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. "Nincs módom tesztelni és összehasonlítani a minőséget a különböző modellek között"
+🧪 14. "I have no way to test and compare quality across models"
-A fejlesztők szeretnék tudni, hogy melyik modell a legjobb az ő használati esetükben – kód, fordítás, érvelés –, de a manuális összehasonlítás lassú. Nincsenek integrált eval eszközök. +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. -**Hogyan oldja meg az OmniRoute:** +**How OmniRoute solves it:** -- **LLM-értékelések** — Arany készlet tesztelése 10 előre betöltött esettel, beleértve az üdvözlést, a matematikát, a földrajzot, a kódgenerálást, a JSON-megfelelőséget, a fordítást, a leértékelést, a biztonsági megtagadást -- **4 egyezési stratégia** — `exact`, `contains`, `regex`, `custom` (JS funkció) -- **Translator Playground Test Bench** - Kötegelt tesztelés több bemenettel és várható kimenettel, szolgáltatók közötti összehasonlítás -- **Csevegés tesztelő** - Teljes körút vizuális válaszmegjelenítéssel -- **Élő monitor** – Valós idejű adatfolyam a proxyn keresztül folyó összes kérésről +- **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. "A teljesítmény elvesztése nélkül kell méreteznem"
+📈 15. "I need to scale without losing performance"
-A kérelmek mennyiségének növekedésével ugyanazok a kérdések a gyorsítótárazás nélkül duplikált költségeket generálnak. Idempotencia nélkül a duplikált hulladékfeldolgozási kérelmek. A szolgáltatónkénti díjkorlátokat be kell tartani. +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. -**Hogyan oldja meg az OmniRoute:** +**How OmniRoute solves it:** -- **Szemantikus gyorsítótár** – A kétszintű gyorsítótár (aláírás + szemantikai) csökkenti a költségeket és a késleltetést -- **Idempotency kérése** – 5 másodperces deduplikációs ablak azonos kérések esetén -- **Drátakorlát észlelése** – Szolgáltatónkénti RPM, minimális rés és maximális egyidejű követés -- **Szerkeszthető sebességkorlátok** - Konfigurálható alapértékek a Beállítások → Kitartással ellenálló képesség menüpontban -- **API Key Validation Cache** – 3-szintű gyorsítótár az éles teljesítményhez -- **Egészségügyi irányítópult telemetriával** — p50/p95/p99 késleltetés, gyorsítótár statisztika, üzemidő +- **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 +- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence +- **API Key Validation Cache** — 3-tier cache for production performance +- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
-
🤖 16. "Globálisan szeretném szabályozni a modell viselkedését"
+🤖 16. "I want to control model behavior globally"
-Azok a fejlesztők, akik minden választ egy adott nyelven, egy adott hangnemben szeretnének, vagy korlátozni szeretnék az érvelési tokeneket. Ennek konfigurálása minden eszközben/kérelemben nem praktikus. +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. -**Hogyan oldja meg az OmniRoute:** +**How OmniRoute solves it:** -- **Rendszerprompt Injection** — Globális prompt minden kérelemre vonatkozik -- **A költségkeret átgondolásának ellenőrzése** – Indoklási token-kiosztás ellenőrzése kérésenként (áthaladó, automatikus, egyéni, adaptív) -- **6 Útválasztási stratégia** – Globális stratégiák, amelyek meghatározzák a kérések elosztását -- **Wildcard Router** — `provider/*` minták dinamikusan továbbítanak bármely szolgáltatóhoz -- **Kombinációs engedélyezés/letiltás váltás** - A kombók váltása közvetlenül az irányítópultról -- **Provider Toggle** — Egy szolgáltató összes kapcsolatának engedélyezése/letiltása egyetlen kattintással -- **Letiltott szolgáltatók** - Adott szolgáltatók kizárása az `/v1/models` listáról +- **System Prompt Injection** — Global prompt applied to all requests +- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive) +- **6 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 +- **Provider Toggle** — Enable/disable all connections for a provider with one click +- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
-
🧰 17. "MCP eszközökre van szükségem, mint első osztályú termékképességekre"
+🧰 17. "I need MCP tools as first-class product capabilities"
-Sok mesterséges intelligencia-átjáró csak rejtett megvalósítási részletként teszi közzé az MCP-t. A csapatoknak látható, kezelhető műveleti rétegre van szükségük. +Many AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer. -**Hogyan oldja meg az OmniRoute:** +**How OmniRoute solves it:** -- Az MCP megjelenik az irányítópult navigációs és végponti protokoll lapján -- Dedikált MCP-kezelési oldal folyamatokkal, eszközökkel, hatókörökkel és audittal -- Beépített gyorsindítás az `omniroute --mcp` és a kliens beépítéséhez +- 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. "A2A hangszerelésre van szükségem szinkronizálással + adatfolyam feladatútvonalak"
+🧠 18. "I need A2A orchestration with sync + stream task paths"
-Az ügynöki munkafolyamatokhoz közvetlen válaszokra és hosszú távú, streamelt végrehajtásra van szükség életciklus-vezérléssel. +Agent workflows need both direct replies and long-running streamed execution with lifecycle control. -**Hogyan oldja meg az OmniRoute:** +**How OmniRoute solves it:** -- A2A JSON-RPC végpont (`POST /a2a`) `message/send` és `message/stream` -- SSE streaming terminál állapot terjesztéssel -- Feladat életciklus API-k `tasks/get` és `tasks/cancel` +- 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. "Valódi MCP folyamatállapotra van szükségem, nem kitalált állapotra"
+🛰️ 19. "I need real MCP process health, not guessed status"
-Az operatív csapatoknak tudniuk kell, hogy az MCP valóban életben van-e, nem csak azt, hogy egy API elérhető-e. +Operational teams need to know if MCP is actually alive, not just whether an API is reachable. -**Hogyan oldja meg az OmniRoute:** +**How OmniRoute solves it:** -- Futásidejű szívverés fájl PID-vel, időbélyegekkel, szállítással, szerszámszámmal és hatókör móddal -- MCP állapot API, amely kombinálja a szívverést + a legutóbbi tevékenységet -- UI állapotkártyák a folyamat/üzemidő/szívverés frissességéhez +- 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. "Kivizsgálható MCP-eszköz végrehajtásra van szükségem"
+📋 20. "I need auditable MCP tool execution"
-Amikor az eszközök módosítják a konfigurációt vagy működési műveleteket indítanak el, a csapatoknak kriminalisztikai nyomon követhetőségre van szükségük. +When tools mutate config or trigger ops actions, teams need forensic traceability. -**Hogyan oldja meg az OmniRoute:** +**How OmniRoute solves it:** -- SQLite-alapú audit naplózás MCP-eszközhívásokhoz -- Szűrések eszköz, siker/kudarc, API-kulcs és oldalszámozás szerint -- Irányítópult audit táblázat + statisztikai végpontok az automatizáláshoz +- 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. "Hatókörű MCP-engedélyekre van szükségem integrációnként"
+🔐 21. "I need scoped MCP permissions per integration"
-A különböző ügyfeleknek a legkevesebb jogosultsággal kell rendelkezniük az eszközkategóriákhoz. +Different clients should have least-privilege access to tool categories. -**Hogyan oldja meg az OmniRoute:** +**How OmniRoute solves it:** -- 9 szemcsés MCP hatókör az ellenőrzött szerszámhozzáféréshez -- Hatályérvényesítés és láthatóság az MCP-kezelő felületen -- Biztonságos alaphelyzet az üzemi szerszámokhoz +- 9 granular MCP scopes for controlled tool access +- Scope enforcement and visibility in MCP management UI +- Safe default posture for operational tooling
-
⚙️ 22. "Üzemeltetési vezérlőkre van szükségem átcsoportosítás nélkül"
+⚙️ 22. "I need operational controls without redeploying"
-A csapatoknak gyors futásidejű változtatásokra van szükségük incidensek vagy költségesemények során. +Teams need quick runtime changes during incidents or cost events. -**Hogyan oldja meg az OmniRoute:** +**How OmniRoute solves it:** -- A kombinált aktiválás váltása közvetlenül az MCP műszerfaláról -- Rugalmassági profilok alkalmazása előre meghatározott házirend-csomagokból -- Állítsa vissza a megszakító állapotát ugyanarról a kezelőpanelről +- Switch combo activation directly from MCP dashboard +- Apply resilience profiles from pre-defined policy packs +- Reset circuit breaker state from the same operations panel
-
🔄 23. "Szükségem van élő A2A feladatok életciklusának láthatóságára és törlésére"
+🔄 23. "I need live A2A task lifecycle visibility and cancellation"
-Az életciklus láthatósága nélkül a feladat-incidensek nehezen osztályozhatók. +Without lifecycle visibility, task incidents become hard to triage. -**Hogyan oldja meg az OmniRoute:** +**How OmniRoute solves it:** -- Feladatok listázása/szűrés állapot/készség szerint oldalszámozással -- A feladatok metaadatainak, eseményeinek és műtermékeinek részletezése -- Feladat törlési végpont és felhasználói felület művelet megerősítéssel +- 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. "Aktív adatfolyam-metrikákra van szükségem A2A terheléshez"
+🌊 24. "I need active stream metrics for A2A load"
-A streamelési munkafolyamatok működési betekintést igényelnek a párhuzamosság és az élő kapcsolatok terén. +Streaming workflows require operational insight into concurrency and live connections. -**Hogyan oldja meg az OmniRoute:** +**How OmniRoute solves it:** -- Az A2A állapotba integrált aktív folyamszámlálók -- Utolsó feladat időbélyegzője és állapotonkénti száma -- A2A műszerfalkártyák a valós idejű műveletek figyeléséhez +- Active stream counters integrated into A2A status +- Last task timestamp and per-state counts +- A2A dashboard cards for real-time ops monitoring
-
🪪 25. "Szabványos ügynökfelderítésre van szükségem az ügyfelek számára"
+🪪 25. "I need standard agent discovery for clients"
-A külső klienseknek és hangszerelőknek géppel olvasható metaadatokra van szükségük a bevezetéshez. +External clients and orchestrators need machine-readable metadata for onboarding. -**Hogyan oldja meg az OmniRoute:** +**How OmniRoute solves it:** -- Az ügynökkártya az `/.well-known/agent.json` címen látható -- A menedzsment felületen látható képességek és készségek -- Az A2A állapot API felfedezési metaadatokat tartalmaz az automatizáláshoz +- Agent Card exposed at `/.well-known/agent.json` +- Capabilities and skills shown in management UI +- A2A status API includes discovery metadata for automation
-
🧭 26. "Protokoll felfedezhetőségre van szükségem az UX termékben"
+🧭 26. "I need protocol discoverability in the product UX"
-Ha a felhasználók nem fedezik fel a protokollfelületeket, az elfogadás és a támogatás minősége csökken. +If users cannot discover protocol surfaces, adoption and support quality drop. -**Hogyan oldja meg az OmniRoute:** +**How OmniRoute solves it:** -- Oldalsáv bejegyzések MCP és A2A számára -- Végpont oldal Protokollok lap gyorsindítással és állapottal -- Linkek az áttekintésből a dedikált felügyeleti irányítópultokhoz +- 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. "Végponttól végpontig terjedő protokoll-érvényesítésre van szükségem valós kliensekkel"
+🧪 27. "I need end-to-end protocol validation with real clients"
-A próbatesztek nem elegendőek a protokoll-kompatibilitás ellenőrzéséhez a kiadás előtt. +Mock tests are not enough to validate protocol compatibility before release. -**Hogyan oldja meg az OmniRoute:** +**How OmniRoute solves it:** -- E2E csomag, amely elindítja az alkalmazást, és valódi MCP SDK kliens szállítást használ -- Az A2A kliens teszteli az áramlások felfedezését, küldését, streamingjét, lekérését és megszakítását -- Az állítások keresztellenőrzése az MCP audit és az A2A feladatok API-jával szemben +- 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. "Egységes megfigyelhetőségre van szükségem minden interfészen"
+📡 28. "I need unified observability across all interfaces"
-A megfigyelhetőség protokoll szerinti felosztása vakfoltokat és hosszabb MTTR-t hoz létre. +Splitting observability by protocol creates blind spots and longer MTTR. -**Hogyan oldja meg az OmniRoute:** +**How OmniRoute solves it:** -- Egységes irányítópultok/naplók/analytics egy termékben -- Egészség + audit + kérés telemetria OpenAI, MCP és A2A rétegeken keresztül -- Működési API-k az állapothoz és az automatizáláshoz +- Unified dashboards/logs/analytics in one product +- Health + audit + request telemetry across OpenAI, MCP, and A2A layers +- Operational APIs for status and automation
-
💼 29. "Egy futási időre van szükségem a proxyhoz + eszközökhöz + ügynök hangszereléshez"
+💼 29. "I need one runtime for proxy + tools + agent orchestration"
-Számos külön szolgáltatás futtatása növeli a működési költségeket és a hibamódokat. +Running many separate services increases operational cost and failure modes. -**Hogyan oldja meg az OmniRoute:** +**How OmniRoute solves it:** -- OpenAI-kompatibilis proxy, MCP szerver és A2A szerver egy veremben -- Megosztott hitelesítés, rugalmasság, adattárolás és megfigyelhetőség -- Konzisztens politikai modell az összes interakciós felületen +- 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
-
-### Példa forgatókönyvekre (integrált használati esetek)
+### Example Playbooks (Integrated Use Cases)
-**A játékkönyv: Maximalizálja a fizetett előfizetést + olcsó biztonsági mentés**
+**Playbook A: Maximize paid subscription + cheap backup**
```txt
Combo: "maximize-claude"
@@ -684,7 +694,7 @@ Monthly cost: $20 + small backup spend
Outcome: higher quality, near-zero interruption
```
-**Playbook B: Zéró költségű kódolási verem**
+**Playbook B: Zero-cost coding stack**
```txt
Combo: "free-forever"
@@ -696,7 +706,7 @@ Monthly cost: $0
Outcome: stable free coding workflow
```
-**Playbook C: 24/7 mindig bekapcsolt tartalék lánc**
+**Playbook C: 24/7 always-on fallback chain**
```txt
Combo: "always-on"
@@ -709,65 +719,132 @@ Combo: "always-on"
Outcome: deep fallback depth for deadline-critical workloads
```
-**D játékkönyv: Az ügynök MCP + A2A-val működik**
+**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/mcp and /dashboard/a2a
-4) Control incidents with resilience profile + task cancellation
+3) Observe via /dashboard/endpoint (MCP and A2A tabs)
+4) Toggle services via inline status controls
```
---
-## ⚡ Gyors kezdés
+## 🆓 Start Free — Zero Configuration Cost
-**1. Globális telepítés:**
+> 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 **iFlow** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |
+| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |
+| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |
+| 5 | `/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).
+
+## Gyors kezdés
+
+### 1) Install and run
```bash
npm install -g omniroute
omniroute
```
-🎉 Az irányítópult ekkor nyílik meg: `http://localhost:20128`
+> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:
+>
+> ```bash
+> pnpm install -g omniroute
+> pnpm approve-builds -g # Select all packages → approve
+> omniroute
+> ```
-| Parancs | Leírás |
-| ----------------------- | --------------------------------------------- |
-| `omniroute` | Szerver indítása (alapértelmezett port 20128) |
-| `omniroute --port 3000` | Egyéni port használata |
-| `omniroute --no-open` | Ne nyissa meg automatikusan a böngészőt |
-| `omniroute --help` | Segítség megjelenítése |
+Dashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.
-**2. Csatlakozzon egy INGYENES szolgáltatóhoz:**
+| 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 |
-Irányítópult → Szolgáltatók → Csatlakozás **Claude Code** vagy **Antigravity** → OAuth bejelentkezés → Kész!
+Optional split-port mode:
-**3. Használja a CLI eszközben:**
-
-```
-Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Settings:
- Endpoint: http://localhost:20128/v1
- API Key: [copy from dashboard]
- Model: if/kimi-k2-thinking
+```bash
+PORT=20128 DASHBOARD_PORT=20129 omniroute
+# API: http://localhost:20128/v1
+# Dashboard: http://localhost:20129
```
-**Ennyi!** Kezdje el a kódolást az INGYENES AI modellekkel.
+### 2) Connect providers and create your API key
-**Alternatív – forrásból fut:**
+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
+
+```txt
+Base URL: http://localhost:20128/v1
+API Key: [copy from Endpoint page]
+Model: if/kimi-k2-thinking (or any provider/model prefix)
+```
+
+Works with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.
+
+### 4) Enable and validate protocols (v2.0)
+
+**MCP (for tool-driven operations):**
+
+```bash
+omniroute --mcp
+```
+
+Then connect your MCP client over `stdio` and test tools like:
+
+- `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 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
+PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev
```
---
## 🐳 Docker
-Az OmniRoute nyilvános Docker-képként érhető el a [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute) webhelyen.
+OmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
-**Gyors futás:**
+**Quick run:**
```bash
docker run -d \
@@ -778,7 +855,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Környezetfájllal:**
+**With environment file:**
```bash
# Copy and edit .env first
@@ -793,7 +870,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**A Docker Compose használata:**
+**Using Docker Compose:**
```bash
# Base profile (no CLI tools)
@@ -803,255 +880,550 @@ docker compose --profile base up -d
docker compose --profile cli up -d
```
-| Kép | Címke | Méret | Leírás |
-| ------------------------ | -------- | ------- | ---------------------- |
-| `diegosouzapw/omniroute` | `latest` | ~250 MB | Legújabb stabil kiadás |
-| `diegosouzapw/omniroute` | `1.0.3` | ~250 MB | Jelenlegi verzió |
+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.
+- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.
+- 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` | `1.0.3` | ~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
+### Gyors kezdés
+
```bash
-npm run electron:dev # Development mode
+# 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)
+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)
---
-## 💰 Árazás egy pillantásra
+## 💰 Pricing at a Glance
-| Tier | Szolgáltató | Költség | Kvóta visszaállítása | Legjobb a |
-| ----------------- | ------------------ | --------------------------- | ---------------------- | ------------------------------- |
-| **💳 ELŐFIZETÉS** | Claude Code (Pro) | 20 USD/hó | 5 óra + heti | Már előfizetett |
-| | Codex (Plus/Pro) | 20-200 USD/hó | 5 óra + heti | OpenAI felhasználók |
-| | Gemini CLI | **INGYENES** | 180 000/hó + 1 000/nap | Mindenki! |
-| | GitHub másodpilóta | 10-19 USD/hó | Havi | GitHub felhasználók |
-| **🔑 API KULCS** | NVIDIA NIM | **INGYENES** (1000 kredit) | Egyszeri | Ingyenes szintű tesztelés |
-| | DeepSeek | Felhasználásonkénti fizetés | Nincs | Legjobb ár/minőség |
-| | Groq | Ingyenes szint + fizetett | Ár korlátozott | Ultragyors következtetés |
-| | xAI (Grok) | Felhasználásonkénti fizetés | Nincs | Grok modellek |
-| | Mistral | Ingyenes szint + fizetett | Ár korlátozott | Európai AI |
-| | OpenRouter | Felhasználásonkénti fizetés | Nincs | 100+ modell |
-| **💰 OLCSÓ** | GLM-4.7 | 0,6 USD/1M | Naponta 10:00 | Költségvetési biztonsági mentés |
-| | MiniMax M2.1 | 0,2 USD/1M | 5 órás gurulás | Legolcsóbb lehetőség |
-| | Kimi K2 | 9 USD/hó lakás | 10 millió token/hó | Előrelátható költség |
-| **🆓 INGYENES** | iFlow | $0 | Korlátlan | 8 modell ingyenes |
-| | Qwen | $0 | Korlátlan | 3 modell ingyenes |
-| | Kiro | $0 | Korlátlan | Claude ingyen |
+| 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 |
+| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |
+| | 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** | iFlow | **$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 |
-**💡 Pro tipp:** Kezdje a Gemini CLI-vel (180 000 ingyenes/hónap) + iFlow (korlátlan ingyenes) kombináció = 0 USD költség!
+> 🆕 **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
+iFlow (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.
---
-## 💡 Főbb jellemzők
+---
-### 🧠 Core Routing & Intelligence
+## 🆓 Free Models — What You Actually Get
-| Funkció | Mit csinál |
-| --------------------------------------- | ------------------------------------------------------------------------------------------- |
-| 🎯 **Intelligens 4-szintű tartalék** | Automatikus útvonal: Előfizetés → API-kulcs → Olcsó → Ingyenes |
-| 📊 **Valós idejű kvótakövetés** | Élő tokenszám + visszaszámlálás visszaállítása szolgáltatónként |
-| 🔄 **Formátum fordítás** | OpenAI ↔ Claude ↔ Gemini ↔ Kurzor ↔ Kiro zökkenőmentes + válaszfertőtlenítés |
-| 👥 **Többfiókos támogatás** | Több fiók szolgáltatónként intelligens kiválasztással |
-| 🔄 **Automatikus token frissítés** | Az OAuth-tokenek automatikusan frissülnek |
-| 🎨 **Egyéni kombók** | 6 stratégia: fill-first, round-robin, p2c, random, legkevésbé használt, költségoptimalizált |
-| 🧩 **Egyedi modellek** | Adjon hozzá bármilyen modellazonosítót bármely szolgáltatóhoz |
-| 🌐 **Wildcard Router** | `provider/*` minták továbbítása bármely szolgáltatóhoz dinamikusan |
-| 🧠 **Átgondolt költségvetés** | Átjárási, automatikus, egyéni és adaptív módok érvelési modellekhez |
-| 🔀 **Model Aliases** | Auto-forward deprecated model IDs to current replacements (built-in + custom) |
-| ⚡ **Background Degradation** | Auto-route background tasks (titles, summaries) to cheaper models |
-| 💬 **Rendszer azonnali befecskendezés** | Globális rendszerkérdés minden kérelemre érvényes |
-| 📄 **Responses API** | Teljes OpenAI Responses API (`/v1/responses`) támogatás a Codexhez |
+> 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.
-### 🎵 Multimodális API-k
+### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)
-| Funkció | Mit csinál |
-| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 🖼️ **Képgenerálás** | `/v1/images/generations` — 4 szolgáltató, 9+ modell |
-| 📐 **Beágyazás** | `/v1/embeddings` — 6 szolgáltató, 9+ modell |
-| 🎤 **Audio átírás** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |
-| 🔊 **Szövegfelolvasó** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) |
-| 🛡️ **Moderálás** | `/v1/moderations` — Tartalombiztonsági ellenőrzések |
-| 🔀 **Átsorolás** | `/v1/rerank` — A dokumentumok relevancia szerinti átsorolása |
+| 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 |
-### 🛡️ Rugalmasság és biztonság
+### 🟢 IFLOW MODELS (Free OAuth — No Credit Card)
-| Funkció | Mit csinál |
-| --------------------------------- | ----------------------------------------------------------------------------------------- |
-| 🔌 **Megszakító** | Automatikus megnyitás/bezárás szolgáltatónként konfigurálható küszöbértékekkel |
-| 🛡️ **Menydörgésellenes csorda** | Mutex + szemafor sebességkorlátozás API-kulcs-szolgáltatók számára |
-| 🧠 **Szemantikus gyorsítótár** | A kétszintű gyorsítótár (aláírás + szemantikai) csökkenti a költségeket és a késleltetést |
-| ⚡ **Idempotencia kérése** | 5s dedup ablak ismétlődő kérésekhez |
-| 🔒 **TLS ujjlenyomat-hamisítás** | A TLS-alapú botészlelés megkerülése a wreq-js segítségével |
-| 🌐 **IP-szűrés** | Allowlist/blokkolista API hozzáférés-vezérléshez |
-| 📊 **Szerkeszthető díjkorlátok** | Konfigurálható fordulatszám, minimális rés és maximális egyidejű rendszerszinten |
-| 💾 **Rate Limit Persistence** | Learned limits survive restarts via SQLite with 60s debounce + 24h staleness |
-| 🔄 **Token Refresh Resilience** | Per-provider circuit breaker (5 fails→30min) + 30s timeout per attempt |
-| 🛡 **API Endpoint Protection** | Auth kapuzás + szolgáltató blokkolása a `/models` végponthoz |
-| 🔒 **Proxy láthatósága** | Színkódolt jelvények: 🟢 globális, 🟡 szolgáltató, 🔵 kapcsolatonként IP kijelzővel |
-| 🌐 **3-szintű proxykonfiguráció** | Proxyk konfigurálása globális, szolgáltatónkénti vagy kapcsolatonkénti szinten |
+| 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 |
-### 📊 Megfigyelhetőség és elemzés
+### 🟡 QWEN MODELS (Device Code Auth)
-| Funkció | Mit csinál |
-| -------------------------------- | ----------------------------------------------------------------------------------------------- | ----------- |
-| 📝 **Naplózás kérése** | Hibakeresési mód teljes kérés/válasz naplókkal |
-| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |
-| 💾 **SQLite proxynaplók** | Az állandó proxynaplók túlélik a szerver újraindítását |
-| 📊 **Analytics Dashboard** | Újragrafikusok: statisztikai kártyák, modellhasználati táblázat, szolgáltatói táblázat |
-| 📈 **Haladáskövetés** | SSE előrehaladási események engedélyezése streaming |
-| 🧪 **LLM értékelések** | Aranykészlet tesztelése 4 meccsstratégiával |
-| 🔍 **Telemetria kérése** | p50/p95/p99 késleltetési összesítés + X-Request-Id nyomkövetés |
-| 📋 **Logs Dashboard** | Egységes 4 lapos oldal: Kérelemnaplók, Proxynaplók, Auditnaplók, Konzol |
-| 🖥️ **Console Log Viewer** | Valós idejű terminál stílusú megjelenítő szintszűrővel, kereséssel, automatikus görgetéssel |
-| 📑 **Fájlalapú naplózás** | A konzolelfogó az összes kimenetet JSON-naplófájlba rögzíti | forgatással |
-| 🏥 **Egészségügyi irányítópult** | A rendszer üzemideje, az áramkör megszakítói állapotai, a zárolások, a gyorsítótár statisztikái |
-| 💰 **Költségkövetés** | Költségvetés-kezelés + modellenkénti árképzés |
+| 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) |
-### ☁️ Telepítés és szinkronizálás
+### 🟣 GEMINI CLI (Google OAuth)
-| Funkció | Mit csinál |
-| ----------------------------- | --------------------------------------------------------------------------------------------- | ------------ |
-| 💾 **Cloud Sync** | Szinkronizálja a konfigurációt az eszközök között a Cloudflare Workers | segítségével |
-| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloudflare Workers |
-| 🔑 **API-kulcskezelés** | API-kulcsok generálása, forgatása és hatóköre szolgáltatónként |
-| 🧙 **Bevezető varázsló** | 4 lépésben irányított beállítás első felhasználók számára |
-| 🔧 **CLI Tools Dashboard** | Egy kattintással konfigurálja a Claude, Codex, Cline, OpenClaw, Kilo, Antigravity |
-| 🔄 **DB biztonsági mentések** | Automatikus biztonsági mentés, visszaállítás, exportálás és importálás az összes beállításhoz |
-| 🌐 **Nemzetközivé válás** | Teljes i18n next-intl-vel – angol + portugál (Brazília) támogatás |
-| 🌍 **Nyelvválasztó** | Globe ikon a fejlécben a valós idejű nyelvváltáshoz (🇺🇸/🇧🇷) |
-| 🧹 **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 |
-| 📂 **Egyéni adattár** | `DATA_DIR` env var felülírja az alapértelmezett `~/.omniroute` tárolási útvonalat |
+| Model | Prefix | Limit | Rate Limit |
+| ------------------------ | ------ | --------------------------- | ------------- |
+| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |
+| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |
+
+### ⚫ 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
+> iFlow (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 v2.0 is built as an operational platform, not just a relay proxy.
+
+### 🆕 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 Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |
+| 🤖 **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 (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) |
+| 🤝 **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** | 9 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 combo, apply resilience profiles, reset breakers from one control surface |
+
+### 🧠 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** | 6 balancing strategies + fallback chain control |
+| 🌐 **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) |
+| 💬 **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 |
+| ----------------------------------- | -------------------------------------------------------------------------------------- |
+| 🔌 **Circuit Breakers** | Per-model trip/recover with threshold controls |
+| 🎯 **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 |
+| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |
+| 🔑 **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 |
+
+### 📊 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 |
+| 📋 **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 |
+
+### ☁️ Deployment & Platform
+
+| Feature | What It Does |
+| ----------------------------- | --------------------------------------------------------- |
+| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |
+| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |
+| 💾 **Cloud Sync** | Configuration sync via cloud worker |
+| 🔄 **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 |
+
+### Feature Deep Dive
+
+#### Smart fallback with practical cost control
+
+```txt
+Combo: "my-coding-stack"
+ 1. cc/claude-opus-4-6
+ 2. nvidia/llama-3.3-70b
+ 3. glm/glm-4.7
+ 4. if/kimi-k2-thinking
+```
+
+When quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.
+
+#### 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)
+
+#### 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)
🚀 30. "Az ügynöki munkafolyamatokat ragasztókód szétszórása nélkül kell szállítanom"
+🚀 30. "I need to ship agentic workflows without glue-code sprawl"
-A csapatok veszítenek sebességükből, amikor több ad-hoc szolgáltatást és szkriptet illesztenek össze. +Teams lose velocity when stitching multiple ad-hoc services and scripts. -**Hogyan oldja meg az OmniRoute:** +**How OmniRoute solves it:** -- Egységes végpont stratégia az ügyfelek és ügynökök számára -- Beépített protokollkezelő felhasználói felületek és füstellenőrzési útvonalak -- Gyártásra kész alapok (biztonság, naplózás, rugalmasság, biztonsági mentés) +- Unified endpoint strategy for clients and agents +- Built-in protocol management UIs and smoke validation paths +- Production-ready foundations (security, logging, resilience, backup)
-` blokkok → `reasoning_content` gondolkodó modellekhez
-- **Strukturált kimenet** — `json_schema` → Gemini's `responseMimeType`/`responseSchema`
-
-### 👥 Többfiókos támogatás
-
-- Több fiók hozzáadása szolgáltatónként
-- Automatikus körbefutó vagy prioritás alapú útvonalválasztás
-- Visszatérés a következő fiókhoz, ha valamelyik eléri a kvótát
-
-### 🔄 Token automatikus frissítése
-
-- Az OAuth-tokenek a lejárat előtt automatikusan frissülnek
-- Nincs szükség manuális újrahitelesítésre
-- Zökkenőmentes tapasztalat az összes szolgáltatónál
-
-### 🎨 Egyéni kombók
-
-- Korlátlan számú modellkombináció létrehozása
-- 6 stratégia: töltsd ki először, körbefutó, kettős választási lehetőség, véletlenszerű, legkevésbé használt, költségoptimalizált
-- Oszd meg a kombinációkat az eszközök között a Cloud Sync segítségével
-
-### 🏥 Egészségügyi irányítópult
-
-- Rendszerállapot (üzemidő, verzió, memóriahasználat)
-- A megszakítók állapotai szolgáltatónként (zárt/nyitott/félig nyitva)
-- Díjkorlát állapot és aktív zárolások
-- Az aláírás gyorsítótár statisztikái
-- Késési telemetria (p50/p95/p99) + gyorsítótár
-- Állítsa vissza az egészségi állapotot egyetlen kattintással
-
-### 🔧 Fordítói Játszótér
-
-Az OmniRoute egy erőteljes beépített fordítói játszóteret tartalmaz **4 móddal** az API-fordítások hibakereséséhez, teszteléséhez és figyeléséhez:
-
-| mód | Leírás |
-| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **💻 Játszótér** | Közvetlen formátumfordítás – illessze be az API kérés törzsét, és azonnal megtudhatja, hogyan fordítja le az OmniRoute azt a szolgáltatói formátumok között (OpenAI ↔ Claude ↔ Gemini ↔ Responses API). Példa sablonokat és formátum automatikus felismerést tartalmaz. |
-| **💬 Chat Tester** | Küldjön valódi csevegési kérelmeket az OmniRoute-on keresztül, és tekintse meg a teljes körutazást: a bemenetet, a lefordított kérést, a szolgáltatói választ és a visszafordított választ. Felbecsülhetetlen a kombinált útválasztás érvényesítéséhez. |
-| **🧪 Tesztpad** | Kötegelt tesztelési mód — határozzon meg több tesztesetet különböző bemenetekkel és várható kimenetekkel, futtassa le egyszerre, és hasonlítsa össze a szolgáltatók és modellek eredményeit. |
-| **📱 Élő monitor** | Valós idejű kérések figyelése – figyelje a bejövő kéréseket, ahogy azok az OmniRoute-on keresztül áramlanak, nézze meg a formátumfordításokat élőben, és azonnal azonosítsa a problémákat. |
-
-**Hozzáférés:** Irányítópult → Fordító (oldalsáv)
-
-### 💾 Cloud Sync
-
-- Szinkronizálja a szolgáltatókat, kombinációkat és beállításokat az eszközök között
-- Automatikus háttérszinkronizálás
-- Biztonságos titkosított tárhely
+- `GET /api/mcp/status`
+- `GET /api/mcp/tools`
+- `GET /api/mcp/audit`
+- `GET /api/mcp/audit/stats`
-## 🧪 Értékelések (Evals)
+📖 Funkció részletei
+🧩 MCP Setup (Model Context Protocol)
-### 🎯 Intelligens 4 szintes tartalék +Start MCP transport in stdio mode: -Hozzon létre kombókat automatikus visszaállítással: - -``` -Combo: "my-coding-stack" - 1. cc/claude-opus-4-6 (your subscription) - 2. nvidia/llama-3.3-70b (free NVIDIA API) - 3. glm/glm-4.7 (cheap backup, $0.6/1M) - 4. if/kimi-k2-thinking (free fallback) - -→ Auto switches when quota runs out or errors occur +```bash +omniroute --mcp ``` -### 📊 Valós idejű kvótakövetés +Recommended validation flow: -- Token fogyasztás szolgáltatónként -- Visszaszámlálás visszaállítása (5 órás, napi, heti) -- Költségbecslés a fizetett szintekre -- Havi kiadási jelentések +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. -### 🔄 Formátum fordítás +Useful APIs for automation: -Zökkenőmentes fordítás a formátumok között: - -- **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **OpenAI válaszok** -- A CLI eszköz OpenAI formátumot küld → OmniRoute lefordítja → szolgáltató natív formátumot kap -- Minden olyan eszközzel működik, amely támogatja az egyéni OpenAI végpontokat -- **Válaszfertőtlenítés** - Törli a nem szabványos mezőket a szigorú OpenAI SDK-kompatibilitás érdekében -- **Szerepnormalizálás** — `developer` → `system` nem OpenAI esetén; `system` → `user` GLM/ERNIE modellekhez -- **Gondolkodó címke kivonatolás** — `
+
🤝 A2A Setup (Agent2Agent)
-Az OmniRoute egy beépített értékelési keretrendszert tartalmaz az LLM-válasz minőségének tesztelésére egy aranykészlettel összehasonlítva. Az irányítópult **Analytics → Evals** menüpontjában érheti el. +Discover the agent: -### Beépített arany készlet +```bash +curl http://localhost:20128/.well-known/agent.json +``` -Az előre feltöltött "OmniRoute Golden Set" 10 tesztesetet tartalmaz, amelyek lefedik: +Send a task: -- Üdvözlet, matematika, földrajz, kódgenerálás -- JSON formátum megfelelés, fordítás, leértékelés -- Biztonsági elutasítás (káros tartalom), számlálás, logikai logika +```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."}]}}' +``` -### Értékelési stratégiák +Manage lifecycle: -| Stratégia | Leírás | Példa | -| ---------- | ------------------------------------------------------------------------------------------------- | -------------------------------- | -| `exact` | A kimenetnek pontosan meg kell egyeznie | `"4"` | -| `contains` | A kimenetnek tartalmaznia kell részkarakterláncot (a kis- és nagybetűk nem különböznek egymástól) | `"Paris"` | -| `regex` | A kimenetnek meg kell egyeznie a regex mintával | `"1.*2.*3"` | -| `custom` | Az egyéni JS függvény igaz/hamis | `(output) => output.length > 10` | +- `GET /api/a2a/status` +- `GET /api/a2a/tasks` +- `GET /api/a2a/tasks/:id` +- `POST /api/a2a/tasks/:id/cancel` ---- +Operational UI: -## 📖 Beállítási útmutató +- `/dashboard/a2a` for task/state/stream observability and smoke actions + +
-
+
+💳 Előfizetési szolgáltatók
+🧪 End-to-end protocol validation
+ +Validate both protocols with real clients: + +```bash +npm run test:protocols:e2e +``` + +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) @@ -1066,7 +1438,7 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Profi tipp:** Használja az Opust összetett feladatokhoz, a Sonnet pedig a sebességhez. Az OmniRoute nyomkövetési kvóta modellenként! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! ### OpenAI Codex (Plus/Pro) @@ -1080,7 +1452,24 @@ Models: cx/gpt-5.1-codex-max ``` -### Gemini CLI (INGYENES 180 000/hó!) +#### 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). + +### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -1092,9 +1481,9 @@ Models: gc/gemini-2.5-pro ``` -**Legjobb érték:** Hatalmas ingyenes szint! Használja ezt a fizetett szintek előtt. +**Best Value:** Huge free tier! Use this before paid tiers. -### GitHub másodpilóta +### GitHub Copilot ```bash Dashboard → Providers → Connect GitHub @@ -1110,88 +1499,88 @@ Models:
-
🔑 API kulcs szolgáltatók
+🔑 API Key Providers
-### NVIDIA NIM (INGYENES 1000 kredit!) +### NVIDIA NIM (FREE developer access — 70+ models) -1. Regisztráljon: [build.nvidia.com](https://build.nvidia.com) -2. Ingyenes API-kulcs beszerzése (1000 következtetési kredit) -3. Irányítópult → Szolgáltató hozzáadása → NVIDIA NIM: - - API-kulcs: `nvapi-your-key` +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` -**Modellek:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct` és több mint 50 +**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more -**Profi tipp:** OpenAI-kompatibilis API – zökkenőmentesen működik az OmniRoute formátumfordításával! +**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation! ### DeepSeek -1. Regisztráljon: [platform.deepseek.com](https://platform.deepseek.com) -2. Szerezze be az API-kulcsot -3. Irányítópult → Szolgáltató hozzáadása → DeepSeek +1. Sign up: [platform.deepseek.com](https://platform.deepseek.com) +2. Get API key +3. Dashboard → Add Provider → DeepSeek -**Modellek:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` +**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` -### Groq (ingyenes szint elérhető!) +### Groq (Free Tier Available!) -1. Regisztráljon: [console.groq.com](https://console.groq.com) -2. API-kulcs beszerzése (ingyenes szint tartalmazza) -3. Irányítópult → Szolgáltató hozzáadása → Groq +1. Sign up: [console.groq.com](https://console.groq.com) +2. Get API key (free tier included) +3. Dashboard → Add Provider → Groq -**Modellek:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` +**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` -**Profi tipp:** Ultragyors következtetés – a legjobb valós idejű kódoláshoz! +**Pro Tip:** Ultra-fast inference — best for real-time coding! -### OpenRouter (100+ modell) +### OpenRouter (100+ Models) -1. Regisztráljon: [openrouter.ai](https://openrouter.ai) -2. Szerezze be az API-kulcsot -3. Irányítópult → Szolgáltató hozzáadása → OpenRouter +1. Sign up: [openrouter.ai](https://openrouter.ai) +2. Get API key +3. Dashboard → Add Provider → OpenRouter -**Modellek:** Hozzáférés több mint 100 modellhez az összes főbb szolgáltatótól egyetlen API-kulccsal. +**Models:** Access 100+ models from all major providers through a single API key.
-
💰 Olcsó szolgáltatók (tartalék)
+💰 Cheap Providers (Backup)
-### GLM-4.7 (napi visszaállítás, 0,6 USD/1 millió) +### GLM-4.7 (Daily reset, $0.6/1M) -1. Regisztráljon: [Zhipu AI](https://open.bigmodel.cn/) -2. Szerezze be az API-kulcsot a Coding Plan-ból -3. Irányítópult → API-kulcs hozzáadása: - - Szolgáltató: `glm` - - API-kulcs: `your-key` +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` -**Használd:** `glm/glm-4.7` +**Use:** `glm/glm-4.7` -**Profi tipp:** A kódolási terv 3-szoros kvótát kínál 1/7 költséggel! Visszaállítás naponta 10:00. +**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -### MiniMax M2.1 (5 óra visszaállítás, 0,20 USD/1 millió) +### MiniMax M2.1 (5h reset, $0.20/1M) -1. Regisztráljon: [MiniMax](https://www.minimax.io/) -2. Szerezze be az API-kulcsot -3. Irányítópult → API-kulcs hozzáadása +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key +3. Dashboard → Add API Key -**Használd:** `minimax/MiniMax-M2.1` +**Use:** `minimax/MiniMax-M2.1` -**Profi tipp:** A legolcsóbb lehetőség hosszú kontextushoz (1 millió token)! +**Pro Tip:** Cheapest option for long context (1M tokens)! -### Kimi K2 (9 USD/hó lakás) +### Kimi K2 ($9/month flat) -1. Feliratkozás: [Moonshot AI](https://platform.moonshot.ai/) -2. Szerezze be az API-kulcsot -3. Irányítópult → API-kulcs hozzáadása +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key +3. Dashboard → Add API Key -**Használat:** `kimi/kimi-latest` +**Use:** `kimi/kimi-latest` -**Profi tipp:** Fix 9 USD/hó 10 millió token esetén = 0,90 USD/1 millió tényleges költség! +**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
-
🆓 INGYENES szolgáltatók (vészhelyzeti biztonsági mentés)
+🆓 FREE Providers (Emergency Backup)
-### iFlow (8 INGYENES modell) +### iFlow (5 FREE models via OAuth) ```bash Dashboard → Connect iFlow @@ -1206,7 +1595,7 @@ Models: if/deepseek-r1 ``` -### Qwen (3 INGYENES modell) +### Qwen (4 FREE models via Device Code) ```bash Dashboard → Connect Qwen @@ -1218,7 +1607,7 @@ Models: qw/qwen3-coder-flash ``` -### Kiro (Claude INGYENES) +### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro @@ -1233,9 +1622,9 @@ Models:
-
🎨 Kombók létrehozása
+🎨 Create Combos
-### 1. példa: Előfizetés maximalizálása → Olcsó biztonsági mentés +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -1249,7 +1638,7 @@ Models: Use in CLI: premium-coding ``` -### 2. példa: Csak ingyenes (nulla költség) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -1264,9 +1653,9 @@ Cost: $0 forever!
-
---
-## 🐛 Hibaelhárítás
+## Hibaelhárítás
🔧 CLI-integráció
+🔧 CLI Integration
-### Kurzor IDE +### Cursor IDE ``` Settings → Models → Advanced: @@ -1277,7 +1666,7 @@ Settings → Models → Advanced: ### Claude Code -Használja az irányítópult **CLI Tools** oldalát az egykattintásos konfiguráláshoz, vagy szerkessze manuálisan a `~/.claude/settings.json` fájlt. +Use the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually. ### Codex CLI @@ -1290,13 +1679,13 @@ codex "your prompt" ### OpenClaw -**1. lehetőség – Irányítópult (ajánlott):** +**Option 1 — Dashboard (recommended):** ``` Dashboard → CLI Tools → OpenClaw → Select Model → Apply ``` -**2. lehetőség – Kézi:** Szerkesztés `~/.openclaw/openclaw.json`: +**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`: ```json { @@ -1312,9 +1701,9 @@ Dashboard → CLI Tools → OpenClaw → Select Model → Apply } ``` -> **Megjegyzés:** Az OpenClaw csak a helyi OmniRoute-tal működik. Használja az `127.0.0.1` `localhost` helyett az IPv6-feloldási problémák elkerülése érdekében. +> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues. -### Cline / Folytatás / RooCode +### Cline / Continue / RooCode ``` Settings → API Configuration: @@ -1324,80 +1713,215 @@ Settings → API Configuration: 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. +
- Kuota berlangganan habis tanpa terpakai setiap bulannya
-- Batas kecepatan menghentikan Anda di tengah coding
-- API mahal ($20-50/bulan per penyedia)
-- Peralihan antar penyedia secara manual
-
-**OmniRoute memecahkan masalah ini:**
-
-- ✅ **Maksimalkan langganan** - Lacak kuota, gunakan setiap bit sebelum menyetel ulang
-- ✅ **Pengembalian otomatis** - Berlangganan → Kunci API → Murah → Gratis, tanpa downtime
-- ✅ **Multi-akun** - Round-robin antar akun per penyedia
-- ✅ **Universal** - Bekerja dengan Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, alat CLI apa pun
-
----
-
-## 📧 Dukungan
-
-> 💬 **Bergabunglah dengan komunitas kami!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Dapatkan bantuan, berbagi kiat, dan dapatkan informasi terbaru.
-
-- **Situs Web**: [omniroute.online](https://omniroute.online)
+- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Masalah**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Proyek Asli**: [9router by decolua](https://github.com/decolua/9router)
+- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 Cara Kerjanya
+## 🔄 How It Works
```
┌─────────────┐
@@ -227,452 +236,453 @@ Result: Never stop coding, minimal cost
---
-## 🎯 Apa yang Dipecahkan OmniRoute — 30 Masalah Nyata & Kasus Penggunaan
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **Setiap pengembang yang menggunakan alat AI menghadapi masalah ini setiap hari.** OmniRoute dibuat untuk menyelesaikan semuanya — mulai dari pembengkakan biaya hingga pemblokiran regional, mulai dari aliran OAuth yang rusak hingga operasi protokol dan kemampuan observasi perusahaan.
+> **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.
` tags no longer leak to clients in SSE streaming responses (#585) |
+| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with per-provider/account quota enforcement, idempotency, SHA-256 storage, and optional GitHub issue reporting |
+| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG → generic fallback chain |
+| 🔄 **Model Auto-Sync** | 24h scheduler and manual UI toggle to sync model lists for built-in and custom OpenAI-compatible providers |
+| 🌐 **OpenCode Zen/Go** | Two new providers from @kang-heewon via PR #530: free tier + subscription tier via `OpencodeExecutor` |
+| 🐛 **Gemini CLI OAuth** | Actionable error when `GEMINI_OAUTH_CLIENT_SECRET` is missing in Docker (was cryptic Google error) |
+| 🐛 **OpenCode config** | `saveOpenCodeConfig()` now correctly writes TOML to `XDG_CONFIG_HOME` |
+| 🐛 **Pinned model override** | `body.model` correctly set to `pinnedModel` on context-cache protection |
+| 🐛 **Codex/Claude loop** | `tool_result` blocks now converted to text to stop infinite loops |
+| 🐛 **Login redirect** | Login no longer freezes after skipping password setup |
+| 🐛 **Windows paths** | MSYS2/Git-Bash paths (`/c/...`) normalized to `C:\...` automatically |
+
+---
+
+## 🖼️ Main Dashboard
सदस्यता कोटा हर महीने अप्रयुक्त रूप से समाप्त हो जाता है
-- दर सीमा आपको कोडिंग के बीच में रोक देती है
-- महँगे API ($20-50/माह प्रति प्रदाता)
-- प्रदाताओं के बीच मैन्युअल स्विचिंग
+
+
-**OmniRoute इसका समाधान करता है:**
-
-- ✅ **सब्सक्रिप्शन अधिकतम करें** - कोटा ट्रैक करें, रीसेट से पहले हर बिट का उपयोग करें
-- ✅ **ऑटो फ़ॉलबैक** - सदस्यता → एपीआई कुंजी → सस्ता → निःशुल्क, शून्य डाउनटाइम
-- ✅ **मल्टी-अकाउंट** - प्रति प्रदाता खातों के बीच राउंड-रॉबिन
-- ✅ **यूनिवर्सल** - क्लाउड कोड, कोडेक्स, जेमिनी सीएलआई, कर्सर, क्लाइन, ओपनक्लॉ, किसी भी सीएलआई टूल के साथ काम करता है
+📡 All agents connect via 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:**
+
+- ✅ **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
+- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool
---
-## 🔄 यह कैसे काम करता है
+## 📧 Support
+
+> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.
+
+- **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`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
+
+---
+
+## 🔄 How It Works
```
┌─────────────┐
@@ -144,457 +230,459 @@ _OmniRoute के माध्यम से किसी भी AI-संचा
├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)
│ ↓ budget limit
└─→ [Tier 4: FREE] iFlow, Qwen, Kiro (unlimited)
-- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/` prefix
Result: Never stop coding, minimal cost
```
---
-## 🎯 ओमनीरूट क्या समाधान करता है - 30 वास्तविक समस्या बिंदु और उपयोग के मामले
+## 🎯 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.
` ब्लॉक → सोच मॉडल के लिए `reasoning_content`
-- **संरचित आउटपुट** — `json_schema` → मिथुन राशि का `responseMimeType`/`responseSchema`
+| 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 |
-- OAuth टोकन समाप्ति से पहले स्वचालित रूप से ताज़ा हो जाते हैं
-- किसी मैन्युअल पुन: प्रमाणीकरण की आवश्यकता नहीं है
-- सभी प्रदाताओं के बीच निर्बाध अनुभव
+> 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) 🆕
-- असीमित मॉडल संयोजन बनाएं
-- 6 रणनीतियाँ: पहले भरें, राउंड-रॉबिन, दो-विकल्पों की शक्ति, यादृच्छिक, कम से कम उपयोग, लागत-अनुकूलित
-- क्लाउड सिंक के साथ सभी डिवाइसों पर कॉम्बो साझा करें
+| 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.
-- सिस्टम स्थिति (अपटाइम, संस्करण, मेमोरी उपयोग)
-- प्रति प्रदाता सर्किट ब्रेकर की स्थिति (बंद/खुला/आधा खुला)
-- दर सीमा स्थिति और सक्रिय तालाबंदी
-- हस्ताक्षर कैश आँकड़े
-- विलंबता टेलीमेट्री (p50/p95/p99) + शीघ्र कैश
-- एक क्लिक से स्वास्थ्य स्थिति रीसेट करें
+### 🟠 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 |
-ओमनीरूट में डिबगिंग, परीक्षण और एपीआई अनुवादों की निगरानी के लिए **4 मोड** के साथ एक शक्तिशाली अंतर्निहित अनुवादक खेल का मैदान शामिल है:
+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
+> iFlow (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
-प्री-लोडेड "ओम्नीरूट गोल्डन सेट" में 10 परीक्षण मामले शामिल हैं:
+> Transcribe any audio/video for **$0** — Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.
-- नमस्ते, गणित, भूगोल, कोड जनरेशन
-- JSON प्रारूप अनुपालन, अनुवाद, मार्कडाउन
-- सुरक्षा इनकार (हानिकारक सामग्री), गिनती, बूलियन तर्क
+| 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`:**
-| रणनीति | विवरण | उदाहरण |
-| ---------- | ------------------------------------------------- | -------------------------------- |
-| `exact` | आउटपुट बिल्कुल मेल खाना चाहिए | `"4"` |
-| `contains` | आउटपुट में सबस्ट्रिंग (केस-असंवेदनशील) होना चाहिए | `"Paris"` |
-| `regex` | आउटपुट रेगेक्स पैटर्न से मेल खाना चाहिए | `"1.*2.*3"` |
-| `custom` | कस्टम जेएस फ़ंक्शन सही/गलत लौटाता है | `(output) => output.length > 10` |
+```
+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 v2.0 is built as an operational platform, not just a relay proxy.
+
+### 🆕 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 Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |
+| 🤖 **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 (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) |
+| 🤝 **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** | 9 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 combo, apply resilience profiles, reset breakers from one control surface |
+
+### 🧠 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** | 6 balancing strategies + fallback chain control |
+| 🌐 **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) |
+| 💬 **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 |
+| ----------------------------------- | -------------------------------------------------------------------------------------- |
+| 🔌 **Circuit Breakers** | Per-model trip/recover with threshold controls |
+| 🎯 **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 |
+| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |
+| 🔑 **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 |
+
+### 📊 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 |
+| 📋 **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 |
+
+### ☁️ Deployment & Platform
+
+| Feature | What It Does |
+| ----------------------------- | --------------------------------------------------------- |
+| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |
+| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |
+| 💾 **Cloud Sync** | Configuration sync via cloud worker |
+| 🔄 **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 |
+
+### Feature Deep Dive
+
+#### Smart fallback with practical cost control
+
+```txt
+Combo: "my-coding-stack"
+ 1. cc/claude-opus-4-6
+ 2. nvidia/llama-3.3-70b
+ 3. glm/glm-4.7
+ 4. if/kimi-k2-thinking
+```
+
+When quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.
+
+#### 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)
+
+#### 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
- La quota dell'abbonamento scade inutilizzata ogni mese
-- I limiti di rate ti fermano nel mezzo della programmazione
-- API costose ($20-50/mese per provider)
-- Cambio manuale tra provider
-
-**OmniRoute risolve tutto questo:**
-
-- ✅ **Massimizza gli abbonamenti** — Traccia le quote, usa tutto prima del reset
-- ✅ **Fallback automatico** — Abbonamento → API Key → Economico → Gratuito, zero downtime
-- ✅ **Multi-account** — Round-robin tra account per provider
-- ✅ **Universale** — Funziona con Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, qualsiasi strumento CLI
-
----
-
-## 📧 Supporto
-
-> 💬 **Unisciti alla nostra community!** [Gruppo WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Ottieni aiuto, condividi consigli e rimani aggiornato.
-
-- **Sito Web**: [omniroute.online](https://omniroute.online)
+- **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**: [Gruppo della comunità](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **WhatsApp**: [Gruppo della comunità](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Progetto Originale**: [9router di decolua](https://github.com/decolua/9router)
+- **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`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 Come Funziona
+## 🔄 How It Works
```
┌─────────────┐
-│ Il tuo CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
+│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
│ Tool │
└──────┬──────┘
│ http://localhost:20128/v1
↓
┌─────────────────────────────────────────┐
-│ OmniRoute (Router Intelligente) │
-│ • Traduzione formato (OpenAI ↔ Claude) │
-│ • Tracciamento quote + Embeddings + Immagini │
-│ • Rinnovo automatico dei token │
+│ OmniRoute (Smart Router) │
+│ • Format translation (OpenAI ↔ Claude) │
+│ • Quota tracking + Embeddings + Images │
+│ • Auto token refresh │
└──────┬──────────────────────────────────┘
│
- ├─→ [Tier 1: ABBONAMENTO] Claude Code, Codex, Gemini CLI
- │ ↓ quota esaurita
- ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, ecc.
- │ ↓ limite budget
- ├─→ [Tier 3: ECONOMICO] GLM ($0.6/1M), MiniMax ($0.2/1M)
- │ ↓ limite budget
- └─→ [Tier 4: GRATUITO] iFlow, Qwen, Kiro (illimitato)
+ ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI
+ │ ↓ 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] iFlow, Qwen, Kiro (unlimited)
-Risultato: Non smettere mai di programmare, costo minimo
+Result: Never stop coding, minimal cost
```
---
-## 🎯 Cosa risolve OmniRoute: 30 punti critici reali e casi d'uso
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **Ogni sviluppatore che utilizza strumenti di intelligenza artificiale affronta questi problemi quotidianamente.** OmniRoute è stato creato per risolverli tutti: dai superamenti dei costi ai blocchi regionali, dai flussi OAuth interrotti alle operazioni di protocollo e all'osservabilità aziendale.
+> **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.
サブスクリプション割り当ては毎月未使用のまま期限切れになります
-- レート制限によりコーディングの途中で停止する
-- 高価な API (プロバイダーごとに月額 20 ～ 50 ドル)
-- プロバイダー間の手動切り替え
-
-**OmniRoute はこれを解決します:**
-
-- ✅ **サブスクリプションを最大化** - クォータを追跡し、リセットする前にすべてのビットを使用します
-- ✅ **自動フォールバック** - サブスクリプション → API キー → 安価 → 無料、ダウンタイムなし
-- ✅ **マルチアカウント** - プロバイダーごとのアカウント間のラウンドロビン
-- ✅ **ユニバーサル** - Claude Code、Codex、Gemini CLI、Cursor、Cline、OpenClaw、あらゆる CLI ツールで動作します
-
----
-
-## 📧 サポート
-
-> 💬 **コミュニティに参加してください!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — ヘルプを取得し、ヒントを共有し、最新情報を入手してください。
-
-- **ウェブサイト**: [omniroute.online](https://omniroute.online)
+- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **問題**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **オリジナル プロジェクト**: [9router by decolua](https://github.com/decolua/9router)
+- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 仕組み
+## 🔄 How It Works
```
┌─────────────┐
@@ -227,452 +236,453 @@ Result: Never stop coding, minimal cost
---
-## 🎯 OmniRoute が解決するもの — 30 の実際の問題点とユースケース
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **AI ツールを使用するすべての開発者は、これらの問題に日々直面しています。** OmniRoute は、コスト超過から地域ブロック、壊れた OAuth フローからプロトコル操作、企業の可観測性まで、それらすべてを解決するために構築されました。
+> **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.
구독 할당량은 매달 사용하지 않은 채 만료됩니다.
-- 속도 제한으로 인해 코딩이 중단됩니다.
-- 고가의 API(공급자당 월 $20-50)
-- 공급자 간 수동 전환
-
-**OmniRoute는 이 문제를 해결합니다.**
-
-- ✅ **구독 극대화** - 할당량을 추적하고 재설정하기 전에 모든 비트를 사용하세요.
-- ✅ **자동 대체** - 구독 → API 키 → 저렴한 → 무료, 다운타임 없음
-- ✅ **다중 계정** - 공급자별 계정 간 라운드 로빈
-- ✅ **유니버설** - Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, 모든 CLI 도구와 함께 작동
-
----
-
-## 📧 지원
-
-> 💬 **커뮤니티에 가입하세요!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — 도움을 받고, 팁을 공유하고, 최신 소식을 받아보세요.
-
-- **웹사이트**: [omniroute.online](https://omniroute.online)
+- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **문제**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **원래 프로젝트**: [9router by decolua](https://github.com/decolua/9router)
+- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 작동 방식
+## 🔄 How It Works
```
┌─────────────┐
@@ -227,451 +236,453 @@ Result: Never stop coding, minimal cost
---
-## 🎯 OmniRoute가 해결하는 것 — 30가지 실제 문제점 및 사용 사례
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **AI 도구를 사용하는 모든 개발자는 매일 이러한 문제에 직면합니다.** OmniRoute는 비용 초과부터 지역적 차단, 손상된 OAuth 흐름부터 프로토콜 운영 및 기업 관찰 가능성까지 모든 문제를 해결하기 위해 구축되었습니다.
+> **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.
Kuota langganan tamat tempoh tidak digunakan setiap bulan
-- Had kadar menghalang anda pertengahan pengekodan
-- API Mahal ($20-50/bulan bagi setiap pembekal)
-- Pertukaran manual antara pembekal
-
-**OmniRoute menyelesaikan ini:**
-
-- ✅ **Maksimumkan langganan** - Jejaki kuota, gunakan setiap bit sebelum ditetapkan semula
-- ✅ **Auto sandaran** - Langganan → Kunci API → Murah → Percuma, masa henti sifar
-- ✅ **Berbilang akaun** - Round-robin antara akaun bagi setiap pembekal
-- ✅ **Universal** - Berfungsi dengan Kod Claude, Codex, Gemini CLI, Kursor, Cline, OpenClaw, sebarang alat CLI
-
----
-
-## 📧 Sokongan
-
-> 💬 **Sertai komuniti kami!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Dapatkan bantuan, kongsi petua dan kekal kemas kini.
-
-- **Laman web**: [omniroute.online](https://omniroute.online)
+- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Isu**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Projek Asal**: [9router by decolua](https://github.com/decolua/9router)
+- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 Cara Ia Berfungsi
+## 🔄 How It Works
```
┌─────────────┐
@@ -227,451 +236,453 @@ Result: Never stop coding, minimal cost
---
-## 🎯 Perkara yang Selesaikan OmniRoute — 30 Titik Sakit Nyata & Kes Penggunaan
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **Setiap pembangun yang menggunakan alatan AI menghadapi masalah ini setiap hari.** OmniRoute dibina untuk menyelesaikan kesemuanya — daripada lebihan kos kepada blok serantau, daripada aliran OAuth yang rosak kepada operasi protokol dan kebolehmerhatian perusahaan.
+> **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.
Het abonnementsquotum verloopt elke maand ongebruikt
-- Snelheidslimieten voorkomen dat u halverwege codeert
-- Dure API's ($20-50/maand per provider)
-- Handmatig schakelen tussen providers
-
-**OmniRoute lost dit op:**
-
-- ✅ **Maximaliseer abonnementen** - Houd quota bij, gebruik elk bit voordat u het opnieuw instelt
-- ✅ **Automatische fallback** - Abonnement → API-sleutel → Goedkoop → Gratis, geen downtime
-- ✅ **Multi-account** - Round-robin tussen accounts per provider
-- ✅ **Universeel** - Werkt met Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, elke CLI-tool
-
----
-
-## 📧 Ondersteuning
-
-> 💬 **Word lid van onze community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Krijg hulp, deel tips en blijf op de hoogte.
+> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.
- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Problemen**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Origineel project**: [9router by decolua](https://github.com/decolua/9router)
+- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 Hoe het werkt
+## 🔄 How It Works
```
┌─────────────┐
@@ -227,451 +236,453 @@ Result: Never stop coding, minimal cost
---
-## 🎯 Wat OmniRoute oplost — 30 echte pijnpunten en gebruiksscenario's
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **Elke ontwikkelaar die AI-tools gebruikt, wordt dagelijks met deze problemen geconfronteerd.** OmniRoute is gebouwd om ze allemaal op te lossen: van kostenoverschrijdingen tot regionale blokkades, van kapotte OAuth-stromen tot protocolbewerkingen en bedrijfsobservatie.
+> **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.
Abonnementskvoten utløper ubrukt hver måned
-- Takstgrenser stopper deg med midtkoding
-- Dyre APIer ($20–50/måned per leverandør)
-- Manuell veksling mellom tilbydere
-
-**OmniRoute løser dette:**
-
-- ✅ **Maksimer abonnementer** - Spor kvote, bruk hver bit før tilbakestilling
-- ✅ **Automatisk fallback** - Abonnement → API-nøkkel → Billig → Gratis, null nedetid
-- ✅ **Multi-konto** - Round-robin mellom kontoer per leverandør
-- ✅ **Universal** - Fungerer med Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, hvilket som helst CLI-verktøy
-
----
-
-## 📧 Støtte
-
-> 💬 **Bli med i fellesskapet vårt!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Få hjelp, del tips og hold deg oppdatert.
-
-- **Nettsted**: [omniroute.online](https://omniroute.online)
+- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Problemer**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Originalt prosjekt**: [9router by decolua](https://github.com/decolua/9router)
+- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 Hvordan det fungerer
+## 🔄 How It Works
```
┌─────────────┐
@@ -227,451 +236,453 @@ Result: Never stop coding, minimal cost
---
-## 🎯 Hva OmniRoute løser — 30 ekte smertepoeng og brukstilfeller
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **Hver utviklere som bruker AI-verktøy møter disse problemene daglig.** OmniRoute ble bygget for å løse dem alle – fra kostnadsoverskridelser til regionale blokker, fra ødelagte OAuth-flyter til protokolloperasjoner og observerbarhet i bedrifter.
+> **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.
Mag-e-expire ang quota ng subscription na hindi nagamit bawat buwan
-- Pinipigilan ka ng mga limitasyon sa rate sa mid-coding
-- Mga Mamahaling API ($20-50/buwan bawat provider)
-- Manu-manong paglipat sa pagitan ng mga provider
-
-**Sumalutas ito ng OmniRoute:**
-
-- ✅ **I-maximize ang mga subscription** - Subaybayan ang quota, gamitin ang bawat bit bago i-reset
-- ✅ **Auto fallback** - Subscription → API Key → Mura → Libre, zero downtime
-- ✅ **Multi-account** - Round-robin sa pagitan ng mga account sa bawat provider
-- ✅ **Universal** - Gumagana sa Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, anumang CLI tool
-
----
-
-## 📧 Suporta
-
-> 💬 **Sumali sa aming komunidad!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Humingi ng tulong, magbahagi ng mga tip, at manatiling updated.
+> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.
- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Mga Isyu**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Orihinal na Proyekto**: [9router by decolua](https://github.com/decolua/9router)
+- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 Paano Ito Gumagana
+## 🔄 How It Works
```
┌─────────────┐
@@ -227,451 +236,453 @@ Result: Never stop coding, minimal cost
---
-## 🎯 Ano ang Lutasin ng OmniRoute — 30 Tunay na Pain Points at Mga Kaso ng Paggamit
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **Ang bawat developer na gumagamit ng mga tool ng AI ay nahaharap sa mga problemang ito araw-araw.** Binuo ang OmniRoute para lutasin ang lahat ng ito — mula sa mga pag-overrun sa gastos hanggang sa mga panrehiyong bloke, mula sa mga sirang daloy ng OAuth hanggang sa mga pagpapatakbo ng protocol at pagmamasid sa enterprise.
+> **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.
A cota de assinatura expira sem ser utilizada todos os meses
-- Os limites de taxa impedem você no meio da codificação
-- APIs caras (US$ 20-50/mês por provedor)
-- Troca manual entre provedores
-
-**OmniRoute resolve isso:**
-
-- ✅ **Maximize as assinaturas** - Rastreie a cota, use cada bit antes de redefinir
-- ✅ **Fullback automático** - Assinatura → Chave de API → Barato → Gratuito, tempo de inatividade zero
-- ✅ **Múltiplas contas** - Round-robin entre contas por provedor
-- ✅ **Universal** - Funciona com Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, qualquer ferramenta CLI
-
----
-
-## 📧 Suporte
-
-> 💬 **Junte-se à nossa comunidade!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Obtenha ajuda, compartilhe dicas e fique atualizado.
-
-- **Site**: [omniroute.online](https://omniroute.online)
+- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Problemas**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Projeto Original**: [9router by decolua](https://github.com/decolua/9router)
+- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 Como funciona
+## 🔄 How It Works
```
┌─────────────┐
@@ -227,452 +236,453 @@ Result: Never stop coding, minimal cost
---
-## 🎯 O que o OmniRoute resolve — 30 pontos reais de dor e casos de uso
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **Todo desenvolvedor que usa ferramentas de IA enfrenta esses problemas diariamente.** O OmniRoute foi criado para resolver todos eles, desde custos excessivos até bloqueios regionais, desde fluxos quebrados de OAuth até operações de protocolo e observabilidade empresarial.
+> **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.
Cota de abonament expiră neutilizată în fiecare lună
-- Limitele ratelor te opresc la mijloc de codare
-- API-uri scumpe (20-50 USD/lună per furnizor)
-- Comutare manuală între furnizori
-
-**OmniRoute rezolvă asta:**
-
-- ✅ **Maximizați abonamentele** - Urmăriți cota, utilizați fiecare bit înainte de resetare
-- ✅ **Auto de rezervă** - Abonament → Cheie API → Ieftin → Gratuit, timp de nefuncționare zero
-- ✅ **Multi-cont** - Round-robin între conturi pentru fiecare furnizor
-- ✅ **Universal** - Funcționează cu Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, orice instrument CLI
-
----
-
-## 📧 Suport
-
-> 💬 **Alăturați-vă comunității noastre!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Obțineți ajutor, împărtășiți sfaturi și fiți la curent.
-
-- **Site web**: [omniroute.online](https://omniroute.online)
+- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Probleme**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Proiect original**: [9router by decolua](https://github.com/decolua/9router)
+- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 Cum funcționează
+## 🔄 How It Works
```
┌─────────────┐
@@ -227,453 +236,453 @@ Result: Never stop coding, minimal cost
---
-## 🎯 Ce rezolvă OmniRoute — 30 de puncte reale de durere și cazuri de utilizare
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **Fiecare dezvoltator care folosește instrumente AI se confruntă zilnic cu aceste probleme.** OmniRoute a fost creat pentru a le rezolva pe toate - de la depășiri de costuri la blocaje regionale, de la fluxuri OAuth întrerupte la operațiuni de protocol și observabilitate a întreprinderii.
+> **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.
Квота подписки истекает неиспользованной каждый месяц
-- Лимиты скорости останавливают вас посреди программирования
-- Дорогие API ($20-50/месяц за провайдера)
-- Ручное переключение между провайдерами
-
-**OmniRoute решает это:**
-
-- ✅ **Максимизируйте подписки** — Отслеживайте квоты, используйте всё до сброса
-- ✅ **Автоматический fallback** — Подписка → API Key → Дешёвый → Бесплатный, нулевой простой
-- ✅ **Мульти-аккаунт** — Round-robin между аккаунтами каждого провайдера
-- ✅ **Универсальный** — Работает с Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, любым CLI-инструментом
-
----
-
-## 📧 Поддержка
-
-> 💬 **Присоединяйтесь к сообществу!** [Группа WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Получайте помощь, делитесь советами и оставайтесь в курсе.
-
-- **Сайт**: [omniroute.online](https://omniroute.online)
+- **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**: [Группа сообщества](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Оригинальный проект**: [9router от decolua](https://github.com/decolua/9router)
+- **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`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 Как это работает
+## 🔄 How It Works
```
┌─────────────┐
-│ Ваш CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
+│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
│ Tool │
└──────┬──────┘
│ http://localhost:20128/v1
↓
┌─────────────────────────────────────────┐
-│ OmniRoute (Умный маршрутизатор) │
-│ • Трансляция формата (OpenAI ↔ Claude) │
-│ • Отслеживание квот + Embeddings + Изображения │
-│ • Автообновление токенов │
+│ OmniRoute (Smart Router) │
+│ • Format translation (OpenAI ↔ Claude) │
+│ • Quota tracking + Embeddings + Images │
+│ • Auto token refresh │
└──────┬──────────────────────────────────┘
│
- ├─→ [Tier 1: ПОДПИСКА] Claude Code, Codex, Gemini CLI
- │ ↓ квота исчерпана
- ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM и др.
- │ ↓ лимит бюджета
- ├─→ [Tier 3: ДЕШЁВЫЙ] GLM ($0.6/1M), MiniMax ($0.2/1M)
- │ ↓ лимит бюджета
- └─→ [Tier 4: БЕСПЛАТНЫЙ] iFlow, Qwen, Kiro (неограниченно)
+ ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI
+ │ ↓ 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] iFlow, Qwen, Kiro (unlimited)
-Результат: Никогда не прекращайте программировать, минимальные затраты
+Result: Never stop coding, minimal cost
```
---
-## 🎯 Что решает OmniRoute — 30 реальных проблем и вариантов использования
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **Каждый разработчик, использующий инструменты искусственного интеллекта, ежедневно сталкивается с этими проблемами.** OmniRoute был создан для решения всех этих проблем — от перерасхода средств до региональных блоков, от нарушенных потоков OAuth до операций протокола и наблюдения за предприятием.
+> **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.
Kvóta odberu vyprší nevyužitá každý mesiac
-- Obmedzenia sadzieb vás zastavia uprostred kódovania
-- drahé rozhrania API (20 – 50 USD mesačne na poskytovateľa)
-- Manuálne prepínanie medzi poskytovateľmi
-
-**OmniRoute to rieši:**
-
-- ✅ **Maximalizujte odbery** - Sledujte kvótu, pred resetovaním použite každý bit
-- ✅ **Automatická záloha** - Predplatné → Kľúč API → Lacné → Bezplatne, nulové prestoje
-- ✅ **Viaceré účty** - Obojstranne medzi účtami na poskytovateľa
-- ✅ **Universal** - Funguje s Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, akýmkoľvek nástrojom CLI
-
----
-
-## 📧 Podpora
-
-> 💬 **Pripojte sa k našej komunite!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Získajte pomoc, zdieľajte tipy a buďte informovaní.
-
-- **Web**: [omniroute.online](https://omniroute.online)
+- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Problémy**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Pôvodný projekt**: [9router by decolua](https://github.com/decolua/9router)
+- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 Ako to funguje
+## 🔄 How It Works
```
┌─────────────┐
@@ -227,455 +236,453 @@ Result: Never stop coding, minimal cost
---
-## 🎯 Čo OmniRoute rieši — 30 bodov skutočnej bolesti a prípadov použitia
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **Každý vývojár, ktorý používa nástroje AI, čelí týmto problémom denne.** OmniRoute bol vytvorený tak, aby ich všetky vyriešil – od prekročenia nákladov po regionálne bloky, od prerušených tokov OAuth po operácie protokolov a pozorovateľnosť podniku.
+> **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.
Kattintson a hibaelhárítási útmutató kibontásához
+Click to expand troubleshooting guide
-**"A nyelvi modell nem adott üzenetet"** +**"Language model did not provide messages"** -- A szolgáltatói kvóta kimerült → Ellenőrizze az irányítópult kvótakövetőjét -- Megoldás: Használjon kombinált tartalékot, vagy váltson olcsóbb szintre +- Provider quota exhausted → Check dashboard quota tracker +- Solution: Use combo fallback or switch to cheaper tier -**Drátakorlát** +**Rate limiting** -- Előfizetési kvóta lejárt → Tartalék a GLM/MiniMax-hoz -- Kombinó hozzáadása: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Subscription quota out → Fallback to GLM/MiniMax +- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -**OAuth token lejárt** +**OAuth token expired** -- Az OmniRoute automatikusan frissíti -- Ha a problémák továbbra is fennállnak: Irányítópult → Szolgáltató → Újracsatlakozás +- Auto-refreshed by OmniRoute +- If issues persist: Dashboard → Provider → Reconnect -**Magas költségek** +**High costs** -- Ellenőrizze a használati statisztikákat az Irányítópult → Költségek menüpontban -- Állítsa át az elsődleges modellt GLM/MiniMax-ra -- Használjon ingyenes réteget (Gemini CLI, iFlow) a nem kritikus feladatokhoz +- Check usage stats in Dashboard → Costs +- Switch primary model to GLM/MiniMax +- Use free tier (Gemini CLI, iFlow) for non-critical tasks -**A műszerfal rossz porton nyílik meg** +**Dashboard/API ports are wrong** -- `PORT=20128` és `NEXT_PUBLIC_BASE_URL=http://localhost:20128` beállítása +- `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) -**Felhő szinkronizálási hibák** +**Cloud sync errors** -- Ellenőrizze, hogy `BASE_URL` mutat a futó példányra -- Ellenőrizzen `CLOUD_URL` pontot a várható felhő-végponthoz -- Tartsa az `NEXT_PUBLIC_*` értékeket a szerveroldali értékekkel összhangban +- 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 -**Az első bejelentkezés nem működik** +**First login not working** -- Ellenőrizze a `INITIAL_PASSWORD`-t itt: `.env` -- Ha nincs beállítva, a tartalék jelszó: `123456` +- Check `INITIAL_PASSWORD` in `.env` +- If unset, fallback password is `123456` -**Nincs kérésnapló** +**No request logs** -- Állítsa be `ENABLE_REQUEST_LOGS=true` a `.env`-ban +- Set `ENABLE_REQUEST_LOGS=true` in `.env` -**A csatlakozási teszt „Érvénytelen” üzenetet mutat az OpenAI-kompatibilis szolgáltatók esetében** +**Connection test shows "Invalid" for OpenAI-compatible providers** -- Sok szolgáltató nem tesz közzé `/models` végpontot -- Az OmniRoute v1.0.6+ tartalmazza a tartalék érvényesítést a csevegés befejezésén keresztül -- Győződjön meg arról, hogy az alap URL tartalmazza a `/v1` utótagot +- 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 +### 🔐 OAuth on a Remote Server + -> **⚠️ FONTOS az OmniRoute em VPS/Docker/servidor Remoto használatához** +> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server** -### OAuth +#### Why does Antigravity / Gemini CLI OAuth fail on remote servers? -Az **Antigravitáció** és a **Gemini CLI** usam **Google OAuth 2.0** hitelesítése. A Google exige que a `redirect_uri` nincs fluxo OAuth seja **exatamente** uma das URI-k pre-cadastradas no Google Cloud Console do aplicativo. +The **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console. -As credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para `localhost`**. Quando você acessa o OmniRoute em um servidor Remoto (pl.: `https://omniroute.meuservidor.com`), o Google rejeita a autenticação com: +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 ``` -### Megoldás: A suas próprias credenciais OAuth konfigurálása +#### Solution: Configure your own OAuth credentials -Você precisa criar um **OAuth 2.0 ügyfél-azonosító** nincs Google Cloud Console com egy URI do seu servidor. +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 + +# For Gemini CLI: +GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com +GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +``` + +**6. Restart OmniRoute** + +```bash +# npm: +npm run dev + +# Docker: +docker restart omniroute +``` + +**7. Try connecting again** + +Dashboard → Providers → Antigravity (or Gemini CLI) → OAuth + +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. + +--- + +
+
-- **Futtatási idejű**: Node.js 18–22 LTS (⚠️ A Node.js 24+ **nem támogatott** - A `better-sqlite3` natív binárisok nem kompatibilisek)
-- **Nyelv**: TypeScript 5.9 – **100% TypeScript** `src/` és `open-sse/` (v1.0.6) között
-- **Keretrendszer**: Next.js 16 + React 19 + Tailwind CSS 4
-- **Adatbázis**: LowDB (JSON) + SQLite (tartomány állapota + proxynaplók)
-- **Streaming**: Szerver által küldött események (SSE)
-- **Auth**: OAuth 2.0 (PKCE) + JWT + API kulcsok
-- **Tesztelés**: Node.js tesztfutó (368+ egységteszt)
-- **CI/CD**: GitHub Actions (automatikus npm közzététel + Docker Hub kiadáskor)
-- **Webhely**: [omniroute.online](https://omniroute.online)
-- **Csomag**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
-- **Dokker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
-- **Rugalmasság**: megszakító, exponenciális visszakapcsolás, mennydörgés elleni csorda, TLS-hamisítás
-
----
-
-## 📖 Dokumentáció
-
-| dokumentum | Leírás |
-| -------------------------------------------- | -------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Szolgáltatók, kombók, CLI-integráció, telepítés |
-| [API Reference](docs/API_REFERENCE.md) | Minden végpont példákkal |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Gyakori problémák és megoldások |
-| [Architecture](docs/ARCHITECTURE.md) | Rendszerarchitektúra és belső elemek |
-| [Contributing](CONTRIBUTING.md) | Fejlesztési beállítások és irányelvek |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specifikáció |
-| [Security Policy](SECURITY.md) | Sebezhetőségi jelentések és biztonsági gyakorlatok |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Teljes útmutató: VM + nginx + Cloudflare beállítás |
-| [Features Gallery](docs/FEATURES.md) | Vizuális irányítópult bemutató képernyőképekkel |
-
-### 📸 Irányítópult előnézete
+## 🛠️ Tech Stack
🇧🇷 Versão em Português
+ +#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos? + +Os provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo. + +As credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticação com: + +``` +Error 400: redirect_uri_mismatch +``` + +#### Solução: Configure suas próprias credenciais OAuth + +Você precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor. #### Passo a passo @@ -1405,27 +1929,27 @@ Você precisa criar um **OAuth 2.0 ügyfél-azonosító** nincs Google Cloud Con Abra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) -**2. Crie um novo OAuth 2.0 ügyfél-azonosító** +**2. Crie um novo OAuth 2.0 Client ID** -- Kattintson a gombra **"+ Hitelesítési adatok létrehozása"** → **"OAuth-kliens-azonosító"** -- Tipo de Aplicativo: **"Web alkalmazás"** -- Név: escolha qualquer nome (pl.: `OmniRoute Remote`) +- Clique em **"+ Create Credentials"** → **"OAuth client ID"** +- Tipo de aplicativo: **"Web application"** +- Nome: escolha qualquer nome (ex: `OmniRoute Remote`) -**3. Adicione mint engedélyezett átirányítási URI** +**3. Adicione as Authorized Redirect URIs** -No campo **"Engedélyezett átirányítási URI-k"**, kiegészítés: +No campo **"Authorized redirect URIs"**, adicione: ``` https://seu-servidor.com/callback ``` -> Helyettesítő `seu-servidor.com` pelo domínio vagy IP do seu servidor (beleértve a porta se necessário-t is, pl.: `http://45.33.32.156:20128/callback`). +> Substitua `seu-servidor.com` pelo domínio ou IP do seu servidor (inclua a porta se necessário, ex: `http://45.33.32.156:20128/callback`). -**4. Másolat mentése hitelesítésként** +**4. Salve e copie as credenciais** Após criar, o Google mostrará o **Client ID** e o **Client Secret**. -**5. Konfigurálás variáveis de ambienteként** +**5. Configure as variáveis de ambiente** No seu `.env` (ou nas variáveis de ambiente do Docker): @@ -1452,21 +1976,21 @@ docker restart omniroute **7. Tente conectar novamente** -Irányítópult → Szolgáltatók → Antigravity (vagy Gemini CLI) → OAuth +Dashboard → Providers → Antigravity (ou Gemini CLI) → OAuth Agora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará. --- -### Kerülő megoldás temporário (sem configurar credenciais próprias) +#### Workaround temporário (sem configurar credenciais próprias) Se não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**: -1. OmniRoute abrirá a Google autorização URL-jét +1. O OmniRoute abrirá a URL de autorização do Google 2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto) -3. ** Teljes URL másolása** da barra de endereço do seu browser (mesmo que a página não carregue) +3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue) 4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute -5. Kattintson a **"Connect"** gombra +5. Clique em **"Connect"** > Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não. @@ -1474,128 +1998,123 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux --- -## 🛠️ +
-
---
-## 🗺️
+## Dokumentáció
-Az OmniRoute **210+ funkciót tervez** több fejlesztési fázisban. Íme a legfontosabb területek:
-
-| Kategória | Tervezett funkciók | Kiemelések |
-| ----------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------ |
-| 🧠 **Útválasztás és intelligencia** | 25+ | Legkisebb késleltetésű útválasztás, címke alapú útválasztás, kvóta elővizsgálat, P2C-fiók kiválasztása |
-| 🔒 **Biztonság és megfelelőség** | 20+ | SSRF keményítés, hitelesítő adatok álcázása, végpontonkénti sebességkorlát, felügyeleti kulcs hatóköre |
-| 📊 **Megfigyelhetőség** | 15+ | OpenTelemetry integráció, valós idejű kvótafigyelés, modellenkénti költségkövetés |
-| 🔄 ** Szolgáltatói integrációk** | 20+ | Dinamikus modellnyilvántartás, szolgáltatói leállások, többfiókos Codex, másodpilóta kvótaelemzés |
-| ⚡ **Teljesítmény** | 15+ | Kettős gyorsítótárréteg, gyorsítótár, válaszgyorsítótár, folyamatos adatfolyam, kötegelt API |
-| 🌐 **Ökoszisztéma** | 10+ | WebSocket API, config hot-reload, elosztott konfigurációs tároló, kereskedelmi mód |
-
-### 🔜 Hamarosan
-
-- 🔗 **OpenCode integráció** - Natív szolgáltatói támogatás az OpenCode AI kódoló IDE-hez
-- 🔗 **TRAE integráció** — A TRAE AI fejlesztési keret teljes támogatása
-- 📦 **Batch API** - Aszinkron kötegelt feldolgozás tömeges kérésekhez
-- 🎯 **Címke alapú útválasztás** - Egyéni címkéken és metaadatokon alapuló útvonalkérések
-- 💰 **Legalacsonyabb költségű stratégia** - Automatikusan válassza ki a legolcsóbb elérhető szolgáltatót
-
-> 📝 A teljes funkció specifikációi a [link](docs/new-features/) címen érhetők el (217 részletes specifikáció)
+| Document | Description |
+| ---------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 16 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/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
+| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
-## 👥 Közreműködők
+## 🗺️ Roadmap
+
+OmniRoute has **210+ 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, P2C account selection |
+| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |
+| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |
+| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider 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
[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
-### Hogyan járuljunk hozzá
+### How to Contribute
-1. Fork a tároló
-2. Hozza létre saját jellemző ágát (`git checkout -b feature/amazing-feature`)
-3. Végezze el módosításait (`git commit -m 'Add amazing feature'`)
-4. Nyomja az ágra (`git push origin feature/amazing-feature`)
-5. Nyisson meg egy lehívási kérelmet
+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
-A részletes útmutatásért lásd: [CONTRIBUTING.md](CONTRIBUTING.md).
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
-### Új verzió kiadása
+### Releasing a New Version
```bash
# Create a release — npm publish happens automatically
-gh release create v1.0.6 --title "v1.0.6" --generate-notes
+gh release create v2.0.0 --title "v2.0.0" --generate-notes
```
---
-## 📊 Csillagtörténet
+## 📊 Star History
## Stargazers over time
## [](https://starchart.cc/diegosouzapw/OmniRoute)
-## 🙏 Köszönetnyilvánítás
+## 🙏 Acknowledgments
-Külön köszönet **[9router](https://github.com/decolua/9router)**, **[decolua](https://github.com/decolua)** – az eredeti projekt, amely ezt a villát inspirálta. Az OmniRoute erre a hihetetlen alapra épít további funkciókkal, multimodális API-kkal és teljes TypeScript-újraírással.
+Special thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.
-Külön köszönet **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** – az eredeti Go implementációnak, amely ihlette ezt a JavaScript-portot.
+Special thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.
---
-## 📄 Licenc
+## Licenc
-MIT-licenc – a részletekért lásd: [LICENSE](LICENSE).
+MIT License - see [LICENSE](LICENSE) for details.
---
Kattintson az irányítópult képernyőképeinek megtekintéséhez
+Click to expand tech stack details
-| Oldal | Képernyőkép | -| --------------------- | ------------------------------------------------- | -| **Szolgáltatók** |  | -| **Combos** |  | -| **Analytics** |  | -| **Egészség** |  | -| **Fordító** |  | -| **Beállítások** |  | -| **CLI eszközök** |  | -| **Használati naplók** |  | -| **Végpont** |  | +- **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**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions) +- **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
- A ❤️ segítségével készült a 24/7 kódoló fejlesztőknek
+ Built with ❤️ for developers who code 24/7
omniroute.online
+
diff --git a/docs/i18n/hu/docs/FEATURES.md b/docs/i18n/hu/docs/FEATURES.md
new file mode 100644
index 0000000000..47af714d7e
--- /dev/null
+++ b/docs/i18n/hu/docs/FEATURES.md
@@ -0,0 +1,145 @@
+# OmniRoute — Dashboard Features Gallery (Magyar)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/FEATURES.md) · 🇪🇸 [es](../../es/docs/FEATURES.md) · 🇫🇷 [fr](../../fr/docs/FEATURES.md) · 🇩🇪 [de](../../de/docs/FEATURES.md) · 🇮🇹 [it](../../it/docs/FEATURES.md) · 🇷🇺 [ru](../../ru/docs/FEATURES.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FEATURES.md) · 🇯🇵 [ja](../../ja/docs/FEATURES.md) · 🇰🇷 [ko](../../ko/docs/FEATURES.md) · 🇸🇦 [ar](../../ar/docs/FEATURES.md) · 🇮🇳 [in](../../in/docs/FEATURES.md) · 🇹🇭 [th](../../th/docs/FEATURES.md) · 🇻🇳 [vi](../../vi/docs/FEATURES.md) · 🇮🇩 [id](../../id/docs/FEATURES.md) · 🇲🇾 [ms](../../ms/docs/FEATURES.md) · 🇳🇱 [nl](../../nl/docs/FEATURES.md) · 🇵🇱 [pl](../../pl/docs/FEATURES.md) · 🇸🇪 [sv](../../sv/docs/FEATURES.md) · 🇳🇴 [no](../../no/docs/FEATURES.md) · 🇩🇰 [da](../../da/docs/FEATURES.md) · 🇫🇮 [fi](../../fi/docs/FEATURES.md) · 🇵🇹 [pt](../../pt/docs/FEATURES.md) · 🇷🇴 [ro](../../ro/docs/FEATURES.md) · 🇭🇺 [hu](../../hu/docs/FEATURES.md) · 🇧🇬 [bg](../../bg/docs/FEATURES.md) · 🇸🇰 [sk](../../sk/docs/FEATURES.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FEATURES.md) · 🇮🇱 [he](../../he/docs/FEATURES.md) · 🇵🇭 [phi](../../phi/docs/FEATURES.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FEATURES.md)
+
+---
+
+Visual guide to every section of the OmniRoute dashboard.
+
+---
+
+## 🔌 Providers
+
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
+
+
+
+---
+
+## 🎨 Combos
+
+Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
+
+
+
+---
+
+## 📊 Analytics
+
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
+
+
+
+---
+
+## 🏥 System Health
+
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+
+
+
+---
+
+## 🔧 Translator Playground
+
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
+
+
+
+---
+
+## 🎮 Model Playground _(v2.0.9+)_
+
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
+
+---
+
+## 🎨 Themes _(v2.0.5+)_
+
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
+
+## ⚙️ Settings
+
+Comprehensive settings panel with tabs:
+
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning
+- **Advanced** — Configuration overrides
+
+
+
+---
+
+## 🔧 CLI Tools
+
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
+
+
+
+---
+
+## 🤖 CLI Agents _(v2.0.11+)_
+
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
+
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
+
+---
+
+## 🖼️ Media _(v2.0.3+)_
+
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
+
+## 📝 Request Logs
+
+Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
+
+
+
+---
+
+## 🌐 API Endpoint
+
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
+
+
+
+---
+
+## 🔑 API Key Management
+
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
+
+---
+
+## 📋 Audit Log
+
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
+
+---
+
+## 🖥️ Desktop Application
+
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
+
+Key features:
+
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
+
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.
diff --git a/docs/i18n/id/README.md b/docs/i18n/id/README.md
index 8338f199e2..11c8657316 100644
--- a/docs/i18n/id/README.md
+++ b/docs/i18n/id/README.md
@@ -1,24 +1,94 @@
-omniroute.online
-
-
- # 🚀 OmniRoute — Gerbang AI Gratis
+# 🚀 OmniRoute — The Free AI Gateway (Bahasa Indonesia)
-### Jangan pernah berhenti membuat kode. Perutean cerdas ke **model AI GRATIS & berbiaya rendah** dengan fallback otomatis.
-
-_Proksi API universal Anda — satu titik akhir, 36+ penyedia, tanpa waktu henti._
-
-**Penyelesaian Obrolan • Penyematan • Pembuatan Gambar • Audio • Pemeringkatan Ulang • 100% TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Penyedia AI gratis untuk agen coding favorit Anda
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Hubungkan alat IDE atau CLI apa pun yang didukung AI melalui OmniRoute — gerbang API gratis untuk pengkodean tanpa batas._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+` tags no longer leak to clients in SSE streaming responses (#585) |
+| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with per-provider/account quota enforcement, idempotency, SHA-256 storage, and optional GitHub issue reporting |
+| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG → generic fallback chain |
+| 🔄 **Model Auto-Sync** | 24h scheduler and manual UI toggle to sync model lists for built-in and custom OpenAI-compatible providers |
+| 🌐 **OpenCode Zen/Go** | Two new providers from @kang-heewon via PR #530: free tier + subscription tier via `OpencodeExecutor` |
+| 🐛 **Gemini CLI OAuth** | Actionable error when `GEMINI_OAUTH_CLIENT_SECRET` is missing in Docker (was cryptic Google error) |
+| 🐛 **OpenCode config** | `saveOpenCodeConfig()` now correctly writes TOML to `XDG_CONFIG_HOME` |
+| 🐛 **Pinned model override** | `body.model` correctly set to `pinnedModel` on context-cache protection |
+| 🐛 **Codex/Claude loop** | `tool_result` blocks now converted to text to stop infinite loops |
+| 🐛 **Login redirect** | Login no longer freezes after skipping password setup |
+| 🐛 **Windows paths** | MSYS2/Git-Bash paths (`/c/...`) normalized to `C:\...` automatically |
+
+---
+
+## 🖼️ Main Dashboard
+
+
-📡 Semua agen terhubung melalui ` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**Stop wasting money and hitting limits:**
-### 🆕 What's New in v3.0.0
+- Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**OmniRoute solves this:**
+
+- ✅ **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
+- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool
---
-[](https://www.npmjs.com/package/omniroute)
-[](https://hub.docker.com/r/diegosouzapw/omniroute)
-[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
-[](https://omniroute.online)
-[](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
+## 📧 Support
-[🌐 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)
+> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.
-🌐 **Available in:** 🇺🇸 [English](../../README.md) | 🇧🇷 [Português (Brasil)](../pt-BR/README.md) | 🇪🇸 [Español](../es/README.md) | 🇫🇷 [Français](../fr/README.md) | 🇮🇹 [Italiano](../it/README.md) | 🇷🇺 [Русский](../ru/README.md) | 🇨🇳 [中文 (简体)](../zh-CN/README.md) | 🇩🇪 [Deutsch](../de/README.md) | 🇮🇳 [हिन्दी](../in/README.md) | 🇹🇭 [ไทย](../th/README.md) | 🇺🇦 [Українська](../uk-UA/README.md) | 🇸🇦 [العربية](../ar/README.md) | 🇯🇵 [日本語](../ja/README.md) | 🇻🇳 [Tiếng Việt](../vi/README.md) | 🇧🇬 [Български](../bg/README.md) | 🇩🇰 [Dansk](../da/README.md) | 🇫🇮 [Suomi](../fi/README.md) | 🇮🇱 [עברית](../he/README.md) | 🇭🇺 [Magyar](../hu/README.md) | 🇮🇩 [Bahasa Indonesia](../id/README.md) | 🇰🇷 [한국어](../ko/README.md) | 🇲🇾 [Bahasa Melayu](../ms/README.md) | 🇳🇱 [Nederlands](../nl/README.md) | 🇳🇴 [Norsk](../no/README.md) | 🇵🇹 [Português (Portugal)](../pt/README.md) | 🇷🇴 [Română](../ro/README.md) | 🇵🇱 [Polski](../pl/README.md) | 🇸🇰 [Slovenčina](../sk/README.md) | 🇸🇪 [Svenska](../sv/README.md) | 🇵🇭 [Filipino](../phi/README.md)
-
-
-
----
-
-## 🖼️
-
-
-
- # 🚀 OmniRoute — Gerbang AI Gratis
+# 🚀 OmniRoute — The Free AI Gateway (Bahasa Indonesia)
-### Jangan pernah berhenti membuat kode. Perutean cerdas ke **model AI GRATIS & berbiaya rendah** dengan fallback otomatis.
-
-_Proksi API universal Anda — satu titik akhir, 36+ penyedia, tanpa waktu henti._
-
-**Penyelesaian Obrolan • Penyematan • Pembuatan Gambar • Audio • Pemeringkatan Ulang • 100% TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Penyedia AI gratis untuk agen coding favorit Anda
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Hubungkan alat IDE atau CLI apa pun yang didukung AI melalui OmniRoute — gerbang API gratis untuk pengkodean tanpa batas._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+
+
+[](https://www.npmjs.com/package/omniroute)
+[](https://www.npmjs.com/package/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
+[](https://omniroute.online)
+[](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)
+
+
+
+🌐 **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)
+
+---
+
+## 🆕 What's New in v3.0.0
+
+> **Upgrading from v2.9.5?** — See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes.
+
+| Area | Change |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection remediation |
+| ✅ **Route Validation** | All 176 API routes now validated with Zod schemas + `validateBody()` — CI `check:route-validation:t06` passes |
+| 🐛 **omniModel Tag Leak** | Internal `
+
+
+
+---
+
+## 📸 Dashboard Preview
+
+
+
+
+
+---
+
+### 🤖 Free AI Provider for your favorite coding agents
+
+_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._
Click to see dashboard screenshots
+ +| Page | Screenshot | +| -------------- | ------------------------------------------------- | +| **Providers** |  | +| **Combos** |  | +| **Analytics** |  | +| **Health** |  | +| **Translator** |  | +| **Settings** |  | +| **CLI Tools** |  | +| **Usage Logs** |  | +| **Endpoints** |  | + +|
-
+
OpenClaw @@ -92,113 +162,52 @@ _Hubungkan alat IDE atau CLI apa pun yang didukung AI melalui OmniRoute — gerb |
http://localhost:20128/v1 atau http://cloud.omniroute.online/v1 — satu konfigurasi, model tak terbatas, dan kuota
+📡 All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 — one config, unlimited models and quota
---
-### 🆕 What's New in v3.0.0
+## 🤔 Why OmniRoute?
-| Area | Change |
-| ------------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal ` Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `
-
-
-
----
-
-## 📸
-
-
-
-
-
----
-
-## 🤔 Mengapa OmniRoute?
-
-**Berhenti membuang-buang uang dan mencapai batas:**
-
-- ...
- -| # | # | -| ----- | ---------------------------------------- | -| **1** |  | -| **2** |  | -| **3** |  | -| **4** |  | -| **5** |  | -| **6** |  | -| **7** |  | -| **8** |  | -| **9** |  | - - Kuota berlangganan habis tanpa terpakai setiap bulannya
-- Batas kecepatan menghentikan Anda di tengah coding
-- API mahal ($20-50/bulan per penyedia)
-- Peralihan antar penyedia secara manual
-
-**OmniRoute memecahkan masalah ini:**
-
-- ✅ **Maksimalkan langganan** - Lacak kuota, gunakan setiap bit sebelum menyetel ulang
-- ✅ **Pengembalian otomatis** - Berlangganan → Kunci API → Murah → Gratis, tanpa downtime
-- ✅ **Multi-akun** - Round-robin antar akun per penyedia
-- ✅ **Universal** - Bekerja dengan Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, alat CLI apa pun
-
----
-
-## 📧 Dukungan
-
-> 💬 **Bergabunglah dengan komunitas kami!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Dapatkan bantuan, berbagi kiat, dan dapatkan informasi terbaru.
-
-- **Situs Web**: [omniroute.online](https://omniroute.online)
+- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Masalah**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Proyek Asli**: [9router by decolua](https://github.com/decolua/9router)
+- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 Cara Kerjanya
+## 🔄 How It Works
```
┌─────────────┐
@@ -227,452 +236,453 @@ Result: Never stop coding, minimal cost
---
-## 🎯 Apa yang Dipecahkan OmniRoute — 30 Masalah Nyata & Kasus Penggunaan
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **Setiap pengembang yang menggunakan alat AI menghadapi masalah ini setiap hari.** OmniRoute dibuat untuk menyelesaikan semuanya — mulai dari pembengkakan biaya hingga pemblokiran regional, mulai dari aliran OAuth yang rusak hingga operasi protokol dan kemampuan observasi perusahaan.
+> **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.
-
💸 1. "Saya membayar langganan yang mahal tetapi masih terganggu oleh batasan"
+💸 1. "I pay for an expensive subscription but still get interrupted by limits"
-Pengembang membayar $20–200/bulan untuk Claude Pro, Codex Pro, atau GitHub Copilot. Bahkan saat membayar, kuota memiliki batas tertinggi — penggunaan 5 jam, batas mingguan, atau batas tarif per menit. Di tengah sesi pengkodean, penyedia berhenti merespons dan pengembang kehilangan aliran dan produktivitas. +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. -**Bagaimana OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- **Smart 4-Tier Fallback** — Jika kuota berlangganan habis, otomatis dialihkan ke Kunci API → Murah → Gratis tanpa intervensi manual -- **Pelacakan Kuota Real-Time** — Menampilkan konsumsi token secara real-time dengan hitungan mundur reset (5 jam, harian, mingguan) -- **Dukungan Multi-Akun** — Beberapa akun per penyedia dengan sistem round-robin otomatis — jika satu akun habis, beralih ke akun berikutnya -- **Kombo Khusus** — Rantai cadangan yang dapat disesuaikan dengan 6 strategi penyeimbangan (isi terlebih dahulu, round-robin, P2C, acak, paling jarang digunakan, hemat biaya) -- **Codex Business Quotas** — Pemantauan kuota ruang kerja Bisnis/Tim langsung di dasbor +- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention +- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly) +- **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 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
-` dari model seperti DeepSeek R1 ke dalam `reasoning_content` standar
-- **Output Terstruktur untuk Gemini** — `json_schema` → `responseMimeType`/`responseSchema` konversi otomatis
-- **`stream` defaultnya adalah `false`** — Sesuai dengan spesifikasi OpenAI, menghindari SSE yang tidak terduga di SDK Python/Rust/Go
+- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 67+ 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
🔌 2. "Saya perlu menggunakan beberapa penyedia tetapi masing-masing memiliki API yang berbeda"
+🔌 2. "I need to use multiple providers but each has a different API"
-OpenAI menggunakan satu format, Claude (Anthropic) menggunakan format lain, Gemini menggunakan format lain. Jika pengembang ingin menguji model dari penyedia yang berbeda atau melakukan fallback di antara penyedia tersebut, mereka perlu mengonfigurasi ulang SDK, mengubah titik akhir, menangani format yang tidak kompatibel. Penyedia khusus (FriendLI, NIM) memiliki titik akhir model non-standar. +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. -**Bagaimana OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- **Titik Akhir Terpadu** — Satu `http://localhost:20128/v1` berfungsi sebagai proxy untuk 36+ penyedia -- **Terjemahan Format** — Otomatis dan transparan: OpenAI ↔ Claude ↔ Gemini ↔ Responses API -- **Sanitasi Respons** — Menghapus kolom non-standar (`x_groq`, `usage_breakdown`, `service_tier`) yang merusak OpenAI SDK v1.83+ -- **Normalisasi Peran** — Mengonversi `developer` → `system` untuk penyedia non-OpenAI; `system` → `user` untuk GLM/ERNIE -- **Think Tag Extraction** — Mengekstrak blok `
-
🌐 3. "Penyedia AI saya memblokir wilayah/negara saya"
+🌐 3. "My AI provider blocks my region/country"
-Penyedia seperti OpenAI/Codex memblokir akses dari wilayah geografis tertentu. Pengguna mendapatkan kesalahan seperti `unsupported_country_region_territory` selama koneksi OAuth dan API. Hal ini sangat membuat frustasi bagi pengembang dari negara-negara berkembang. +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. -**Bagaimana OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- **Konfigurasi Proksi 3 Tingkat** — Proksi yang dapat dikonfigurasi pada 3 tingkat: global (semua lalu lintas), per penyedia (hanya satu penyedia), dan per koneksi/kunci -- **Lencana Proksi Berkode Warna** — Indikator visual: 🟢 proksi global, 🟡 proksi penyedia, 🔵 proksi koneksi, selalu menampilkan IP -- **OAuth Token Exchange Through Proxy** — Aliran OAuth juga melewati proxy, menyelesaikan `unsupported_country_region_territory` -- **Tes Koneksi melalui Proxy** — Tes koneksi menggunakan proxy yang dikonfigurasi (tidak ada lagi bypass langsung) -- **Dukungan SOCKS5** — Dukungan proksi SOCKS5 penuh untuk perutean keluar -- **TLS Fingerprint Spoofing** — Sidik jari TLS mirip browser melalui `wreq-js` untuk melewati deteksi bot +- **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
-` prefix
-- **Kombo Khusus Gratis** — Rantai `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/bulan tanpa downtime
-- **Kredit Gratis NVIDIA NIM** — 1000 kredit gratis terintegrasi
-- **Strategi Pengoptimalan Biaya** — Strategi perutean yang secara otomatis memilih penyedia termurah yang tersedia
+- **Free-Only Combos** — Chain `gc/gemini-3-flash → 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
🆓 4. "Saya ingin menggunakan AI untuk coding tetapi saya tidak punya uang"
+🆓 4. "I want to use AI for coding but I have no money"
-Tidak semua orang mampu membayar $20–200/bulan untuk berlangganan AI. Pelajar, pengembang dari negara-negara berkembang, penghobi, dan pekerja lepas memerlukan akses ke model berkualitas tanpa biaya. +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. -**Bagaimana OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- **Terintegrasi Penyedia Tingkat Gratis** — Dukungan asli untuk 100% penyedia gratis: iFlow (8 model tak terbatas), Qwen (3 model tak terbatas), Kiro (Claude gratis), Gemini CLI (gratis 180K/bulan) +- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free) - **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/
-
🔒 5. "Saya perlu melindungi gateway AI saya dari akses tidak sah"
+🔒 5. "I need to protect my AI gateway from unauthorized access"
-Saat mengekspos gateway AI ke jaringan (LAN, VPS, Docker), siapa pun yang memiliki alamat tersebut dapat menggunakan token/kuota pengembang. Tanpa perlindungan, API rentan terhadap penyalahgunaan, injeksi cepat, dan penyalahgunaan. +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. -**Bagaimana OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- **Manajemen Kunci API** — Pembuatan, rotasi, dan pelingkupan per penyedia dengan halaman `/dashboard/api-manager` khusus -- **Izin Tingkat Model** — Membatasi kunci API untuk model tertentu (`openai/*`, pola karakter pengganti), dengan tombol Izinkan Semua/Batasi -- **API Endpoint Protection** — Memerlukan kunci untuk `/v1/models` dan memblokir penyedia tertentu dari daftar -- **Auth Guard + Perlindungan CSRF** — Semua rute dasbor dilindungi dengan middleware `withAuth` + token CSRF -- **Pembatas Kecepatan** — Pembatasan kecepatan per-IP dengan jendela yang dapat dikonfigurasi -- **Pemfilteran IP** — Daftar yang diizinkan/daftar blokir untuk kontrol akses -- **Prompt Injection Guard** — Sanitasi terhadap pola prompt berbahaya -- **Enkripsi AES-256-GCM** — Kredensial dienkripsi saat disimpan +- **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. "Penyedia saya down dan saya kehilangan alur pengkodean"
+🛑 6. "My provider went down and I lost my coding flow"
-Penyedia AI bisa menjadi tidak stabil, menampilkan kesalahan 5xx, atau mencapai batas kecepatan sementara. Jika pengembang bergantung pada satu penyedia, mereka akan terganggu. Tanpa pemutus sirkuit, percobaan ulang yang berulang-ulang dapat membuat aplikasi crash. +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. -**Bagaimana OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- **Pemutus Sirkuit per penyedia** — Buka/tutup otomatis dengan ambang batas dan cooldown yang dapat dikonfigurasi (Tertutup/Terbuka/Setengah Terbuka) -- **Kemunduran Eksponensial** — Penundaan percobaan ulang yang progresif -- **Kawanan Anti-Guntur** — Perlindungan mutex + semaphore terhadap badai percobaan ulang secara bersamaan -- **Combo Fallback Chains** — Jika penyedia utama gagal, otomatis gagal dalam rantai tanpa intervensi -- **Combo Circuit Breaker** — Menonaktifkan secara otomatis penyedia yang gagal dalam rantai kombo - | 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format | -- **Dasbor Kesehatan** — Pemantauan waktu aktif, status pemutus sirkuit, penguncian, statistik cache, latensi p50/p95/p99 +- **Circuit Breaker per-model** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks +- **Exponential Backoff** — Progressive retry delays +- **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 +- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain +- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
-
🔧 7. "Mengonfigurasi setiap alat AI membosankan dan berulang-ulang"
+🔧 7. "Configuring each AI tool is tedious and repetitive"
-Pengembang menggunakan Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Setiap alat memerlukan konfigurasi yang berbeda (titik akhir API, kunci, model). Mengonfigurasi ulang saat berpindah penyedia atau model hanya membuang-buang waktu. +Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time. -**Bagaimana OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- **Dasbor Alat CLI** — Halaman khusus dengan pengaturan sekali klik untuk Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline -- **GitHub Copilot Config Generator** — Menghasilkan `chatLanguageModels.json` untuk VS Code dengan pemilihan model massal -- **Onboarding Wizard** — Panduan penyiapan 4 langkah untuk pengguna pertama kali -- **Satu titik akhir, semua model** — Konfigurasikan `http://localhost:20128/v1` satu kali, akses 36+ penyedia +- **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 67+ providers
-
🔑 8. "Mengelola token OAuth dari banyak penyedia adalah neraka"
+🔑 8. "Managing OAuth tokens from multiple providers is hell"
-Claude Code, Codex, Gemini CLI, Copilot — semuanya menggunakan OAuth 2.0 dengan token yang kedaluwarsa. Pengembang perlu melakukan autentikasi ulang terus-menerus, menangani `client_secret is missing`, `redirect_uri_mismatch`, dan kegagalan pada server jarak jauh. OAuth pada LAN/VPS sangat bermasalah. +Claude Code, Codex, Gemini CLI, 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. -**Bagaimana OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- **Penyegaran Token Otomatis** — Penyegaran token OAuth di latar belakang sebelum masa berlakunya habis -- **OAuth 2.0 (PKCE) Bawaan** — Aliran otomatis untuk Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow -- **OAuth Multi-Akun** — Beberapa akun per penyedia melalui ekstraksi token JWT/ID -- **OAuth LAN/Remote Fix** — Deteksi IP pribadi untuk `redirect_uri` + mode URL manual untuk server jarak jauh -- **OAuth Dibalik Nginx** — Menggunakan `window.location.origin` untuk kompatibilitas proxy terbalik -- **Panduan OAuth Jarak Jauh** — Panduan langkah demi langkah untuk kredensial Google Cloud di VPS/Docker +- **Auto Token Refresh** — OAuth tokens refresh in background before expiration +- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow +- **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. "Saya tidak tahu berapa banyak yang saya belanjakan atau di mana"
+📊 9. "I don't know how much I'm spending or where"
-Pengembang menggunakan beberapa penyedia berbayar tetapi tidak memiliki pandangan terpadu mengenai pembelanjaan. Setiap penyedia memiliki dasbor penagihannya sendiri, namun tidak ada tampilan gabungan. Biaya tak terduga bisa menumpuk. +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. -**Bagaimana OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- **Dasbor Analisis Biaya** — Pelacakan biaya per token dan pengelolaan anggaran per penyedia -- **Batas Anggaran per Tingkat** — Batas pembelanjaan per tingkat yang memicu penggantian otomatis -- **Konfigurasi Harga Per Model** — Harga per model yang dapat dikonfigurasi -- **Statistik Penggunaan Per Kunci API** — Jumlah permintaan dan stempel waktu terakhir digunakan per kunci -- **Dasbor Analytics** — Kartu statistik, diagram penggunaan model, tabel penyedia dengan tingkat keberhasilan dan latensi +- **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. "Saya tidak dapat mendiagnosis kesalahan dan masalah dalam panggilan AI"
+🐛 10. "I can't diagnose errors and problems in AI calls"
-Saat panggilan gagal, pengembang tidak mengetahui apakah itu batas kecepatan, token kedaluwarsa, format salah, atau kesalahan penyedia. Log terfragmentasi di terminal yang berbeda. Tanpa observabilitas, debugging adalah trial-and-error. +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. -**Bagaimana OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- **Dasbor Log Terpadu** — 4 tab: Log Permintaan, Log Proksi, Log Audit, Konsol -- **Penampil Log Konsol** — Penampil gaya terminal real-time dengan level kode warna, gulir otomatis, pencarian, filter -- **Log Proxy SQLite** — Log persisten yang bertahan saat server dimulai ulang -- **Translator Playground** — 4 mode debugging: Playground (terjemahan format), Chat Tester (pulang pergi), Test Bench (batch), Live Monitor (real-time) -- **Telemetri Permintaan** — latensi p50/p95/p99 + penelusuran X-Request-Id -- **Logging Berbasis File dengan Rotasi** — Pencegat konsol menangkap semuanya ke log JSON dengan rotasi berbasis ukuran +- **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 Proxy Logs** — Persistent logs that survive server restarts +- **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 Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation +- **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. "Menyebarkan dan memelihara gateway itu rumit"
+🏗️ 11. "Deploying and maintaining the gateway is complex"
-Menginstal, mengonfigurasi, dan memelihara proksi AI di berbagai lingkungan (lokal, VPS, Docker, cloud) membutuhkan banyak tenaga. Masalah seperti jalur hardcode, `EACCES` pada direktori, konflik port, dan pembangunan lintas platform menambah gesekan. +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. -**Bagaimana OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- **instal global npm** — `npm install -g omniroute && omniroute` — selesai -- **Docker Multi-Platform** — asli AMD64 + ARM64 (Apple Silicon, AWS Graviton, Raspberry Pi) -- **Docker Compose Profiles** — `base` (tanpa alat CLI) dan `cli` (dengan Claude Code, Codex, OpenClaw) -- **Aplikasi Desktop Electron** — Aplikasi asli untuk Windows/macOS/Linux dengan baki sistem, mulai otomatis, mode offline -- **Mode Port Terpisah** — API dan Dasbor pada port terpisah untuk skenario tingkat lanjut (proksi terbalik, jaringan kontainer) -- **Cloud Sync** — Konfigurasi sinkronisasi antar perangkat melalui Cloudflare Workers -- **DB Backups** — Pencadangan otomatis, pemulihan, ekspor dan impor semua pengaturan +- **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
-
🌍 12. "Antarmuka hanya berbahasa Inggris dan tim saya tidak bisa berbahasa Inggris"
+🌍 12. "The interface is English-only and my team doesn't speak English"
-Tim di negara-negara yang tidak berbahasa Inggris, khususnya di Amerika Latin, Asia, dan Eropa, kesulitan dengan antarmuka yang hanya berbahasa Inggris. Hambatan bahasa mengurangi adopsi dan meningkatkan kesalahan konfigurasi. +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. -**Bagaimana OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- **Dasbor i18n — 30 Bahasa** — 500+ tombol diterjemahkan termasuk Arab, Bulgaria, Denmark, Jerman, Spanyol, Finlandia, Prancis, Ibrani, Hindi, Hungaria, Indonesia, Italia, Jepang, Korea, Melayu, Belanda, Norwegia, Polandia, Portugis (PT/BR), Rumania, Rusia, Slovakia, Swedia, Thailand, Ukraina, Vietnam, China, Filipina, Inggris -- **Dukungan RTL** — Dukungan kanan ke kiri untuk bahasa Arab dan Ibrani -- **README Multi-Bahasa** — 30 terjemahan dokumentasi lengkap -- **Pemilih Bahasa** — Ikon bola dunia di header untuk peralihan waktu nyata +- **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. "Saya memerlukan lebih dari sekadar obrolan — saya memerlukan penyematan, gambar, audio"
+🔄 13. "I need more than chat — I need embeddings, images, audio"
-AI bukan hanya penyelesaian obrolan. Pengembang perlu membuat gambar, mentranskripsikan audio, membuat penyematan untuk RAG, mengubah peringkat dokumen, dan memoderasi konten. Setiap API memiliki titik akhir dan format yang berbeda. +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. -**Bagaimana OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- **Sematan** — `/v1/embeddings` dengan 6 penyedia dan 9+ model -- **Image Generation** — `/v1/images/generations` dengan 10 penyedia dan 20+ model (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI) -- **Teks-ke-Video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) dan SD WebUI -- **Teks-ke-Musik** — `/v1/music/generations` — ComfyUI (Audio Terbuka Stabil, MusicGen) -- **Transkripsi Audio** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3 -- **Text-to-Speech** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, Inworld, Cartesia, PlayHT, + penyedia yang ada -- **Moderasi** — `/v1/moderations` — Pemeriksaan keamanan konten -- **Pemeringkatan ulang** — `/v1/rerank` — Pemeringkatan ulang relevansi dokumen -- **Respon API** — Dukungan penuh `/v1/responses` untuk Codex +- **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. "Saya tidak punya cara untuk menguji dan membandingkan kualitas antar model"
+🧪 14. "I have no way to test and compare quality across models"
-Pengembang ingin mengetahui model mana yang terbaik untuk kasus penggunaan mereka — kode, terjemahan, penalaran — tetapi membandingkan secara manual itu lambat. Tidak ada alat evaluasi terintegrasi. +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. -**Bagaimana OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- **Evaluasi LLM** — Pengujian set emas dengan 10 kasus yang dimuat sebelumnya yang mencakup salam, matematika, geografi, pembuatan kode, kepatuhan JSON, terjemahan, penurunan harga, penolakan keamanan -- **4 Strategi Pertandingan** — `exact`, `contains`, `regex`, `custom` (fungsi JS) -- **Bangku Tes Taman Bermain Penerjemah** — Pengujian batch dengan banyak masukan dan keluaran yang diharapkan, perbandingan lintas penyedia -- **Penguji Obrolan** — Perjalanan bolak-balik penuh dengan rendering respons visual -- **Monitor Langsung** — Aliran real-time dari semua permintaan yang mengalir melalui proxy +- **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. "Saya perlu melakukan penskalaan tanpa kehilangan performa"
+📈 15. "I need to scale without losing performance"
-Seiring bertambahnya volume permintaan, tanpa menyimpan pertanyaan yang sama akan menghasilkan biaya duplikat. Tanpa idempotensi, permintaan duplikat akan membuang-buang pemrosesan. Batasan tarif per penyedia harus dipatuhi. +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. -**Bagaimana OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- **Cache Semantik** — Cache dua tingkat (tanda tangan + semantik) mengurangi biaya dan latensi -- **Request Idempoency** — Jendela deduplikasi 5 detik untuk permintaan yang identik -- **Deteksi Batas Tarif** — RPM per penyedia, selisih minimum, dan pelacakan serentak maks -- **Batas Nilai yang Dapat Diedit** — Default yang dapat dikonfigurasi di Pengaturan → Ketahanan dengan persistensi -- **Cache Validasi Kunci API** — cache 3 tingkat untuk kinerja produksi -- **Dasbor Kesehatan dengan Telemetri** — latensi p50/p95/p99, statistik cache, waktu aktif +- **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 +- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence +- **API Key Validation Cache** — 3-tier cache for production performance +- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
-
🤖 16. "Saya ingin mengontrol perilaku model secara global"
+🤖 16. "I want to control model behavior globally"
-Pengembang yang menginginkan semua respons dalam bahasa tertentu, dengan nada tertentu, atau ingin membatasi token penalaran. Mengonfigurasi ini di setiap alat/permintaan tidak praktis. +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. -**Bagaimana OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- **Injeksi Perintah Sistem** — Perintah global diterapkan ke semua permintaan -- **Validasi Anggaran Berpikir** — Kontrol alokasi token penalaran per permintaan (passthrough, otomatis, kustom, adaptif) -- **6 Strategi Perutean** — Strategi global yang menentukan cara permintaan didistribusikan -- **Wildcard Router** — Pola `provider/*` dirutekan secara dinamis ke penyedia mana pun -- **Combo Aktifkan/Nonaktifkan Toggle** — Beralih kombo langsung dari dasbor -- **Toggle Penyedia** — Mengaktifkan/menonaktifkan semua koneksi untuk penyedia dengan satu klik -- **Penyedia yang Diblokir** — Kecualikan penyedia tertentu dari daftar `/v1/models` +- **System Prompt Injection** — Global prompt applied to all requests +- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive) +- **6 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 +- **Provider Toggle** — Enable/disable all connections for a provider with one click +- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
-
🧰 17. "Saya membutuhkan alat MCP sebagai kemampuan produk kelas satu"
+🧰 17. "I need MCP tools as first-class product capabilities"
-Banyak gateway AI yang mengekspos MCP hanya sebagai detail implementasi yang tersembunyi. Tim memerlukan lapisan operasi yang terlihat dan dapat dikelola. +Many AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer. -**Bagaimana OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- MCP muncul di navigasi dasbor dan tab protokol titik akhir -- Halaman manajemen MCP khusus dengan proses, alat, cakupan, dan audit -- Mulai cepat bawaan untuk `omniroute --mcp` dan orientasi klien +- 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. "Saya memerlukan orkestrasi A2A dengan jalur tugas sinkronisasi + streaming"
+🧠 18. "I need A2A orchestration with sync + stream task paths"
-Alur kerja agen memerlukan balasan langsung dan eksekusi streaming jangka panjang dengan kontrol siklus hidup. +Agent workflows need both direct replies and long-running streamed execution with lifecycle control. -**Bagaimana OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- Titik akhir A2A JSON-RPC (`POST /a2a`) dengan `message/send` dan `message/stream` -- Streaming SSE dengan propagasi status terminal -- API siklus hidup tugas untuk `tasks/get` dan `tasks/cancel` +- 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. "Saya membutuhkan kesehatan proses MCP yang nyata, bukan status yang dapat ditebak"
+🛰️ 19. "I need real MCP process health, not guessed status"
-Tim operasional perlu mengetahui apakah MCP benar-benar aktif, bukan hanya apakah API dapat dijangkau. +Operational teams need to know if MCP is actually alive, not just whether an API is reachable. -**Bagaimana OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- File detak jantung runtime dengan PID, stempel waktu, transportasi, jumlah alat, dan mode cakupan -- API status MCP menggabungkan detak jantung + aktivitas terkini -- Kartu status UI untuk kesegaran proses/waktu aktif/detak jantung +- 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. "Saya memerlukan eksekusi alat MCP yang dapat diaudit"
+📋 20. "I need auditable MCP tool execution"
-Saat alat mengubah konfigurasi atau memicu tindakan operasi, tim memerlukan kemampuan penelusuran forensik. +When tools mutate config or trigger ops actions, teams need forensic traceability. -**Bagaimana OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- Pencatatan audit yang didukung SQLite untuk panggilan alat MCP -- Filter berdasarkan alat, keberhasilan/kegagalan, kunci API, dan penomoran halaman -- Tabel audit dasbor + titik akhir statistik untuk otomatisasi +- 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. "Saya memerlukan izin MCP terbatas per integrasi"
+🔐 21. "I need scoped MCP permissions per integration"
-Klien yang berbeda harus memiliki akses dengan hak istimewa paling rendah ke kategori alat. +Different clients should have least-privilege access to tool categories. -**Bagaimana OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- 9 cakupan MCP granular untuk akses alat terkontrol -- Penegakan cakupan dan visibilitas di UI manajemen MCP -- Postur default yang aman untuk perkakas operasional +- 9 granular MCP scopes for controlled tool access +- Scope enforcement and visibility in MCP management UI +- Safe default posture for operational tooling
-
⚙️ 22. "Saya memerlukan kontrol operasional tanpa memindahkan"
+⚙️ 22. "I need operational controls without redeploying"
-Tim memerlukan perubahan runtime yang cepat selama insiden atau peristiwa biaya. +Teams need quick runtime changes during incidents or cost events. -**Bagaimana OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- Beralih aktivasi kombo langsung dari dasbor MCP -- Menerapkan profil ketahanan dari paket kebijakan yang telah ditentukan sebelumnya -- Reset status pemutus sirkuit dari panel operasi yang sama +- Switch combo activation directly from MCP dashboard +- Apply resilience profiles from pre-defined policy packs +- Reset circuit breaker state from the same operations panel
-
🔄 23. "Saya memerlukan visibilitas dan pembatalan siklus hidup tugas A2A langsung"
+🔄 23. "I need live A2A task lifecycle visibility and cancellation"
-Tanpa visibilitas siklus hidup, insiden tugas menjadi sulit untuk diprioritaskan. +Without lifecycle visibility, task incidents become hard to triage. -**Bagaimana OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- Daftar tugas/pemfilteran berdasarkan status/keterampilan dengan penomoran halaman -- Telusuri metadata tugas, peristiwa, dan artefak -- Titik akhir pembatalan tugas dan tindakan UI dengan konfirmasi +- 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. "Saya memerlukan metrik streaming aktif untuk memuat A2A"
+🌊 24. "I need active stream metrics for A2A load"
-Alur kerja streaming memerlukan wawasan operasional tentang konkurensi dan koneksi langsung. +Streaming workflows require operational insight into concurrency and live connections. -**Bagaimana OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- Penghitung aliran aktif terintegrasi ke dalam status A2A -- Stempel waktu tugas terakhir dan jumlah per negara bagian -- Kartu dasbor A2A untuk pemantauan operasi waktu nyata +- Active stream counters integrated into A2A status +- Last task timestamp and per-state counts +- A2A dashboard cards for real-time ops monitoring
-
🪪 25. "Saya memerlukan penemuan agen standar untuk klien"
+🪪 25. "I need standard agent discovery for clients"
-Klien dan orkestra eksternal memerlukan metadata yang dapat dibaca mesin untuk orientasi. +External clients and orchestrators need machine-readable metadata for onboarding. -**Bagaimana OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- Kartu Agen terekspos di `/.well-known/agent.json` -- Kemampuan dan keterampilan yang ditunjukkan dalam manajemen UI -- API status A2A mencakup metadata penemuan untuk otomatisasi +- Agent Card exposed at `/.well-known/agent.json` +- Capabilities and skills shown in management UI +- A2A status API includes discovery metadata for automation
-
🧭 26. "Saya memerlukan kemampuan protokol untuk ditemukan di UX produk"
+🧭 26. "I need protocol discoverability in the product UX"
-Jika pengguna tidak dapat menemukan permukaan protokol, kualitas adopsi dan dukungan akan menurun. +If users cannot discover protocol surfaces, adoption and support quality drop. -**Bagaimana OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- Entri sidebar untuk MCP dan A2A -- Tab Protokol halaman titik akhir dengan mulai cepat dan status -- Tautan dari ikhtisar ke dasbor manajemen khusus +- 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. "Saya memerlukan validasi protokol end-to-end dengan klien nyata"
+🧪 27. "I need end-to-end protocol validation with real clients"
-Tes tiruan tidak cukup untuk memvalidasi kompatibilitas protokol sebelum rilis. +Mock tests are not enough to validate protocol compatibility before release. -**Bagaimana OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- Suite E2E yang mem-boot aplikasi dan menggunakan transportasi klien MCP SDK yang sebenarnya -- Klien A2A menguji penemuan, pengiriman, streaming, dapatkan, dan pembatalan aliran -- Periksa silang pernyataan terhadap audit MCP dan API tugas A2A +- 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. "Saya memerlukan kemampuan pengamatan terpadu di semua antarmuka"
+📡 28. "I need unified observability across all interfaces"
-Memisahkan observabilitas berdasarkan protokol menciptakan titik buta dan MTTR yang lebih panjang. +Splitting observability by protocol creates blind spots and longer MTTR. -**Bagaimana OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- Dasbor/log/analitik terpadu dalam satu produk -- Kesehatan + audit + permintaan telemetri di seluruh lapisan OpenAI, MCP, dan A2A -- API Operasional untuk status dan otomatisasi +- Unified dashboards/logs/analytics in one product +- Health + audit + request telemetry across OpenAI, MCP, and A2A layers +- Operational APIs for status and automation
-
💼 29. "Saya memerlukan satu runtime untuk proxy + alat + orkestrasi agen"
+💼 29. "I need one runtime for proxy + tools + agent orchestration"
-Menjalankan banyak layanan terpisah akan meningkatkan biaya operasional dan mode kegagalan. +Running many separate services increases operational cost and failure modes. -**Bagaimana OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- Proksi yang kompatibel dengan OpenAI, server MCP, dan server A2A dalam satu tumpukan -- Otentikasi bersama, ketahanan, penyimpanan data, dan kemampuan observasi -- Model kebijakan yang konsisten di seluruh platform interaksi +- 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
-
-### Contoh Playbook (Kasus Penggunaan Terintegrasi)
+### Example Playbooks (Integrated Use Cases)
-**Playbook A: Maksimalkan langganan berbayar + cadangan murah**
+**Playbook A: Maximize paid subscription + cheap backup**
```txt
Combo: "maximize-claude"
@@ -684,7 +694,7 @@ Monthly cost: $20 + small backup spend
Outcome: higher quality, near-zero interruption
```
-**Playbook B: Tumpukan coding tanpa biaya**
+**Playbook B: Zero-cost coding stack**
```txt
Combo: "free-forever"
@@ -696,7 +706,7 @@ Monthly cost: $0
Outcome: stable free coding workflow
```
-**Playbook C: Rantai fallback yang selalu aktif 24/7**
+**Playbook C: 24/7 always-on fallback chain**
```txt
Combo: "always-on"
@@ -709,65 +719,132 @@ Combo: "always-on"
Outcome: deep fallback depth for deadline-critical workloads
```
-**Playbook D: Operasi agen dengan MCP + A2A**
+**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/mcp and /dashboard/a2a
-4) Control incidents with resilience profile + task cancellation
+3) Observe via /dashboard/endpoint (MCP and A2A tabs)
+4) Toggle services via inline status controls
```
---
-## ⚡ Mulai Cepat
+## 🆓 Start Free — Zero Configuration Cost
-**1. Instal secara global:**
+> 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 **iFlow** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |
+| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |
+| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |
+| 5 | `/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).
+
+## Mulai Cepat
+
+### 1) Install and run
```bash
npm install -g omniroute
omniroute
```
-🎉 Dasbor terbuka di `http://localhost:20128`
+> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:
+>
+> ```bash
+> pnpm install -g omniroute
+> pnpm approve-builds -g # Select all packages → approve
+> omniroute
+> ```
-| Perintah | Deskripsi |
-| ----------------------- | --------------------------------- |
-| `omniroute` | Mulai server (port default 20128) |
-| `omniroute --port 3000` | Gunakan port khusus |
-| `omniroute --no-open` | Jangan buka otomatis browser |
-| `omniroute --help` | Tampilkan bantuan |
+Dashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.
-**2. Hubungkan penyedia GRATIS:**
+| 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 |
-Dasbor → Penyedia → Hubungkan **Kode Claude** atau **Antigravitasi** → Login OAuth → Selesai!
+Optional split-port mode:
-**3. Gunakan di alat CLI Anda:**
-
-```
-Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Settings:
- Endpoint: http://localhost:20128/v1
- API Key: [copy from dashboard]
- Model: if/kimi-k2-thinking
+```bash
+PORT=20128 DASHBOARD_PORT=20129 omniroute
+# API: http://localhost:20128/v1
+# Dashboard: http://localhost:20129
```
-**Selesai!** Mulai coding dengan model AI GRATIS.
+### 2) Connect providers and create your API key
-**Alternatif — dijalankan dari sumber:**
+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
+
+```txt
+Base URL: http://localhost:20128/v1
+API Key: [copy from Endpoint page]
+Model: if/kimi-k2-thinking (or any provider/model prefix)
+```
+
+Works with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.
+
+### 4) Enable and validate protocols (v2.0)
+
+**MCP (for tool-driven operations):**
+
+```bash
+omniroute --mcp
+```
+
+Then connect your MCP client over `stdio` and test tools like:
+
+- `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 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
+PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev
```
---
-## 🐳 buruh pelabuhan
+## 🐳 Docker
-OmniRoute tersedia sebagai image Docker publik di [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
+OmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
-**Lari cepat:**
+**Quick run:**
```bash
docker run -d \
@@ -778,7 +855,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Dengan file lingkungan:**
+**With environment file:**
```bash
# Copy and edit .env first
@@ -793,7 +870,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Menggunakan Docker Tulis:**
+**Using Docker Compose:**
```bash
# Base profile (no CLI tools)
@@ -803,257 +880,552 @@ docker compose --profile base up -d
docker compose --profile cli up -d
```
-| Gambar | Tandai | Ukuran | Deskripsi |
-| ------------------------ | -------- | ------- | -------------------- |
-| `diegosouzapw/omniroute` | `latest` | ~250 MB | Rilis stabil terbaru |
-| `diegosouzapw/omniroute` | `1.0.3` | ~250 MB | Versi saat ini |
+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.
+- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.
+- 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` | `1.0.3` | ~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
+### Mulai Cepat
+
```bash
-npm run electron:dev # Development mode
+# 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)
+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)
---
-## 💰 Sekilas tentang Harga
+## 💰 Pricing at a Glance
-| Tingkat | Penyedia | Biaya | Reset Kuota | Terbaik Untuk |
-| ------------------- | ----------------- | ------------------------- | ------------------------- | --------------------------- |
-| **💳 BERLANGGANAN** | Kode Claude (Pro) | $20/bln | 5 jam + mingguan | Sudah berlangganan |
-| | Kodeks (Plus/Pro) | $20-200/bln | 5 jam + mingguan | Pengguna OpenAI |
-| | CLI Gemini | **GRATIS** | 180K/bln + 1K/hari | Setiap orang! |
-| | Kopilot GitHub | $10-19/bln | Bulanan | Pengguna GitHub |
-| **🔑 KUNCI API** | NVIDIA NIM | **GRATIS** (1000 sks) | Satu kali | Pengujian tingkat gratis |
-| | Pencarian Dalam | Bayar per penggunaan | Tidak ada | Harga/kualitas terbaik |
-| | Bagus | Tingkat gratis + berbayar | Tarif terbatas | Inferensi ultra-cepat |
-| | xAI (Grok) | Bayar per penggunaan | Tidak ada | Model Grok |
-| | Mistral | Tingkat gratis + berbayar | Tarif terbatas | AI Eropa |
-| | BukaRouter | Bayar per penggunaan | Tidak ada | 100+ model |
-| **💰 MURAH** | GLM-4.7 | $0,6/1 juta | Setiap hari pukul 10 pagi | Cadangan anggaran |
-| | MiniMax M2.1 | $0,2/1 juta | 5 jam bergulir | Pilihan termurah |
-| | Kimi K2 | $9/bln tetap | 10 juta token/bln | Biaya yang dapat diprediksi |
-| **🆓 GRATIS** | iFlow | $0 | Tidak terbatas | 8 model gratis |
-| | Qwen | $0 | Tidak terbatas | 3 model gratis |
-| | Kiro | $0 | Tidak terbatas | Claude gratis |
+| 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 |
+| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |
+| | 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** | iFlow | **$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 |
-**💡 Kiat Pro:** Mulai dengan Gemini CLI (gratis 180 ribu/bulan) + kombo iFlow (gratis tanpa batas) = biaya $0!
+> 🆕 **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
+iFlow (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.
---
-## 💡 Fitur Utama
+---
-### 🧠 Perutean & Kecerdasan Inti
+## 🆓 Free Models — What You Actually Get
-| Fitur | Apa Fungsinya |
-| ------------------------------------ | ---------------------------------------------------------------------------------- |
-| 🎯 **Pengembalian 4 Tingkat Cerdas** | Rute otomatis: Berlangganan → Kunci API → Murah → Gratis |
-| 📊 **Pelacakan Kuota Waktu Nyata** | Jumlah token langsung + setel ulang hitungan mundur per penyedia |
-| 🔄 **Terjemahan Format** | OpenAI ↔ Claude ↔ Gemini ↔ Kursor ↔ Kiro mulus + sanitasi respons |
-| 👥 **Dukungan Multi-Akun** | Banyak akun per penyedia dengan pilihan cerdas |
-| 🔄 **Penyegaran Token Otomatis** | Token OAuth disegarkan secara otomatis dengan coba lagi |
-| 🎨 **Kombo Khusus** | 6 strategi: isi dulu, round-robin, p2c, acak, paling jarang digunakan, hemat biaya |
-| 🧩 **Model Khusus** | Tambahkan ID model apa pun ke penyedia mana pun |
-| 🌐 **Router Wildcard** | Rutekan pola `provider/*` ke penyedia mana pun secara dinamis |
-| 🧠 **Memikirkan Anggaran** | Mode passthrough, otomatis, kustom, dan adaptif untuk model penalaran |
-| 🔀 **Model Aliases** | Auto-forward deprecated model IDs to current replacements (built-in + custom) |
-| ⚡ **Background Degradation** | Auto-route background tasks (titles, summaries) to cheaper models |
-| 💬 **Injeksi Perintah Sistem** | Perintah sistem global diterapkan di semua permintaan |
-| 📄 **API Respons** | Dukungan penuh OpenAI Responses API (`/v1/responses`) untuk Codex |
+> 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.
-### 🎵 API Multi-Modal
+### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)
-| Fitur | Apa Fungsinya |
+| 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 |
+
+### 🟢 IFLOW MODELS (Free OAuth — No Credit Card)
+
+| 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 |
+
+### 🟡 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) |
+
+### 🟣 GEMINI CLI (Google OAuth)
+
+| Model | Prefix | Limit | Rate Limit |
+| ------------------------ | ------ | --------------------------- | ------------- |
+| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |
+| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |
+
+### ⚫ 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
+> iFlow (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 v2.0 is built as an operational platform, not just a relay proxy.
+
+### 🆕 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 Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |
+| 🤖 **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 (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) |
+| 🤝 **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** | 9 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 combo, apply resilience profiles, reset breakers from one control surface |
+
+### 🧠 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** | 6 balancing strategies + fallback chain control |
+| 🌐 **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) |
+| 💬 **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 |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 🖼️ **Pembuatan Gambar** | `/v1/images/generations` — 4 penyedia, 9+ model |
-| 📐 **Sematan** | `/v1/embeddings` — 6 penyedia, 9+ model |
-| 🎤 **Transkripsi Audio** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |
-| 🔊 **Teks-ke-Ucapan** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) |
-| 🛡️ **Moderasi** | `/v1/moderations` — Pemeriksaan keamanan konten |
-| 🔀 **Pemeringkatan Ulang** | `/v1/rerank` — Pemeringkatan ulang relevansi dokumen |
+| 🖼️ **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 |
-### 🛡️ Ketahanan & Keamanan
+### 🛡️ Resilience, Security & Governance
-| Fitur | Apa Fungsinya |
-| ------------------------------------ | ------------------------------------------------------------------------------------------ |
-| 🔌 **Pemutus Arus** | Buka/tutup otomatis per penyedia dengan ambang batas yang dapat dikonfigurasi |
-| 🛡️ **Kawanan Anti Guntur** | Batas kecepatan mutex + semaphore untuk penyedia kunci API |
-| 🧠 **Cache Semantik** | Cache dua tingkat (tanda tangan + semantik) mengurangi biaya & latensi |
-| ⚡ **Minta Idempotensi** | Jendela dedup 5 detik untuk permintaan duplikat |
-| 🔒 **Spoofing Sidik Jari TLS** | Lewati deteksi bot berbasis TLS melalui wreq-js |
-| 🌐 **Pemfilteran IP** | Daftar yang diizinkan/daftar blokir untuk kontrol akses API |
-| 📊 **Batas Tarif yang Dapat Diedit** | RPM yang dapat dikonfigurasi, celah minimum, dan maks secara bersamaan pada tingkat sistem |
-| 💾 **Rate Limit Persistence** | Learned limits survive restarts via SQLite with 60s debounce + 24h staleness |
-| 🔄 **Token Refresh Resilience** | Per-provider circuit breaker (5 fails→30min) + 30s timeout per attempt |
-| 🛡 **Perlindungan Titik Akhir API** | Gerbang autentikasi + pemblokiran penyedia untuk titik akhir `/models` |
-| 🔒 **Visibilitas Proksi** | Lencana berkode warna: 🟢 global, 🟡 penyedia, 🔵 per koneksi dengan tampilan IP |
-| 🌐 **Konfigurasi Proksi 3 Tingkat** | Konfigurasikan proxy di tingkat global, per penyedia, atau per koneksi |
+| Feature | What It Does |
+| ----------------------------------- | -------------------------------------------------------------------------------------- |
+| 🔌 **Circuit Breakers** | Per-model trip/recover with threshold controls |
+| 🎯 **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 |
+| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |
+| 🔑 **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 |
-### 📊 Observabilitas & Analisis
+### 📊 Observability & Analytics
-| Fitur | Apa Fungsinya |
-| -------------------------------- | ------------------------------------------------------------------------------- |
-| 📝 **Permintaan Pencatatan** | Mode debug dengan log permintaan/respons lengkap |
-| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |
-| 💾 **Log Proksi SQLite** | Log proksi persisten bertahan saat server dimulai ulang |
-| 📊 **Dasbor Analitik** | Didukung grafik ulang: kartu stat, bagan penggunaan model, tabel penyedia |
-| 📈 **Pelacakan Kemajuan** | Ikut serta dalam acara kemajuan SSE untuk streaming |
-| 🧪 **Evaluasi LLM** | Pengujian set emas dengan 4 strategi pertandingan |
-| 🔍 **Permintaan Telemetri** | agregasi latensi p50/p95/p99 + penelusuran X-Request-Id |
-| 📋 **Dasbor Log** | Halaman 4 tab terpadu: Log Permintaan, Log Proksi, Log Audit, Konsol |
-| 🖥️ **Penampil Log Konsol** | Penampil gaya terminal real-time dengan filter level, pencarian, gulir otomatis |
-| 📑 **Logging Berbasis File** | Pencegat konsol menangkap semua output ke file log JSON dengan rotasi |
-| 🏥 **Dasbor Kesehatan** | Waktu aktif sistem, status pemutus sirkuit, penguncian, statistik cache |
-| 💰 **Pelacakan Biaya** | Manajemen anggaran + konfigurasi harga per model |
+| Feature | What It Does |
+| -------------------------------- | ----------------------------------------------------- |
+| 📝 **Request + Proxy Logging** | Full request/response and proxy logging |
+| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |
+| 📋 **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 |
-### ☁️ Penerapan & Sinkronisasi
+### ☁️ Deployment & Platform
-| Fitur | Apa Fungsinya |
-| ---------------------------- | ---------------------------------------------------------------------------- |
-| 💾 **Sinkronisasi Cloud** | Sinkronkan konfigurasi antar perangkat melalui Cloudflare Workers |
-| 🌐 **Terapkan Di Mana Saja** | Localhost, VPS, Docker, Pekerja Cloudflare |
-| 🔑 **Manajemen Kunci API** | Menghasilkan, memutar, dan mencakup kunci API per penyedia |
-| 🧙 **Wizard Orientasi** | Penyiapan terpandu 4 langkah untuk pengguna pertama kali |
-| 🔧 **Dasbor Alat CLI** | Konfigurasikan sekali klik Claude, Codex, Cline, OpenClaw, Kilo, Antigravity |
-| 🔄 **Cadangan DB** | Pencadangan, pemulihan, ekspor & impor otomatis untuk semua pengaturan |
-| 🌐 **Internasionalisasi** | I18n lengkap dengan next-intl — Dukungan Inggris + Portugis (Brasil) |
-| 🌍 **Pemilih Bahasa** | Ikon bola dunia di header untuk peralihan bahasa secara real-time (🇮🇩/🇧🇷) |
-| 🧹 **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 |
-| 📂 **Direktori Data Khusus** | `DATA_DIR` env var untuk mengganti jalur penyimpanan `~/.omniroute` default |
+| Feature | What It Does |
+| ----------------------------- | --------------------------------------------------------- |
+| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |
+| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |
+| 💾 **Cloud Sync** | Configuration sync via cloud worker |
+| 🔄 **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 |
+
+### Feature Deep Dive
+
+#### Smart fallback with practical cost control
+
+```txt
+Combo: "my-coding-stack"
+ 1. cc/claude-opus-4-6
+ 2. nvidia/llama-3.3-70b
+ 3. glm/glm-4.7
+ 4. if/kimi-k2-thinking
+```
+
+When quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.
+
+#### 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)
+
+#### 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)
🚀 30. "Saya perlu mengirimkan alur kerja agen tanpa gepeng kode lem"
+🚀 30. "I need to ship agentic workflows without glue-code sprawl"
-Tim kehilangan kecepatan saat menggabungkan beberapa layanan dan skrip ad-hoc. +Teams lose velocity when stitching multiple ad-hoc services and scripts. -**Bagaimana OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- Strategi titik akhir terpadu untuk klien dan agen -- UI manajemen protokol bawaan dan jalur validasi asap -- Fondasi siap produksi (keamanan, logging, ketahanan, cadangan) +- Unified endpoint strategy for clients and agents +- Built-in protocol management UIs and smoke validation paths +- Production-ready foundations (security, logging, resilience, backup)
-` blok → `reasoning_content` untuk model berpikir
-- **Keluaran terstruktur** — `json_schema` → `responseMimeType`/`responseSchema` Gemini
-
-### 👥 Dukungan Multi-Akun
-
-- Tambahkan beberapa akun per penyedia
-- Perutean otomatis round-robin atau berbasis prioritas
-- Penggantian ke akun berikutnya ketika ada yang mencapai kuota
-
-### 🔄 Penyegaran Token Otomatis
-
-- Token OAuth secara otomatis disegarkan sebelum masa berlakunya habis
-- Tidak diperlukan otentikasi ulang manual
-- Pengalaman mulus di semua penyedia
-
-### 🎨 Kombo Khusus
-
-- Buat kombinasi model tanpa batas
-- 6 strategi: isi pertama, round-robin, kekuatan dua pilihan, acak, paling jarang digunakan, hemat biaya
-- Bagikan kombo di seluruh perangkat dengan Cloud Sync
-
-### 🏥 Dasbor Kesehatan
-
-- Status sistem (waktu aktif, versi, penggunaan memori)
-- Status pemutus sirkuit per penyedia (Tertutup/Terbuka/Setengah Terbuka)
-- Status batas tarif dan penguncian aktif
-- Statistik cache tanda tangan
-- Telemetri latensi (p50/p95/p99) + cache cepat
-- Atur ulang status kesehatan dengan satu klik
-
-### 🔧 Taman Bermain Penerjemah
-
-OmniRoute menyertakan Taman Bermain Penerjemah bawaan yang canggih dengan **4 mode** untuk melakukan debug, menguji, dan memantau terjemahan API:
-
-| Modus | Deskripsi |
-| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **💻 Taman bermain** | Terjemahan format langsung — tempelkan isi permintaan API apa pun dan langsung lihat bagaimana OmniRoute menerjemahkannya antar format penyedia (OpenAI ↔ Claude ↔ Gemini ↔ Responses API). Termasuk contoh templat dan deteksi otomatis format. |
-| **💬 Penguji Obrolan** | Kirim permintaan obrolan nyata melalui OmniRoute dan lihat perjalanan pulang pergi selengkapnya: masukan Anda, permintaan yang diterjemahkan, respons penyedia, dan respons yang diterjemahkan kembali. Sangat berharga untuk memvalidasi perutean kombo. |
-| **🧪 Bangku Tes** | Mode pengujian batch — tentukan beberapa kasus pengujian dengan masukan berbeda dan keluaran yang diharapkan, jalankan semuanya sekaligus, dan bandingkan hasilnya di seluruh penyedia dan model. |
-| **📱 Monitor Langsung** | Pemantauan permintaan waktu nyata — perhatikan permintaan masuk saat mengalir melalui OmniRoute, lihat terjemahan format yang terjadi secara langsung, dan identifikasi masalah secara instan. |
-
-**Akses:** Dasbor → Penerjemah (bilah samping)
-
-### 💾 Sinkronisasi Awan
-
-- Sinkronisasi penyedia, kombo, dan pengaturan di seluruh perangkat
-- Sinkronisasi latar belakang otomatis
-- Penyimpanan terenkripsi yang aman
+- `GET /api/mcp/status`
+- `GET /api/mcp/tools`
+- `GET /api/mcp/audit`
+- `GET /api/mcp/audit/stats`
-## 🧪 Evaluasi (Eval)
+📖 Detail Fitur
+🧩 MCP Setup (Model Context Protocol)
-### 🎯 Penggantian 4 Tingkat yang Cerdas +Start MCP transport in stdio mode: -Buat kombo dengan fallback otomatis: - -``` -Combo: "my-coding-stack" - 1. cc/claude-opus-4-6 (your subscription) - 2. nvidia/llama-3.3-70b (free NVIDIA API) - 3. glm/glm-4.7 (cheap backup, $0.6/1M) - 4. if/kimi-k2-thinking (free fallback) - -→ Auto switches when quota runs out or errors occur +```bash +omniroute --mcp ``` -### 📊 Pelacakan Kuota Waktu Nyata +Recommended validation flow: -- Konsumsi token per penyedia -- Atur ulang hitungan mundur (5 jam, harian, mingguan) -- Estimasi biaya untuk tingkatan berbayar -- Laporan pengeluaran bulanan +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. -### 🔄 Format Terjemahan +Useful APIs for automation: -Terjemahan mulus antar format: - -- **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **Respon OpenAI** -- Alat CLI Anda mengirimkan format OpenAI → OmniRoute menerjemahkan → Penyedia menerima format asli -- Bekerja dengan alat apa pun yang mendukung titik akhir OpenAI khusus -- **Sanitasi respons** — Menghapus kolom non-standar untuk kompatibilitas OpenAI SDK yang ketat -- **Normalisasi peran** — `developer` → `system` untuk non-OpenAI; `system` → `user` untuk model GLM/ERNIE -- **Think tag ekstraksi** — `
+
🤝 A2A Setup (Agent2Agent)
-OmniRoute menyertakan kerangka evaluasi bawaan untuk menguji kualitas respons LLM terhadap rangkaian emas. Akses melalui **Analytics → Evals** di dasbor. +Discover the agent: -### Set Emas Bawaan +```bash +curl http://localhost:20128/.well-known/agent.json +``` -"OmniRoute Golden Set" yang dimuat sebelumnya berisi 10 kasus uji yang meliputi: +Send a task: -- Salam, matematika, geografi, pembuatan kode -- Kepatuhan format JSON, terjemahan, penurunan harga -- Penolakan keamanan (konten berbahaya), penghitungan, logika boolean +```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."}]}}' +``` -### Strategi Evaluasi +Manage lifecycle: -| Strategi | Deskripsi | Contoh | -| ---------- | ------------------------------------------------------------ | -------------------------------- | -| `exact` | Output harus sama persis | `"4"` | -| `contains` | Output harus berisi substring (tidak peka huruf besar-kecil) | `"Paris"` | -| `regex` | Output harus sesuai dengan pola regex | `"1.*2.*3"` | -| `custom` | Fungsi JS khusus mengembalikan benar/salah | `(output) => output.length > 10` | +- `GET /api/a2a/status` +- `GET /api/a2a/tasks` +- `GET /api/a2a/tasks/:id` +- `POST /api/a2a/tasks/:id/cancel` ---- +Operational UI: -## 📖 Panduan Pengaturan +- `/dashboard/a2a` for task/state/stream observability and smoke actions + +
-
+
+💳 Penyedia Langganan
+🧪 End-to-end protocol validation
-### Kode Claude (Pro/Maks) +Validate both protocols with real clients: + +```bash +npm run test:protocols:e2e +``` + +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) ```bash Dashboard → Providers → Connect Claude Code @@ -1066,9 +1438,9 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Kiat Pro:** Gunakan Opus untuk tugas kompleks, Soneta untuk kecepatan. OmniRoute melacak kuota per model! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! -### Kodeks OpenAI (Plus/Pro) +### OpenAI Codex (Plus/Pro) ```bash Dashboard → Providers → Connect Codex @@ -1080,24 +1452,24 @@ Models: cx/gpt-5.1-codex-max ``` -#### Manajemen Limit Akun Codex (5h + Mingguan) +#### Codex Account Limit Management (5h + Weekly) -Setiap akun Codex sekarang punya toggle kebijakan di `Dashboard -> Providers`: +Each Codex account now has policy toggles in `Dashboard -> Providers`: -- `5h` (ON/OFF): menerapkan kebijakan ambang untuk jendela 5 jam. -- `Weekly` (ON/OFF): menerapkan kebijakan ambang untuk jendela mingguan. -- Perilaku ambang: saat jendela yang aktif mencapai >=90% penggunaan, akun tersebut di-skip. -- Perilaku rotasi: OmniRoute otomatis merutekan ke akun Codex berikutnya yang masih eligible. -- Perilaku reset: saat waktu `resetAt` provider sudah lewat, akun otomatis bisa dipakai lagi. +- `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. -Skenario: +Scenarios: -- `5h ON` + `Weekly ON`: akun di-skip jika salah satu jendela mencapai ambang. -- `5h OFF` + `Weekly ON`: hanya penggunaan mingguan yang bisa memblokir akun. -- `5h ON` + `Weekly OFF`: hanya penggunaan 5 jam yang bisa memblokir akun. -- `resetAt` sudah lewat: akun otomatis masuk rotasi lagi (tanpa enable manual). +- `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). -### Gemini CLI (GRATIS 180K/bulan!) +### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -1109,9 +1481,9 @@ Models: gc/gemini-2.5-pro ``` -**Nilai Terbaik:** Tingkat gratis yang sangat besar! Gunakan ini sebelum tingkatan berbayar. +**Best Value:** Huge free tier! Use this before paid tiers. -### Kopilot GitHub +### GitHub Copilot ```bash Dashboard → Providers → Connect GitHub @@ -1127,88 +1499,88 @@ Models:
-
🔑 Penyedia Kunci API
+🔑 API Key Providers
-### NVIDIA NIM (GRATIS 1000 kredit!) +### NVIDIA NIM (FREE developer access — 70+ models) -1. Daftar: [build.nvidia.com](https://build.nvidia.com) -2. Dapatkan kunci API gratis (termasuk 1000 kredit inferensi) -3. Dasbor → Tambah Penyedia → NVIDIA NIM: - - Kunci API: `nvapi-your-key` +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` -**Model:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, dan 50+ lainnya +**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more -**Kiat Pro:** API yang kompatibel dengan OpenAI — bekerja secara lancar dengan terjemahan format OmniRoute! +**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation! -### Pencarian Dalam +### DeepSeek -1. Daftar: [platform.deepseek.com](https://platform.deepseek.com) -2. Dapatkan kunci API -3. Dasbor → Tambah Penyedia → DeepSeek +1. Sign up: [platform.deepseek.com](https://platform.deepseek.com) +2. Get API key +3. Dashboard → Add Provider → DeepSeek -**Model:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` +**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` -### Groq (Tersedia Tingkat Gratis!) +### Groq (Free Tier Available!) -1. Daftar: [console.groq.com](https://console.groq.com) -2. Dapatkan kunci API (termasuk tingkat gratis) -3. Dasbor → Tambah Penyedia → Groq +1. Sign up: [console.groq.com](https://console.groq.com) +2. Get API key (free tier included) +3. Dashboard → Add Provider → Groq -**Model:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` +**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` -**Kiat Pro:** Inferensi ultra-cepat — terbaik untuk pengkodean waktu nyata! +**Pro Tip:** Ultra-fast inference — best for real-time coding! -### OpenRouter (100+ Model) +### OpenRouter (100+ Models) -1. Daftar: [openrouter.ai](https://openrouter.ai) -2. Dapatkan kunci API -3. Dasbor → Tambah Penyedia → OpenRouter +1. Sign up: [openrouter.ai](https://openrouter.ai) +2. Get API key +3. Dashboard → Add Provider → OpenRouter -**Model:** Akses 100+ model dari semua penyedia utama melalui satu kunci API. +**Models:** Access 100+ models from all major providers through a single API key.
-
💰 Penyedia Murah (Cadangan)
+💰 Cheap Providers (Backup)
-### GLM-4.7 (Reset harian, $0,6/1 juta) +### GLM-4.7 (Daily reset, $0.6/1M) -1. Daftar: [Zhipu AI](https://open.bigmodel.cn/) -2. Dapatkan kunci API dari Coding Plan -3. Dasbor → Tambahkan Kunci API: - - Penyedia: `glm` - - Kunci API: `your-key` +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` -**Gunakan:** `glm/glm-4.7` +**Use:** `glm/glm-4.7` -**Tips Pro:** Paket Coding menawarkan 3× kuota dengan biaya 1/7! Reset setiap hari pukul 10.00. +**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -### MiniMax M2.1 (reset 5 jam, $0,20/1 juta) +### MiniMax M2.1 (5h reset, $0.20/1M) -1. Daftar: [MiniMax](https://www.minimax.io/) -2. Dapatkan kunci API -3. Dasbor → Tambahkan Kunci API +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key +3. Dashboard → Add API Key -**Gunakan:** `minimax/MiniMax-M2.1` +**Use:** `minimax/MiniMax-M2.1` -**Kiat Pro:** Opsi termurah untuk konteks panjang (1 juta token)! +**Pro Tip:** Cheapest option for long context (1M tokens)! -### Kimi K2 ($9/bulan tetap) +### Kimi K2 ($9/month flat) -1. Berlangganan: [Moonshot AI](https://platform.moonshot.ai/) -2. Dapatkan kunci API -3. Dasbor → Tambahkan Kunci API +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key +3. Dashboard → Add API Key -**Gunakan:** `kimi/kimi-latest` +**Use:** `kimi/kimi-latest` -**Kiat Pro:** Memperbaiki $9/bulan untuk 10 juta token = biaya efektif $0,90/1 juta! +**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
-
🆓 Penyedia GRATIS (Cadangan Darurat)
+🆓 FREE Providers (Emergency Backup)
-### iFlow (8 model GRATIS) +### iFlow (5 FREE models via OAuth) ```bash Dashboard → Connect iFlow @@ -1223,7 +1595,7 @@ Models: if/deepseek-r1 ``` -### Qwen (3 model GRATIS) +### Qwen (4 FREE models via Device Code) ```bash Dashboard → Connect Qwen @@ -1235,7 +1607,7 @@ Models: qw/qwen3-coder-flash ``` -### Kiro (Claude GRATIS) +### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro @@ -1250,9 +1622,9 @@ Models:
-
🎨 Buat Kombo
+🎨 Create Combos
-### Contoh 1: Maksimalkan Langganan → Cadangan Murah +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -1266,7 +1638,7 @@ Models: Use in CLI: premium-coding ``` -### Contoh 2: Gratis Saja (Tanpa Biaya) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -1281,9 +1653,9 @@ Cost: $0 forever!
-
---
-## 🐛 Pemecahan masalah
+## Pemecahan Masalah
🔧 Integrasi CLI
+🔧 CLI Integration
-### IDE Kursor +### Cursor IDE ``` Settings → Models → Advanced: @@ -1292,11 +1664,11 @@ Settings → Models → Advanced: Model: cc/claude-opus-4-6 ``` -### Kode Claude +### Claude Code -Gunakan halaman **Alat CLI** di dasbor untuk konfigurasi sekali klik, atau edit `~/.claude/settings.json` secara manual. +Use the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually. -### Kodeks CLI +### Codex CLI ```bash export OPENAI_BASE_URL="http://localhost:20128" @@ -1305,15 +1677,15 @@ export OPENAI_API_KEY="your-omniroute-api-key" codex "your prompt" ``` -### Buka Cakar +### OpenClaw -**Opsi 1 — Dasbor (disarankan):** +**Option 1 — Dashboard (recommended):** ``` Dashboard → CLI Tools → OpenClaw → Select Model → Apply ``` -**Opsi 2 — Panduan:** Sunting `~/.openclaw/openclaw.json`: +**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`: ```json { @@ -1329,9 +1701,9 @@ Dashboard → CLI Tools → OpenClaw → Select Model → Apply } ``` -> **Catatan:** OpenClaw hanya berfungsi dengan OmniRoute lokal. Gunakan `127.0.0.1` alih-alih `localhost` untuk menghindari masalah resolusi IPv6. +> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues. -### Cline / Lanjutkan / RooCode +### Cline / Continue / RooCode ``` Settings → API Configuration: @@ -1341,110 +1713,245 @@ Settings → API Configuration: 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. +
-
-- **Runtime**: Node.js 18–22 LTS (⚠️ Node.js 24+ **tidak didukung** — `better-sqlite3` biner asli tidak kompatibel)
-- **Bahasa**: TypeScript 5.9 — **100% TypeScript** di `src/` dan `open-sse/` (v1.0.6)
-- **Kerangka Kerja**: Next.js 16 + React 19 + Tailwind CSS 4
-- **Database**: LowDB (JSON) + SQLite (status domain + log proksi)
-- **Streaming**: Peristiwa Terkirim Server (SSE)
-- **Auth**: OAuth 2.0 (PKCE) + JWT + Kunci API
-- **Pengujian**: pelari pengujian Node.js (368+ pengujian unit)
-- **CI/CD**: Tindakan GitHub (publikasi npm otomatis + Docker Hub saat dirilis)
-- **Situs Web**: [omniroute.online](https://omniroute.online)
-- **Paket**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
-- **Pekerja Pelabuhan**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
-- **Ketahanan**: Pemutus sirkuit, kemunduran eksponensial, kawanan anti-guntur, spoofing TLS
-
----
-
-## 📖 Dokumentasi
-
-| Dokumen | Deskripsi |
-| -------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Penyedia, kombo, integrasi CLI, penerapan |
-| [API Reference](docs/API_REFERENCE.md) | Semua titik akhir dengan contoh |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Masalah umum dan solusinya |
-| [Architecture](docs/ARCHITECTURE.md) | Arsitektur sistem dan internal |
-| [Contributing](CONTRIBUTING.md) | Pengaturan dan pedoman pengembangan |
-| [OpenAPI Spec](docs/openapi.yaml) | Spesifikasi OpenAPI 3.0 |
-| [Security Policy](SECURITY.md) | Pelaporan kerentanan dan praktik keamanan |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Panduan lengkap: VM + nginx + Pengaturan Cloudflare |
-| [Features Gallery](docs/FEATURES.md) | Tur dasbor visual dengan tangkapan layar |
-
-### 📸 Pratinjau Dasbor
+## 🛠️ Tech Stack
Klik untuk memperluas panduan pemecahan masalah
+Click to expand troubleshooting guide
-**"Model bahasa tidak memberikan pesan"** +**"Language model did not provide messages"** -- Kuota penyedia habis → Periksa dashboard pelacak kuota -- Solusi: Gunakan combo fallback atau beralih ke tier yang lebih murah +- Provider quota exhausted → Check dashboard quota tracker +- Solution: Use combo fallback or switch to cheaper tier -**Pembatasan tarif** +**Rate limiting** -- Kuota berlangganan habis → Penggantian ke GLM/MiniMax -- Tambahkan kombo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Subscription quota out → Fallback to GLM/MiniMax +- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -**Token OAuth kedaluwarsa** +**OAuth token expired** -- Disegarkan secara otomatis oleh OmniRoute -- Jika masalah terus berlanjut: Dasbor → Penyedia → Sambungkan kembali +- Auto-refreshed by OmniRoute +- If issues persist: Dashboard → Provider → Reconnect -**Biaya tinggi** +**High costs** -- Periksa statistik penggunaan di Dashboard → Biaya -- Ganti model utama ke GLM/MiniMax -- Gunakan tingkat gratis (Gemini CLI, iFlow) untuk tugas-tugas yang tidak penting +- Check usage stats in Dashboard → Costs +- Switch primary model to GLM/MiniMax +- Use free tier (Gemini CLI, iFlow) for non-critical tasks -**Dasbor terbuka pada port yang salah** +**Dashboard/API ports are wrong** -- Tetapkan `PORT=20128` dan `NEXT_PUBLIC_BASE_URL=http://localhost:20128` +- `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) -**Kesalahan sinkronisasi cloud** +**Cloud sync errors** -- Verifikasi `BASE_URL` poin ke instance Anda yang sedang berjalan -- Verifikasi `CLOUD_URL` poin ke titik akhir cloud yang Anda harapkan -- Jaga agar nilai `NEXT_PUBLIC_*` selaras dengan nilai sisi server +- 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 -**Login pertama tidak berfungsi** +**First login not working** -- Periksa `INITIAL_PASSWORD` di `.env` -- Jika tidak disetel, kata sandi cadangan adalah `123456` +- Check `INITIAL_PASSWORD` in `.env` +- If unset, fallback password is `123456` -**Tidak ada log permintaan** +**No request logs** -- Tetapkan `ENABLE_REQUEST_LOGS=true` di `.env` +- Set `ENABLE_REQUEST_LOGS=true` in `.env` -**Tes koneksi menunjukkan "Tidak Valid" untuk penyedia yang kompatibel dengan OpenAI** +**Connection test shows "Invalid" for OpenAI-compatible providers** -- Banyak penyedia tidak mengekspos titik akhir `/models` -- OmniRoute v1.0.6+ menyertakan validasi fallback melalui penyelesaian obrolan -- Pastikan URL dasar menyertakan akhiran `/v1` +- 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 +### 🔐 OAuth on a Remote Server + -> **⚠️ PENTING bagi pengguna dengan OmniRoute pada VPS/Docker/server jarak jauh** +> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server** -### OAuth +#### Why does Antigravity / Gemini CLI OAuth fail on remote servers? -Pembuktiannya **Antigravitasi** dan **Gemini CLI** digunakan **Google OAuth 2.0** untuk autentikasi. Google meminta agar `redirect_uri` menggunakan OAuth yang terus berubah, jadi **exatamente** adalah URI yang sudah ada sebelumnya di Google Cloud Console yang dapat diterapkan. +The **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console. -Karena kredensial OAuth yang diberikan pada OmniRoute adalah kadastrada **apenas untuk `localhost`**. Ketika Anda mengakses OmniRoute dari server jarak jauh (misal: `https://omniroute.meuservidor.com`), atau Google meminta autenticação com: +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 ``` -### Solusi: Konfigurasikan akun OAuth Anda +#### Solution: Configure your own OAuth credentials -Anda perlu membuat **ID Klien OAuth 2.0** di Google Cloud Console dengan URI di server Anda. +You need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI. -#### Lewati dulu +#### Step-by-step -**1. Mengakses Google Cloud Console** +**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 + +# For Gemini CLI: +GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com +GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +``` + +**6. Restart OmniRoute** + +```bash +# npm: +npm run dev + +# Docker: +docker restart omniroute +``` + +**7. Try connecting again** + +Dashboard → Providers → Antigravity (or Gemini CLI) → OAuth + +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. + +--- + +
+
---
-## 🛠️
+🇧🇷 Versão em Português
+ +#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos? + +Os provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo. + +As credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticação com: + +``` +Error 400: redirect_uri_mismatch +``` + +#### Solução: Configure suas próprias credenciais OAuth + +Você precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor. + +#### Passo a passo + +**1. Acesse o Google Cloud Console** Abra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) -**2. Inilah ID Klien OAuth 2.0 yang baru** +**2. Crie um novo OAuth 2.0 Client ID** -- Klik pada **"+ Buat Kredensial"** → **"ID klien OAuth"** -- Tip aplikasi: **"Aplikasi web"** -- Nama: nama escolha qualquer (misal: `OmniRoute Remote`) +- Clique em **"+ Create Credentials"** → **"OAuth client ID"** +- Tipo de aplicativo: **"Web application"** +- Nome: escolha qualquer nome (ex: `OmniRoute Remote`) -**3. Tambahan sebagai URI Pengalihan Resmi** +**3. Adicione as Authorized Redirect URIs** -Selain itu **"URI pengalihan resmi"**, tambahan: +No campo **"Authorized redirect URIs"**, adicione: ``` https://seu-servidor.com/callback ``` -> Pengganti `seu-servidor.com` pelo domínio atau IP ke server Anda (termasuk port yang diperlukan, misal: `http://45.33.32.156:20128/callback`). +> Substitua `seu-servidor.com` pelo domínio ou IP do seu servidor (inclua a porta se necessário, ex: `http://45.33.32.156:20128/callback`). -**4. Salep dan salin sebagai kredensial** +**4. Salve e copie as credenciais** -Kemudian, Google menampilkan **ID Klien** dan **Rahasia Klien**. +Após criar, o Google mostrará o **Client ID** e o **Client Secret**. -**5. Konfigurasikan sebagai variáveis de ambiente** +**5. Configure as variáveis de ambiente** -Di `.env` (atau berbagai lingkungan di Docker): +No seu `.env` (ou nas variáveis de ambiente do Docker): ```bash # Para Antigravity: @@ -1457,7 +1964,7 @@ GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret ``` -**6. Memulai kembali OmniRoute** +**6. Reinicie o OmniRoute** ```bash # Se usando npm: @@ -1467,152 +1974,147 @@ npm run dev docker restart omniroute ``` -**7. Mari kita sambungkan lagi** +**7. Tente conectar novamente** -Dasbor → Penyedia → Antigravitasi (atau Gemini CLI) → OAuth +Dashboard → Providers → Antigravity (ou Gemini CLI) → OAuth -Sekarang o Google dialihkan langsung ke `https://seu-servidor.com/callback` dan autentikasi berfungsi. +Agora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará. --- -### Solusi sementara (sem configurar credenciais próprias) +#### Workaround temporário (sem configurar credenciais próprias) -Jika Anda tidak ingin membuat kredensial pribadi sekarang, Anda mungkin dapat menggunakan fluks **panduan URL**: +Se não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**: -1. O OmniRoute membuka URL autoriza dari Google -2. Setelah Anda autorizar, Google mengarahkan pengalihan ke `localhost` (yang gagal pada server jarak jauh) -3. **Salin URL lengkap** dari bilah akhir browser Anda (meskipun halaman tidak dimuat) -4. Gunakan URL ini karena tidak ada modal koneksi ke OmniRoute -5. Klik pada **"Hubungkan"** +1. O OmniRoute abrirá a URL de autorização do Google +2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto) +3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue) +4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute +5. Clique em **"Connect"** -> Solusi ini berfungsi karena kode otorisasi pada URL valid secara independen untuk mengarahkan ulang ke akun atau tidak. +> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.
-
---
-## 🗺️
+## Dokumentasi
-OmniRoute memiliki **210+ fitur yang direncanakan** di berbagai fase pengembangan. Berikut adalah bidang-bidang utamanya:
-
-| Kategori | Fitur yang Direncanakan | Sorotan |
-| ---------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------- |
-| 🧠 **Perutean & Kecerdasan** | 25+ | Perutean latensi terendah, perutean berbasis tag, preflight kuota, pemilihan akun P2C |
-| 🔒 **Keamanan & Kepatuhan** | 20+ | Pengerasan SSRF, penyelubungan kredensial, batas tarif per titik akhir, pelingkupan kunci manajemen |
-| 📊 **Kemampuan Observasi** | 15+ | Integrasi OpenTelemetry, pemantauan kuota waktu nyata, pelacakan biaya per model |
-| 🔄 **Integrasi Penyedia** | 20+ | Registri model dinamis, cooldown penyedia, Codex multi-akun, penguraian kuota Salinan |
-| ⚡ **Kinerja** | 15+ | Lapisan cache ganda, cache cepat, cache respons, streaming keepalive, API batch |
-| 🌐 **Ekosistem** | 10+ | WebSocket API, konfigurasi hot-reload, penyimpanan konfigurasi terdistribusi, mode komersial |
-
-### 🔜 Segera Hadir
-
-- 🔗 **Integrasi OpenCode** — Dukungan penyedia asli untuk IDE pengkodean AI OpenCode
-- 🔗 **Integrasi TRAE** — Dukungan penuh untuk kerangka pengembangan AI TRAE
-- 📦 **Batch API** — Pemrosesan batch asinkron untuk permintaan massal
-- 🎯 **Perutean Berbasis Tag** — Merutekan permintaan berdasarkan tag dan metadata khusus
-- 💰 **Strategi Biaya Terendah** — Secara otomatis memilih penyedia termurah yang tersedia
-
-> 📝 Spesifikasi fitur lengkap tersedia di [link](docs/new-features/) (217 spesifikasi detail)
+| Document | Description |
+| ---------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 16 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/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
+| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
-## 👥 Kontributor
+## 🗺️ Roadmap
+
+OmniRoute has **210+ 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, P2C account selection |
+| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |
+| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |
+| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider 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
[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
-### Cara Berkontribusi
+### How to Contribute
-1. Cabangkan repositori
-2. Buat cabang fitur Anda (`git checkout -b feature/amazing-feature`)
-3. Komit perubahan Anda (`git commit -m 'Add amazing feature'`)
-4. Dorong ke cabang (`git push origin feature/amazing-feature`)
-5. Buka Permintaan Tarik
+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
-Lihat [CONTRIBUTING.md](CONTRIBUTING.md) untuk panduan detailnya.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
-### Merilis Versi Baru
+### Releasing a New Version
```bash
# Create a release — npm publish happens automatically
-gh release create v1.0.6 --title "v1.0.6" --generate-notes
+gh release create v2.0.0 --title "v2.0.0" --generate-notes
```
---
-## 📊 Sejarah Bintang
+## 📊 Star History
## Stargazers over time
## [](https://starchart.cc/diegosouzapw/OmniRoute)
-## 🙏 Ucapan Terima Kasih
+## 🙏 Acknowledgments
-Terima kasih khusus kepada **[9router](https://github.com/decolua/9router)** oleh **[decolua](https://github.com/decolua)** — proyek asli yang menginspirasi fork ini. OmniRoute dibangun di atas fondasi luar biasa tersebut dengan fitur tambahan, API multi-modal, dan penulisan ulang TypeScript lengkap.
+Special thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.
-Terima kasih khusus kepada **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — implementasi Go asli yang menginspirasi port JavaScript ini.
+Special thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.
---
-## 📄 Lisensi
+## Lisensi
-Lisensi MIT - lihat [LICENSE](LICENSE) untuk detailnya.
+MIT License - see [LICENSE](LICENSE) for details.
---
Klik untuk melihat tangkapan layar dasbor
+Click to expand tech stack details
-| Halaman | Tangkapan layar | -| ------------------ | ------------------------------------------------- | -| **Penyedia** |  | -| **Kombo** |  | -| **Analitik** |  | -| **Kesehatan** |  | -| **Penerjemah** |  | -| **Pengaturan** |  | -| **Alat CLI** |  | -| **Log Penggunaan** |  | -| **Titik Akhir** |  | +- **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**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions) +- **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
- Dibangun dengan ❤️ untuk pengembang yang membuat kode 24/7
+ Built with ❤️ for developers who code 24/7
omniroute.online
+
diff --git a/docs/i18n/id/docs/FEATURES.md b/docs/i18n/id/docs/FEATURES.md
new file mode 100644
index 0000000000..364d7774f4
--- /dev/null
+++ b/docs/i18n/id/docs/FEATURES.md
@@ -0,0 +1,145 @@
+# OmniRoute — Dashboard Features Gallery (Bahasa Indonesia)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/FEATURES.md) · 🇪🇸 [es](../../es/docs/FEATURES.md) · 🇫🇷 [fr](../../fr/docs/FEATURES.md) · 🇩🇪 [de](../../de/docs/FEATURES.md) · 🇮🇹 [it](../../it/docs/FEATURES.md) · 🇷🇺 [ru](../../ru/docs/FEATURES.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FEATURES.md) · 🇯🇵 [ja](../../ja/docs/FEATURES.md) · 🇰🇷 [ko](../../ko/docs/FEATURES.md) · 🇸🇦 [ar](../../ar/docs/FEATURES.md) · 🇮🇳 [in](../../in/docs/FEATURES.md) · 🇹🇭 [th](../../th/docs/FEATURES.md) · 🇻🇳 [vi](../../vi/docs/FEATURES.md) · 🇮🇩 [id](../../id/docs/FEATURES.md) · 🇲🇾 [ms](../../ms/docs/FEATURES.md) · 🇳🇱 [nl](../../nl/docs/FEATURES.md) · 🇵🇱 [pl](../../pl/docs/FEATURES.md) · 🇸🇪 [sv](../../sv/docs/FEATURES.md) · 🇳🇴 [no](../../no/docs/FEATURES.md) · 🇩🇰 [da](../../da/docs/FEATURES.md) · 🇫🇮 [fi](../../fi/docs/FEATURES.md) · 🇵🇹 [pt](../../pt/docs/FEATURES.md) · 🇷🇴 [ro](../../ro/docs/FEATURES.md) · 🇭🇺 [hu](../../hu/docs/FEATURES.md) · 🇧🇬 [bg](../../bg/docs/FEATURES.md) · 🇸🇰 [sk](../../sk/docs/FEATURES.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FEATURES.md) · 🇮🇱 [he](../../he/docs/FEATURES.md) · 🇵🇭 [phi](../../phi/docs/FEATURES.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FEATURES.md)
+
+---
+
+Visual guide to every section of the OmniRoute dashboard.
+
+---
+
+## 🔌 Providers
+
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
+
+
+
+---
+
+## 🎨 Combos
+
+Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
+
+
+
+---
+
+## 📊 Analytics
+
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
+
+
+
+---
+
+## 🏥 System Health
+
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+
+
+
+---
+
+## 🔧 Translator Playground
+
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
+
+
+
+---
+
+## 🎮 Model Playground _(v2.0.9+)_
+
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
+
+---
+
+## 🎨 Themes _(v2.0.5+)_
+
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
+
+## ⚙️ Settings
+
+Comprehensive settings panel with tabs:
+
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning
+- **Advanced** — Configuration overrides
+
+
+
+---
+
+## 🔧 CLI Tools
+
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
+
+
+
+---
+
+## 🤖 CLI Agents _(v2.0.11+)_
+
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
+
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
+
+---
+
+## 🖼️ Media _(v2.0.3+)_
+
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
+
+## 📝 Request Logs
+
+Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
+
+
+
+---
+
+## 🌐 API Endpoint
+
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
+
+
+
+---
+
+## 🔑 API Key Management
+
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
+
+---
+
+## 📋 Audit Log
+
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
+
+---
+
+## 🖥️ Desktop Application
+
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
+
+Key features:
+
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
+
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.
diff --git a/docs/i18n/in/README.md b/docs/i18n/in/README.md
index 666ccba11d..e95bf306f0 100644
--- a/docs/i18n/in/README.md
+++ b/docs/i18n/in/README.md
@@ -1,127 +1,213 @@
+# 🚀 OmniRoute — The Free AI Gateway (हिन्दी)
+
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
+
+---
+
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
+
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
omniroute.online
-
-
- # 🚀 ओम्निरूट - निःशुल्क एआई गेटवे
-
-🌐 **[English](#-omniroute--the-free-ai-gateway)** | \***\*ओएमएनआई_टोकन_159\*\***
-
-### कोडिंग कभी बंद न करें। स्वचालित फ़ॉलबैक के साथ **मुफ़्त और कम लागत वाले AI मॉडल** के लिए स्मार्ट रूटिंग।
-
-_आपका सार्वभौमिक एपीआई प्रॉक्सी - एक समापन बिंदु, 36+ प्रदाता, शून्य डाउनटाइम।_
-
-**चैट समापन • एंबेडिंग • छवि निर्माण • ऑडियो • पुनर्रैंकिंग • 100% टाइपस्क्रिप्ट**
-
----
-
-### 🤖 आपके पसंदीदा कोडिंग एजेंटों के लिए निःशुल्क एआई प्रदाता
-
-_OmniRoute के माध्यम से किसी भी AI-संचालित IDE या CLI टूल को कनेक्ट करें - असीमित कोडिंग के लिए निःशुल्क API गेटवे।_
-
-📡 सभी एजेंट ` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
-
-### 🆕 What's New in v3.0.0
-
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
-
----
[](https://www.npmjs.com/package/omniroute)
+[](https://www.npmjs.com/package/omniroute)
[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
[](https://omniroute.online)
[](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)
-🌐 **Available in:** 🇺🇸 [English](../../README.md) | 🇧🇷 [Português (Brasil)](../pt-BR/README.md) | 🇪🇸 [Español](../es/README.md) | 🇫🇷 [Français](../fr/README.md) | 🇮🇹 [Italiano](../it/README.md) | 🇷🇺 [Русский](../ru/README.md) | 🇨🇳 [中文 (简体)](../zh-CN/README.md) | 🇩🇪 [Deutsch](../de/README.md) | 🇮🇳 [हिन्दी](../in/README.md) | 🇹🇭 [ไทย](../th/README.md) | 🇺🇦 [Українська](../uk-UA/README.md) | 🇸🇦 [العربية](../ar/README.md) | 🇯🇵 [日本語](../ja/README.md) | 🇻🇳 [Tiếng Việt](../vi/README.md) | 🇧🇬 [Български](../bg/README.md) | 🇩🇰 [Dansk](../da/README.md) | 🇫🇮 [Suomi](../fi/README.md) | 🇮🇱 [עברית](../he/README.md) | 🇭🇺 [Magyar](../hu/README.md) | 🇮🇩 [Bahasa Indonesia](../id/README.md) | 🇰🇷 [한국어](../ko/README.md) | 🇲🇾 [Bahasa Melayu](../ms/README.md) | 🇳🇱 [Nederlands](../nl/README.md) | 🇳🇴 [Norsk](../no/README.md) | 🇵🇹 [Português (Portugal)](../pt/README.md) | 🇷🇴 [Română](../ro/README.md) | 🇵🇱 [Polski](../pl/README.md) | 🇸🇰 [Slovenčina](../sk/README.md) | 🇸🇪 [Svenska](../sv/README.md) | 🇵🇭 [Filipino](../phi/README.md)
+
+
+🌐 **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)
---
-## 🖼️
+## 🆕 What's New in v3.0.0
+
+> **Upgrading from v2.9.5?** — See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes.
+
+| Area | Change |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection remediation |
+| ✅ **Route Validation** | All 176 API routes now validated with Zod schemas + `validateBody()` — CI `check:route-validation:t06` passes |
+| 🐛 **omniModel Tag Leak** | Internal `http://localhost:20128/v1 या http://cloud.omniroute.online/v1 के माध्यम से जुड़ते हैं - एक कॉन्फ़िगरेशन, असीमित मॉडल और कोटा
-
----
-
-### 🆕 What's New in v3.0.0
-
-| Area | Change |
-| ------------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `
-
+
---
-## 📸
+## 📸 Dashboard Preview
+
-
---
-## 🤔ओम्नीरूट क्यों?
+### 🤖 Free AI Provider for your favorite coding agents
-**पैसा बर्बाद करना और सीमा पार करना बंद करें:**
+_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._
-- ...
+Click to see dashboard screenshots
-| # | # | -| ----- | ---------------------------------------- | -| **1** |  | -| **2** |  | -| **3** |  | -| **4** |  | -| **5** |  | -| **6** |  | -| **7** |  | -| **8** |  | -| **9** |  | +| Page | Screenshot | +| -------------- | ------------------------------------------------- | +| **Providers** |  | +| **Combos** |  | +| **Analytics** |  | +| **Health** |  | +| **Translator** |  | +| **Settings** |  | +| **CLI Tools** |  | +| **Usage Logs** |  | +| **Endpoints** |  | सदस्यता कोटा हर महीने अप्रयुक्त रूप से समाप्त हो जाता है
-- दर सीमा आपको कोडिंग के बीच में रोक देती है
-- महँगे API ($20-50/माह प्रति प्रदाता)
-- प्रदाताओं के बीच मैन्युअल स्विचिंग
+ |
+
+ + OpenClaw + + ⭐ 205K + |
+
+
+ + NanoBot + + ⭐ 20.9K + |
+
+
+  + PicoClaw + + ⭐ 14.6K + |
+
+
+ + ZeroClaw + + ⭐ 9.9K + |
+
+
+  + IronClaw + + ⭐ 2.1K + |
+
+
+  + OpenCode + + ⭐ 106K + |
+
+
+ + Codex CLI + + ⭐ 60.8K + |
+
+
+ + Claude Code + + ⭐ 67.3K + |
+
+
+ + Gemini CLI + + ⭐ 94.7K + |
+
+
+ + Kilo Code + + ⭐ 15.5K + |
+
http://localhost:20128/v1 or http://cloud.omniroute.online/v1 — one config, unlimited models and quota
---
-## 📧समर्थन
+## 🤔 Why OmniRoute?
-> 💬 **हमारे समुदाय में शामिल हों!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) - सहायता प्राप्त करें, सुझाव साझा करें और अपडेट रहें।
+**Stop wasting money and hitting limits:**
-- **वेबसाइट**: [omniroute.online](https://omniroute.online)
-- **गिटहब**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **मुद्दे**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
-- **व्हाट्सएप**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **मूल परियोजना**: [9router by decolua](https://github.com/decolua/9router)
+- 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:**
+
+- ✅ **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
+- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool
---
-## 🔄 यह कैसे काम करता है
+## 📧 Support
+
+> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.
+
+- **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`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
+
+---
+
+## 🔄 How It Works
```
┌─────────────┐
@@ -144,457 +230,459 @@ _OmniRoute के माध्यम से किसी भी AI-संचा
├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)
│ ↓ budget limit
└─→ [Tier 4: FREE] iFlow, Qwen, Kiro (unlimited)
-- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/
-
💸 1. "मैं एक महंगी सदस्यता के लिए भुगतान करता हूं लेकिन फिर भी सीमा से बाधित होता हूं"
+💸 1. "I pay for an expensive subscription but still get interrupted by limits"
-डेवलपर्स क्लाउड प्रो, कोडेक्स प्रो, या गिटहब कोपायलट के लिए $20-200/माह का भुगतान करते हैं। यहां तक कि भुगतान करने पर भी, कोटा की एक सीमा होती है - 5 घंटे का उपयोग, साप्ताहिक सीमा, या प्रति मिनट की दर सीमा। मध्य-कोडिंग सत्र में, प्रदाता प्रत्युत्तर देना बंद कर देता है और डेवलपर प्रवाह और उत्पादकता खो देता है। +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. -**ओम्नीरूट इसे कैसे हल करता है:** +**How OmniRoute solves it:** -- **स्मार्ट 4-टियर फ़ॉलबैक** - यदि सदस्यता कोटा समाप्त हो जाता है, तो स्वचालित रूप से एपीआई कुंजी पर रीडायरेक्ट हो जाता है → सस्ता → शून्य मैन्युअल हस्तक्षेप के साथ मुफ़्त -- **वास्तविक समय कोटा ट्रैकिंग** - रीसेट उलटी गिनती के साथ वास्तविक समय में टोकन खपत दिखाता है (5 घंटे, दैनिक, साप्ताहिक) -- **मल्टी-अकाउंट सपोर्ट** - ऑटो राउंड-रॉबिन के साथ प्रति प्रदाता एकाधिक खाते - जब एक खत्म हो जाता है, तो अगले पर स्विच हो जाता है -- **कस्टम कॉम्बो** - 6 संतुलन रणनीतियों (भरण-प्रथम, राउंड-रॉबिन, पी2सी, यादृच्छिक, कम से कम उपयोग, लागत-अनुकूलित) के साथ अनुकूलन योग्य फ़ॉलबैक चेन -- **कोडेक्स बिजनेस कोटा** - बिजनेस/टीम कार्यक्षेत्र कोटा की निगरानी सीधे डैशबोर्ड में +- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention +- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly) +- **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 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
-` ब्लॉक को मानकीकृत `reasoning_content` में निकालता है
-- **मिथुन राशि वालों के लिए संरचित आउटपुट** — `json_schema` → `responseMimeType`/`responseSchema` स्वचालित रूपांतरण
-- **`stream` डिफ़ॉल्ट रूप से `false`** पर आता है - OpenAI स्पेक के साथ संरेखित होता है, Python/Rust/Go SDKs में अप्रत्याशित SSE से बचता है
+- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 67+ 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
🔌 2. "मुझे कई प्रदाताओं का उपयोग करने की आवश्यकता है लेकिन प्रत्येक के पास एक अलग एपीआई है"
+🔌 2. "I need to use multiple providers but each has a different API"
-ओपनएआई एक प्रारूप का उपयोग करता है, क्लाउड (एंथ्रोपिक) दूसरे का उपयोग करता है, जेमिनी एक और का उपयोग करता है। यदि कोई डेवलपर विभिन्न प्रदाताओं के मॉडल का परीक्षण करना चाहता है या उनके बीच फ़ॉलबैक करना चाहता है, तो उन्हें एसडीके को फिर से कॉन्फ़िगर करना होगा, एंडपॉइंट बदलना होगा, असंगत प्रारूपों से निपटना होगा। कस्टम प्रदाताओं (फ्रेंडएलआई, एनआईएम) के पास गैर-मानक मॉडल एंडपॉइंट हैं। +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:** -- **एकीकृत समापन बिंदु** - एक एकल `http://localhost:20128/v1` सभी 36+ प्रदाताओं के लिए प्रॉक्सी के रूप में कार्य करता है -- **प्रारूप अनुवाद** - स्वचालित और पारदर्शी: ओपनएआई ↔ क्लाउड ↔ जेमिनी ↔ प्रतिक्रिया एपीआई -- **प्रतिक्रिया स्वच्छता** - गैर-मानक फ़ील्ड (`x_groq`, `usage_breakdown`, `service_tier`) को स्ट्रिप्स करता है जो OpenAI SDK v1.83+ को तोड़ता है -- **भूमिका सामान्यीकरण** - गैर-ओपनएआई प्रदाताओं के लिए `developer` → `system` परिवर्तित करता है; `system` → GLM/ERNIE के लिए `user` -- **टैग एक्सट्रैक्शन के बारे में सोचें** - डीपसीक R1 जैसे मॉडलों से `
-
🌐 3. "मेरा AI प्रदाता मेरे क्षेत्र/देश को ब्लॉक कर देता है"
+🌐 3. "My AI provider blocks my region/country"
-OpenAI/Codex जैसे प्रदाता कुछ भौगोलिक क्षेत्रों से पहुंच को रोकते हैं। OAuth और API कनेक्शन के दौरान उपयोगकर्ताओं को `unsupported_country_region_territory` जैसी त्रुटियां मिलती हैं। यह विकासशील देशों के डेवलपर्स के लिए विशेष रूप से निराशाजनक है। +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. -**ओम्नीरूट इसे कैसे हल करता है:** +**How OmniRoute solves it:** -- **3-स्तरीय प्रॉक्सी कॉन्फ़िगरेशन** - 3 स्तरों पर कॉन्फ़िगर करने योग्य प्रॉक्सी: वैश्विक (सभी ट्रैफ़िक), प्रति-प्रदाता (केवल एक प्रदाता), और प्रति-कनेक्शन/कुंजी -- **रंग-कोडित प्रॉक्सी बैज** - दृश्य संकेतक: 🟢 वैश्विक प्रॉक्सी, 🟡 प्रदाता प्रॉक्सी, 🔵 कनेक्शन प्रॉक्सी, हमेशा आईपी दिखाता है -- **प्रॉक्सी के माध्यम से OAuth टोकन एक्सचेंज** - OAuth प्रवाह भी प्रॉक्सी के माध्यम से चलता है, `unsupported_country_region_territory` को हल करता है -- **प्रॉक्सी के माध्यम से कनेक्शन परीक्षण** - कनेक्शन परीक्षण कॉन्फ़िगर प्रॉक्सी का उपयोग करते हैं (अब कोई प्रत्यक्ष बाईपास नहीं) -- **SOCKS5 समर्थन** - आउटबाउंड रूटिंग के लिए पूर्ण SOCKS5 प्रॉक्सी समर्थन -- **टीएलएस फिंगरप्रिंट स्पूफिंग** - बॉट डिटेक्शन को बायपास करने के लिए `wreq-js` के माध्यम से ब्राउज़र जैसा टीएलएस फिंगरप्रिंट +- **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
-` prefix
+- **Free-Only Combos** — Chain `gc/gemini-3-flash → 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
🆓 4. "मैं कोडिंग के लिए AI का उपयोग करना चाहता हूं लेकिन मेरे पास पैसे नहीं हैं"
+🆓 4. "I want to use AI for coding but I have no money"
-हर कोई AI सदस्यता के लिए $20-200/माह का भुगतान नहीं कर सकता। छात्रों, उभरते देशों के डेवलपर्स, शौकीनों और फ्रीलांसरों को शून्य लागत पर गुणवत्ता वाले मॉडल तक पहुंच की आवश्यकता है। +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. -**ओम्नीरूट इसे कैसे हल करता है:** +**How OmniRoute solves it:** -- **फ्री टियर प्रोवाइडर बिल्ट-इन** - 100% फ्री प्रदाताओं के लिए मूल समर्थन: आईफ्लो (8 असीमित मॉडल), क्वेन (3 असीमित मॉडल), किरो (क्लाउड मुफ्त में), जेमिनी सीएलआई (180K/माह मुफ्त) -- **केवल-निःशुल्क कॉम्बो** - चेन `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = शून्य डाउनटाइम के साथ $0/माह -- **एनवीडिया एनआईएम फ्री क्रेडिट** - 1000 मुफ्त क्रेडिट एकीकृत -- **लागत अनुकूलित रणनीति** - रूटिंग रणनीति जो स्वचालित रूप से सबसे सस्ते उपलब्ध प्रदाता को चुनती है +- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free) +- **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/
-
🔒 5. "मुझे अपने AI गेटवे को अनधिकृत पहुंच से सुरक्षित रखने की आवश्यकता है"
+🔒 5. "I need to protect my AI gateway from unauthorized access"
-नेटवर्क (LAN, VPS, Docker) में AI गेटवे को उजागर करते समय, पते वाला कोई भी व्यक्ति डेवलपर के टोकन/कोटा का उपभोग कर सकता है। सुरक्षा के बिना, एपीआई दुरुपयोग, त्वरित इंजेक्शन और दुरुपयोग के प्रति संवेदनशील हैं। +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. -**ओम्नीरूट इसे कैसे हल करता है:** +**How OmniRoute solves it:** -- **एपीआई कुंजी प्रबंधन** - एक समर्पित `/dashboard/api-manager` पेज के साथ प्रति प्रदाता जेनरेशन, रोटेशन और स्कोपिंग -- **मॉडल-स्तरीय अनुमतियाँ** - एपीआई कुंजियों को विशिष्ट मॉडलों (`openai/*`, वाइल्डकार्ड पैटर्न) तक सीमित करें, सभी को अनुमति दें/प्रतिबंधित टॉगल के साथ -- **एपीआई एंडपॉइंट सुरक्षा** - `/v1/models` के लिए एक कुंजी की आवश्यकता है और लिस्टिंग से विशिष्ट प्रदाताओं को ब्लॉक करें -- **ऑथ गार्ड + सीएसआरएफ सुरक्षा** - सभी डैशबोर्ड रूट `withAuth` मिडलवेयर + सीएसआरएफ टोकन से सुरक्षित हैं -- **रेट लिमिटर** - कॉन्फ़िगर करने योग्य विंडो के साथ प्रति-आईपी दर सीमित करना -- **आईपी फ़िल्टरिंग** - अभिगम नियंत्रण के लिए अनुमति सूची/अवरुद्ध सूची -- **प्रॉम्प्ट इंजेक्शन गार्ड** - दुर्भावनापूर्ण प्रॉम्प्ट पैटर्न के विरुद्ध स्वच्छता -- **एईएस-256-जीसीएम एन्क्रिप्शन** - क्रेडेंशियल आराम से एन्क्रिप्ट किए गए +- **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. "मेरा प्रदाता बंद हो गया और मैंने अपना कोडिंग प्रवाह खो दिया"
+🛑 6. "My provider went down and I lost my coding flow"
-एआई प्रदाता अस्थिर हो सकते हैं, 5xx त्रुटियाँ लौटा सकते हैं, या अस्थायी दर सीमा तक पहुँच सकते हैं। यदि कोई डेवलपर किसी एकल प्रदाता पर निर्भर करता है, तो वे बाधित हो जाते हैं। सर्किट ब्रेकर के बिना, बार-बार पुनः प्रयास करने से एप्लिकेशन क्रैश हो सकता है। +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:** -- **सर्किट ब्रेकर प्रति-प्रदाता** - कॉन्फ़िगर करने योग्य थ्रेसहोल्ड और कूलडाउन के साथ ऑटो-खुला/बंद (बंद/खुला/आधा-खुला) -- **एक्सपोनेंशियल बैकऑफ़** - प्रगतिशील पुनः प्रयास में देरी -- **एंटी-थंडरिंग हर्ड** - म्यूटेक्स + समवर्ती रिट्री तूफानों के खिलाफ सेमाफोर सुरक्षा -- **कॉम्बो फ़ॉलबैक चेन** - यदि प्राथमिक प्रदाता विफल हो जाता है, तो बिना किसी हस्तक्षेप के स्वचालित रूप से चेन से गिर जाता है -- **कॉम्बो सर्किट ब्रेकर** - कॉम्बो श्रृंखला के भीतर विफल प्रदाताओं को स्वचालित रूप से अक्षम करता है -- **स्वास्थ्य डैशबोर्ड** - अपटाइम मॉनिटरिंग, सर्किट ब्रेकर स्थिति, लॉकआउट, कैश आँकड़े, p50/p95/p99 विलंबता +- **Circuit Breaker per-model** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks +- **Exponential Backoff** — Progressive retry delays +- **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 +- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain +- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
-
🔧 7. "प्रत्येक AI उपकरण को कॉन्फ़िगर करना कठिन और दोहराव वाला है"
+🔧 7. "Configuring each AI tool is tedious and repetitive"
-डेवलपर्स कर्सर, क्लाउड कोड, कोडेक्स सीएलआई, ओपनक्लाव, जेमिनी सीएलआई, किलो कोड का उपयोग करते हैं... प्रत्येक टूल को एक अलग कॉन्फ़िगरेशन (एपीआई एंडपॉइंट, कुंजी, मॉडल) की आवश्यकता होती है। प्रदाताओं या मॉडलों को स्विच करते समय पुन: कॉन्फ़िगर करना समय की बर्बादी है। +Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time. -**ओम्नीरूट इसे कैसे हल करता है:** +**How OmniRoute solves it:** -- **सीएलआई टूल्स डैशबोर्ड** - क्लाउड कोड, कोडेक्स सीएलआई, ओपनक्लाव, किलो कोड, एंटीग्रेविटी, क्लाइन के लिए एक-क्लिक सेटअप वाला समर्पित पृष्ठ -- **GitHub Copilot कॉन्फिग जेनरेटर** - बल्क मॉडल चयन के साथ VS कोड के लिए `chatLanguageModels.json` जेनरेट करता है -- **ऑनबोर्डिंग विज़ार्ड** - पहली बार उपयोगकर्ताओं के लिए निर्देशित 4-चरणीय सेटअप -- **एक समापन बिंदु, सभी मॉडल** - `http://localhost:20128/v1` को एक बार कॉन्फ़िगर करें, 36+ प्रदाताओं तक पहुंचें +- **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 67+ providers
-
🔑 8. "एकाधिक प्रदाताओं से OAuth टोकन प्रबंधित करना नरक है"
+🔑 8. "Managing OAuth tokens from multiple providers is hell"
-क्लाउड कोड, कोडेक्स, जेमिनी सीएलआई, कोपायलट - सभी समाप्त होने वाले टोकन के साथ OAuth 2.0 का उपयोग करते हैं। डेवलपर्स को लगातार पुन: प्रमाणित करने, `client_secret is missing`, `redirect_uri_mismatch` और दूरस्थ सर्वर पर विफलताओं से निपटने की आवश्यकता है। LAN/VPS पर OAuth विशेष रूप से समस्याग्रस्त है। +Claude Code, Codex, Gemini CLI, 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:** -- **ऑटो टोकन रिफ्रेश** - OAuth टोकन समाप्ति से पहले पृष्ठभूमि में रिफ्रेश होते हैं -- **OAuth 2.0 (PKCE) बिल्ट-इन** - क्लाउड कोड, कोडेक्स, जेमिनी सीएलआई, कोपायलट, किरो, क्वेन, आईफ्लो के लिए स्वचालित प्रवाह -- **मल्टी-अकाउंट OAuth** - JWT/ID टोकन निष्कर्षण के माध्यम से प्रति प्रदाता एकाधिक खाते -- **OAuth LAN/रिमोट फिक्स** - `redirect_uri` के लिए निजी आईपी डिटेक्शन + रिमोट सर्वर के लिए मैनुअल यूआरएल मोड -- **Nginx के पीछे OAuth** - रिवर्स प्रॉक्सी संगतता के लिए `window.location.origin` का उपयोग करता है -- **दूरस्थ OAuth मार्गदर्शिका** — VPS/Docker पर Google क्लाउड क्रेडेंशियल के लिए चरण-दर-चरण मार्गदर्शिका +- **Auto Token Refresh** — OAuth tokens refresh in background before expiration +- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow +- **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. "मुझे नहीं पता कि मैं कितना और कहां खर्च कर रहा हूं"
+📊 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. "मैं AI कॉल में त्रुटियों और समस्याओं का निदान नहीं कर सकता"
+🐛 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:** -- **एकीकृत लॉग डैशबोर्ड** - 4 टैब: अनुरोध लॉग, प्रॉक्सी लॉग, ऑडिट लॉग, कंसोल -- **कंसोल लॉग व्यूअर** - रंग-कोडित स्तरों, ऑटो-स्क्रॉल, खोज, फ़िल्टर के साथ वास्तविक समय टर्मिनल-शैली व्यूअर -- **SQLite प्रॉक्सी लॉग** - लगातार लॉग जो सर्वर पुनरारंभ होने से बचे रहते हैं -- **अनुवादक खेल का मैदान** - 4 डिबगिंग मोड: खेल का मैदान (प्रारूप अनुवाद), चैट टेस्टर (राउंड-ट्रिप), टेस्ट बेंच (बैच), लाइव मॉनिटर (वास्तविक समय) -- **अनुरोध टेलीमेट्री** - p50/p95/p99 विलंबता + X-अनुरोध-आईडी ट्रेसिंग -- **रोटेशन के साथ फ़ाइल-आधारित लॉगिंग** - कंसोल इंटरसेप्टर आकार-आधारित रोटेशन के साथ JSON लॉग में सब कुछ कैप्चर करता है +- **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 Proxy Logs** — Persistent logs that survive server restarts +- **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 Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation +- **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. "गेटवे की तैनाती और रखरखाव जटिल है"
+🏗️ 11. "Deploying and maintaining the gateway is complex"
-विभिन्न वातावरणों (स्थानीय, वीपीएस, डॉकर, क्लाउड) में एआई प्रॉक्सी को स्थापित करना, कॉन्फ़िगर करना और बनाए रखना श्रम-गहन है। हार्डकोडेड पथ, निर्देशिकाओं पर `EACCES`, पोर्ट विरोध और क्रॉस-प्लेटफ़ॉर्म बिल्ड जैसी समस्याएं घर्षण बढ़ाती हैं। +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 ग्लोबल इंस्टाल** — `npm install -g omniroute && omniroute` — हो गया -- **डॉकर मल्टी-प्लेटफ़ॉर्म** - AMD64 + ARM64 नेटिव (Apple सिलिकॉन, AWS ग्रेविटॉन, रास्पबेरी पाई) -- **डॉकर कंपोज प्रोफाइल** - `base` (कोई CLI उपकरण नहीं) और `cli` (क्लाउड कोड, कोडेक्स, ओपनक्लाव के साथ) -- **इलेक्ट्रॉन डेस्कटॉप ऐप** - सिस्टम ट्रे, ऑटो-स्टार्ट, ऑफ़लाइन मोड के साथ विंडोज/मैकओएस/लिनक्स के लिए मूल ऐप -- **स्प्लिट-पोर्ट मोड** - उन्नत परिदृश्यों के लिए अलग-अलग पोर्ट पर एपीआई और डैशबोर्ड (रिवर्स प्रॉक्सी, कंटेनर नेटवर्किंग) -- **क्लाउड सिंक** - क्लाउडफ्लेयर वर्कर्स के माध्यम से सभी डिवाइसों में कॉन्फिग सिंक्रोनाइजेशन -- **डीबी बैकअप** - सभी सेटिंग्स का स्वचालित बैकअप, पुनर्स्थापना, निर्यात और आयात +- **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
-
🌍 12. "इंटरफ़ेस केवल अंग्रेजी है और मेरी टीम अंग्रेजी नहीं बोलती है"
+🌍 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:** -- **डैशबोर्ड i18n - 30 भाषाएँ** - अरबी, बल्गेरियाई, डेनिश, जर्मन, स्पेनिश, फिनिश, फ्रेंच, हिब्रू, हिंदी, हंगेरियन, इंडोनेशियाई, इतालवी, जापानी, कोरियाई, मलय, डच, नॉर्वेजियन, पोलिश, पुर्तगाली (पीटी/बीआर), रोमानियाई, रूसी, स्लोवाक, स्वीडिश, थाई, यूक्रेनी, वियतनामी, चीनी, फिलिपिनो, अंग्रेजी सहित सभी 500+ कुंजियाँ अनुवादित -- **आरटीएल समर्थन** - अरबी और हिब्रू के लिए दाएं से बाएं समर्थन -- **बहु-भाषा रीडमी** - 30 पूर्ण दस्तावेज़ीकरण अनुवाद -- **भाषा चयनकर्ता** - वास्तविक समय स्विचिंग के लिए हेडर में ग्लोब आइकन +- **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. "मुझे चैट से अधिक की आवश्यकता है - मुझे एम्बेडिंग, चित्र, ऑडियो की आवश्यकता है"
+🔄 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:** -- **एम्बेडिंग्स** - 6 प्रदाताओं और 9+ मॉडलों के साथ `/v1/embeddings` -- **इमेज जेनरेशन** - `/v1/images/generations` 10 प्रदाताओं और 20+ मॉडलों के साथ (ओपनएआई, एक्सएआई, टुगेदर, फायरवर्क्स, नेबियस, हाइपरबोलिक, नैनोबनाना, एंटीग्रेविटी, एसडी वेबयूआई, कॉम्फीयूआई) -- **टेक्स्ट-टू-वीडियो** — `/v1/videos/generations` — कॉम्फीयूआई (एनिमेटडिफ, एसवीडी) और एसडी वेबयूआई -- **टेक्स्ट-टू-म्यूजिक** — `/v1/music/generations` — कॉम्फीयूआई (स्थिर ऑडियो ओपन, म्यूजिकजेन) -- **ऑडियो ट्रांसक्रिप्शन** - `/v1/audio/transcriptions` - व्हिस्पर + एनवीडिया एनआईएम, हगिंगफेस, क्वेन3 -- **टेक्स्ट-टू-स्पीच** - `/v1/audio/speech` - इलेवनलैब्स, एनवीडिया एनआईएम, हगिंगफेस, कोक्वी, टोरटोइज़, क्वेन3, + मौजूदा प्रदाता -- **संयम** — `/v1/moderations` — सामग्री सुरक्षा जांच -- **पुनर्रैंकिंग** — `/v1/rerank` — दस्तावेज़ प्रासंगिकता पुनर्रैंकिंग -- **प्रतिक्रिया एपीआई** - कोडेक्स के लिए पूर्ण `/v1/responses` समर्थन +- **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. "मेरे पास सभी मॉडलों की गुणवत्ता का परीक्षण और तुलना करने का कोई तरीका नहीं है"
+🧪 14. "I have no way to test and compare quality across models"
-डेवलपर्स जानना चाहते हैं कि उनके उपयोग के मामले में कौन सा मॉडल सबसे अच्छा है - कोड, अनुवाद, तर्क - लेकिन मैन्युअल रूप से तुलना करना धीमा है। कोई एकीकृत eval उपकरण मौजूद नहीं है। +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:** -- **एलएलएम मूल्यांकन** - अभिवादन, गणित, भूगोल, कोड जनरेशन, JSON अनुपालन, अनुवाद, मार्कडाउन, सुरक्षा इनकार को कवर करने वाले 10 प्री-लोडेड मामलों के साथ गोल्डन सेट परीक्षण -- **4 मैच रणनीतियाँ** - `exact`, `contains`, `regex`, `custom` (JS फ़ंक्शन) -- **अनुवादक खेल का मैदान परीक्षण बेंच** - एकाधिक इनपुट और अपेक्षित आउटपुट, क्रॉस-प्रदाता तुलना के साथ बैच परीक्षण -- **चैट परीक्षक** - दृश्य प्रतिक्रिया प्रतिपादन के साथ पूर्ण राउंड-ट्रिप -- **लाइव मॉनिटर** - प्रॉक्सी के माध्यम से बहने वाले सभी अनुरोधों की वास्तविक समय स्ट्रीम +- **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. "मुझे प्रदर्शन खोए बिना स्केल करने की आवश्यकता है"
+📈 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:** -- **सिमेंटिक कैश** - दो-स्तरीय कैश (हस्ताक्षर + सिमेंटिक) लागत और विलंबता को कम करता है -- **अनुरोध Idempotency** - समान अनुरोधों के लिए 5s डिडुप्लीकेशन विंडो -- **दर सीमा का पता लगाना** - प्रति-प्रदाता आरपीएम, न्यूनतम अंतर, और अधिकतम समवर्ती ट्रैकिंग -- **संपादन योग्य दर सीमाएँ** — सेटिंग्स में कॉन्फ़िगर करने योग्य डिफ़ॉल्ट → दृढ़ता के साथ लचीलापन -- **एपीआई कुंजी सत्यापन कैश** - उत्पादन प्रदर्शन के लिए 3-स्तरीय कैश -- **टेलीमेट्री के साथ स्वास्थ्य डैशबोर्ड** — p50/p95/p99 विलंबता, कैश आँकड़े, अपटाइम +- **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 +- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence +- **API Key Validation Cache** — 3-tier cache for production performance +- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
-
🤖 16. "मैं विश्व स्तर पर मॉडल व्यवहार को नियंत्रित करना चाहता हूं"
+🤖 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:** -- **सिस्टम प्रॉम्प्ट इंजेक्शन** — ग्लोबल प्रॉम्प्ट सभी अनुरोधों पर लागू होता है -- **सोच बजट सत्यापन** - प्रति अनुरोध तर्क टोकन आवंटन नियंत्रण (पासथ्रू, ऑटो, कस्टम, अनुकूली) -- **6 रूटिंग रणनीतियाँ** - वैश्विक रणनीतियाँ जो यह निर्धारित करती हैं कि अनुरोध कैसे वितरित किए जाते हैं -- **वाइल्डकार्ड राउटर** - `provider/*` पैटर्न किसी भी प्रदाता को गतिशील रूप से रूट करता है -- **कॉम्बो सक्षम/अक्षम टॉगल** — कॉम्बो को सीधे डैशबोर्ड से टॉगल करें -- **प्रदाता टॉगल** — एक क्लिक से प्रदाता के लिए सभी कनेक्शन सक्षम/अक्षम करें -- **अवरुद्ध प्रदाता** - `/v1/models` सूची से विशिष्ट प्रदाताओं को बाहर करें +- **System Prompt Injection** — Global prompt applied to all requests +- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive) +- **6 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 +- **Provider Toggle** — Enable/disable all connections for a provider with one click +- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
-
🧰 17. "मुझे प्रथम श्रेणी उत्पाद क्षमताओं के रूप में MCP टूल की आवश्यकता है"
+🧰 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:** -- एमसीपी डैशबोर्ड नेविगेशन और एंडपॉइंट प्रोटोकॉल टैब में दिखाई देता है -- प्रक्रिया, उपकरण, कार्यक्षेत्र और ऑडिट के साथ समर्पित एमसीपी प्रबंधन पृष्ठ -- `omniroute --mcp` और क्लाइंट ऑनबोर्डिंग के लिए बिल्ट-इन क्विक-स्टार्ट +- 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. "मुझे सिंक + स्ट्रीम कार्य पथों के साथ A2A ऑर्केस्ट्रेशन की आवश्यकता है"
+🧠 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 एंडपॉइंट (`POST /a2a`) `message/send` और `message/stream` के साथ -- टर्मिनल राज्य प्रसार के साथ एसएसई स्ट्रीमिंग -- `tasks/get` और `tasks/cancel` के लिए कार्य जीवनचक्र एपीआई +- 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. "मुझे वास्तविक MCP प्रक्रिया स्वास्थ्य की आवश्यकता है, अनुमानित स्थिति की नहीं"
+🛰️ 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. "मुझे ऑडिटेबल MCP टूल निष्पादन की आवश्यकता है"
+📋 20. "I need auditable MCP tool execution"
-जब उपकरण कॉन्फ़िगरेशन को बदलते हैं या ऑप्स क्रियाओं को ट्रिगर करते हैं, तो टीमों को फोरेंसिक ट्रैसेबिलिटी की आवश्यकता होती है। +When tools mutate config or trigger ops actions, teams need forensic traceability. -**ओम्नीरूट इसे कैसे हल करता है:** +**How OmniRoute solves it:** -- MCP टूल कॉल के लिए SQLite समर्थित ऑडिट लॉगिंग -- टूल, सफलता/असफलता, एपीआई कुंजी और पेजिनेशन द्वारा फ़िल्टर -- डैशबोर्ड ऑडिट टेबल + स्वचालन के लिए आँकड़े समापन बिंदु +- 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. "मुझे प्रति एकीकरण के लिए स्कोप्ड MCP अनुमतियों की आवश्यकता है"
+🔐 21. "I need scoped MCP permissions per integration"
-विभिन्न ग्राहकों को टूल श्रेणियों तक कम से कम विशेषाधिकार प्राप्त होना चाहिए। +Different clients should have least-privilege access to tool categories. -**ओम्नीरूट इसे कैसे हल करता है:** +**How OmniRoute solves it:** -- नियंत्रित टूल एक्सेस के लिए 9 दानेदार एमसीपी स्कोप -- एमसीपी प्रबंधन यूआई में दायरा प्रवर्तन और दृश्यता -- परिचालन टूलींग के लिए सुरक्षित डिफ़ॉल्ट मुद्रा +- 9 granular MCP scopes for controlled tool access +- Scope enforcement and visibility in MCP management UI +- Safe default posture for operational tooling
-
⚙️ 22. "मुझे पुनः तैनाती के बिना परिचालन नियंत्रण की आवश्यकता है"
+⚙️ 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 +- Apply resilience profiles from pre-defined policy packs +- Reset circuit breaker state from the same operations panel
-
🔄 23. "मुझे लाइव A2A कार्य जीवनचक्र दृश्यता और रद्दीकरण की आवश्यकता है"
+🔄 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. "मुझे A2A लोड के लिए सक्रिय स्ट्रीम मेट्रिक्स की आवश्यकता है"
+🌊 24. "I need active stream metrics for A2A load"
-स्ट्रीमिंग वर्कफ़्लो के लिए समवर्ती और लाइव कनेक्शन में परिचालन अंतर्दृष्टि की आवश्यकता होती है। +Streaming workflows require operational insight into concurrency and live connections. -**ओम्नीरूट इसे कैसे हल करता है:** +**How OmniRoute solves it:** -- सक्रिय स्ट्रीम काउंटर A2A स्थिति में एकीकृत -- अंतिम कार्य टाइमस्टैम्प और प्रति-राज्य गणना -- वास्तविक समय ऑप्स निगरानी के लिए A2A डैशबोर्ड कार्ड +- Active stream counters integrated into A2A status +- Last task timestamp and per-state counts +- A2A dashboard cards for real-time ops monitoring
-
🪪 25. "मुझे ग्राहकों के लिए मानक एजेंट खोज की आवश्यकता है"
+🪪 25. "I need standard agent discovery for clients"
-बाहरी ग्राहकों और ऑर्केस्ट्रेटर्स को ऑनबोर्डिंग के लिए मशीन-पठनीय मेटाडेटा की आवश्यकता होती है। +External clients and orchestrators need machine-readable metadata for onboarding. -**ओम्नीरूट इसे कैसे हल करता है:** +**How OmniRoute solves it:** -- एजेंट कार्ड `/.well-known/agent.json` पर प्रदर्शित हुआ -- प्रबंधन यूआई में दिखाई गई क्षमताएं और कौशल -- A2A स्थिति API में स्वचालन के लिए खोज मेटाडेटा शामिल है +- Agent Card exposed at `/.well-known/agent.json` +- Capabilities and skills shown in management UI +- A2A status API includes discovery metadata for automation
-
🧭 26. "मुझे उत्पाद UX में प्रोटोकॉल खोज योग्यता की आवश्यकता है"
+🧭 26. "I need protocol discoverability in the product UX"
-यदि उपयोगकर्ता प्रोटोकॉल सतहों की खोज नहीं कर पाते हैं, तो अपनाने और समर्थन की गुणवत्ता में गिरावट आती है। +If users cannot discover protocol surfaces, adoption and support quality drop. -**ओम्नीरूट इसे कैसे हल करता है:** +**How OmniRoute solves it:** -- MCP और A2A के लिए साइडबार प्रविष्टियाँ -- समापन बिंदु पृष्ठ प्रोटोकॉल टैब त्वरित-प्रारंभ और स्थिति के साथ -- सिंहावलोकन से लेकर समर्पित प्रबंधन डैशबोर्ड तक के लिंक +- 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. "मुझे वास्तविक ग्राहकों के साथ एंड-टू-एंड प्रोटोकॉल सत्यापन की आवश्यकता है"
+🧪 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 सुइट जो ऐप को बूट करता है और वास्तविक MCP SDK क्लाइंट ट्रांसपोर्ट का उपयोग करता है -- A2A क्लाइंट खोज, भेजने, स्ट्रीम करने, प्राप्त करने और प्रवाह को रद्द करने के लिए परीक्षण करता है -- एमसीपी ऑडिट और ए2ए कार्य एपीआई के खिलाफ दावों की क्रॉस-चेक करें +- 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. "मुझे सभी इंटरफेस में एकीकृत अवलोकन की आवश्यकता है"
+📡 28. "I need unified observability across all interfaces"
-प्रोटोकॉल द्वारा अवलोकनशीलता को विभाजित करने से ब्लाइंड स्पॉट और लंबा एमटीटीआर बनता है। +Splitting observability by protocol creates blind spots and longer MTTR. -**ओम्नीरूट इसे कैसे हल करता है:** +**How OmniRoute solves it:** -- एक उत्पाद में एकीकृत डैशबोर्ड/लॉग/एनालिटिक्स -- स्वास्थ्य + ऑडिट + ओपनएआई, एमसीपी और ए2ए परतों में टेलीमेट्री अनुरोध -- स्थिति और स्वचालन के लिए परिचालन एपीआई +- Unified dashboards/logs/analytics in one product +- Health + audit + request telemetry across OpenAI, MCP, and A2A layers +- Operational APIs for status and automation
-
💼 29. "मुझे प्रॉक्सी + टूल + एजेंट ऑर्केस्ट्रेशन के लिए एक रनटाइम की आवश्यकता है"
+💼 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-संगत प्रॉक्सी, MCP सर्वर और A2A सर्वर एक स्टैक में -- साझा प्रमाणीकरण, लचीलापन, डेटा भंडारण और अवलोकन क्षमता -- सभी संपर्क सतहों पर सुसंगत नीति मॉडल +- 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
-
-### उदाहरण प्लेबुक (एकीकृत उपयोग के मामले)
+### Example Playbooks (Integrated Use Cases)
-**प्लेबुक ए: सशुल्क सदस्यता + सस्ता बैकअप अधिकतम करें**
+**Playbook A: Maximize paid subscription + cheap backup**
```txt
Combo: "maximize-claude"
@@ -606,7 +694,7 @@ Monthly cost: $20 + small backup spend
Outcome: higher quality, near-zero interruption
```
-**प्लेबुक बी: शून्य-लागत कोडिंग स्टैक**
+**Playbook B: Zero-cost coding stack**
```txt
Combo: "free-forever"
@@ -618,7 +706,7 @@ Monthly cost: $0
Outcome: stable free coding workflow
```
-**प्लेबुक सी: 24/7 हमेशा चालू फ़ॉलबैक श्रृंखला**
+**Playbook C: 24/7 always-on fallback chain**
```txt
Combo: "always-on"
@@ -631,60 +719,132 @@ Combo: "always-on"
Outcome: deep fallback depth for deadline-critical workloads
```
-**प्लेबुक डी: एजेंट एमसीपी + ए2ए के साथ काम करता है**
+**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/mcp and /dashboard/a2a
-4) Control incidents with resilience profile + task cancellation
+3) Observe via /dashboard/endpoint (MCP and A2A tabs)
+4) Toggle services via inline status controls
```
---
-## ⚡ त्वरित शुरुआत
+## 🆓 Start Free — Zero Configuration Cost
-**1. विश्व स्तर पर स्थापित करें:**
+> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.
-🎉 डैशबोर्ड `http://localhost:20128` पर खुलता है
+| Step | Action | Providers Unlocked |
+| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |
+| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 — **unlimited** |
+| 2 | Connect **iFlow** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |
+| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |
+| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |
+| 5 | `/dashboard/combos` → **Free Stack ($0)** template | Round-robin all free providers automatically |
-| आदेश | विवरण |
-| ----------------------- | ----------------------------------------- |
-| `omniroute` | सर्वर प्रारंभ करें (डिफ़ॉल्ट पोर्ट 20128) |
-| `omniroute --port 3000` | कस्टम पोर्ट का उपयोग करें |
-| `omniroute --no-open` | ब्राउज़र को स्वतः न खोलें |
-| `omniroute --help` | सहायता दिखाएँ |
+**Point any IDE/CLI to:** `http://localhost:20128/v1` · API Key: `any-string` · Done.
-**2. एक मुफ़्त प्रदाता से जुड़ें:**
+> **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).
-डैशबोर्ड → प्रदाता → कनेक्ट **क्लाउड कोड** या **एंटीग्रेविटी** → OAuth लॉगिन → हो गया!
+## त्वरित प्रारंभ
-**3. अपने सीएलआई टूल में उपयोग करें:**
+### 1) Install and run
-```
-Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Settings:
- Endpoint: http://localhost:20128/v1
- API Key: [copy from dashboard]
- Model: if/kimi-k2-thinking
+```bash
+npm install -g omniroute
+omniroute
```
-**बस!** मुफ़्त AI मॉडल के साथ कोडिंग शुरू करें।
+> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:
+>
+> ```bash
+> pnpm install -g omniroute
+> pnpm approve-builds -g # Select all packages → approve
+> omniroute
+> ```
-**वैकल्पिक - स्रोत से चलाएँ:**
+Dashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.
+
+| 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) 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
+
+```txt
+Base URL: http://localhost:20128/v1
+API Key: [copy from Endpoint page]
+Model: if/kimi-k2-thinking (or any provider/model prefix)
+```
+
+Works with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.
+
+### 4) Enable and validate protocols (v2.0)
+
+**MCP (for tool-driven operations):**
+
+```bash
+omniroute --mcp
+```
+
+Then connect your MCP client over `stdio` and test tools like:
+
+- `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 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
+PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev
```
---
-## 🐳 डॉकर
+## 🐳 Docker
-ओमनीरूट [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute) पर सार्वजनिक डॉकर छवि के रूप में उपलब्ध है।
+OmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
-**त्वरित दौड़:**
+**Quick run:**
```bash
docker run -d \
@@ -695,345 +855,790 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**पर्यावरण फ़ाइल के साथ:**
+**With environment file:**
-**डॉकर कंपोज़ का उपयोग करना:**
+```bash
+# Copy and edit .env first
+cp .env.example .env
-| छवि | टैग | आकार | विवरण |
-| ------------------------ | -------- | -------- | ------------------- |
-| `diegosouzapw/omniroute` | `latest` | ~250एमबी | नवीनतम स्थिर रिलीज़ |
-| `diegosouzapw/omniroute` | `1.0.3` | ~250एमबी | वर्तमान संस्करण |
+docker run -d \
+ --name omniroute \
+ --restart unless-stopped \
+ --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.
+- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.
+- 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` | `1.0.3` | ~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
+### त्वरित प्रारंभ
+
```bash
-npm run electron:dev # Development mode
+# 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)
+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
-| टियर | प्रदाता | लागत | कोटा रीसेट | के लिए सर्वश्रेष्ठ |
-| ----------------- | ------------------- | ------------------------- | -------------------- | ------------------------ |
-| **💳 सदस्यता** | क्लाउड कोड (प्रो) | $20/माह | 5 घंटे + साप्ताहिक | पहले ही सदस्यता ले ली है |
-| | कोडेक्स (प्लस/प्रो) | $20-200/महीना | 5 घंटे + साप्ताहिक | OpenAI उपयोगकर्ता |
-| | जेमिनी सीएलआई | **मुफ़्त** | 180K/माह + 1K/दिन | सब लोग! |
-| | गिटहब कोपायलट | $10-19/माह | मासिक | GitHub उपयोगकर्ता |
-| **🔑एपीआई कुंजी** | एनवीडिया एनआईएम | **मुफ़्त** (1000 क्रेडिट) | एक बार | निःशुल्क स्तरीय परीक्षण |
-| | डीपसीक | भुगतान-प्रति-उपयोग | कोई नहीं | सर्वोत्तम मूल्य/गुणवत्ता |
-| | ग्रोक | फ्री टियर + पेड | दर सीमित | अल्ट्रा-फास्ट अनुमान |
-| | एक्सएआई (ग्रोक) | भुगतान-प्रति-उपयोग | कोई नहीं | ग्रोक मॉडल |
-| | मिस्ट्रल | फ्री टियर + पेड | दर सीमित | यूरोपीय एआई |
-| | ओपनराउटर | भुगतान-प्रति-उपयोग | कोई नहीं | 100+ मॉडल |
-| **💰सस्ता** | जीएलएम-4.7 | $0.6/1 मिलियन | प्रतिदिन सुबह 10 बजे | बजट बैकअप |
-| | मिनीमैक्स एम2.1 | $0.2/1 मिलियन | 5 घंटे की रोलिंग | सबसे सस्ता विकल्प |
-| | किमी K2 | $9/महीना फ्लैट | 10एम टोकन/माह | अनुमानित लागत |
-| **🆓 मुफ़्त** | आईफ्लो | $0 | असीमित | 8 मॉडल निःशुल्क |
-| | क्वेन | $0 | असीमित | 3 मॉडल मुफ़्त |
-| | किरो | $0 | असीमित | क्लाउड मुक्त |
+| 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 |
+| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |
+| | 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** | iFlow | **$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 |
-**💡 प्रो टिप:** जेमिनी सीएलआई (180 हजार निःशुल्क/माह) + आईफ्लो (असीमित निःशुल्क) कॉम्बो = $0 लागत से शुरू करें!
+> 🆕 **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
+iFlow (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
-| फ़ीचर | यह क्या करता है |
-| --------------------------------- | ------------------------------------------------------------------------------------ |
-| 🎯 **स्मार्ट 4-टियर फ़ॉलबैक** | ऑटो-रूट: सदस्यता → एपीआई कुंजी → सस्ता → मुफ़्त |
-| 📊 **वास्तविक समय कोटा ट्रैकिंग** | लाइव टोकन गिनती + प्रति प्रदाता रीसेट उलटी गिनती |
-| 🔄 **प्रारूप अनुवाद** | OpenAI ↔ क्लाउड ↔ जेमिनी ↔ कर्सर ↔ किरो सीमलेस + रिस्पॉन्स सैनिटाइजेशन |
-| 👥 **मल्टी-अकाउंट सपोर्ट** | बुद्धिमान चयन के साथ प्रति प्रदाता एकाधिक खाते |
-| 🔄 **ऑटो टोकन रिफ्रेश** | OAuth टोकन पुनः प्रयास के साथ स्वचालित रूप से ताज़ा हो जाते हैं |
-| 🎨 **कस्टम कॉम्बो** | 6 रणनीतियाँ: पहले भरें, राउंड-रॉबिन, पी2सी, यादृच्छिक, कम से कम उपयोग, लागत-अनुकूलित |
-| 🧩 **कस्टम मॉडल** | किसी भी प्रदाता से कोई भी मॉडल आईडी जोड़ें |
-| 🌐 **वाइल्डकार्ड राउटर** | `provider/*` पैटर्न को गतिशील रूप से किसी भी प्रदाता तक रूट करें |
-| 🧠 **सोच बजट** | तर्क मॉडल के लिए पासथ्रू, ऑटो, कस्टम और अनुकूली मोड |
-| 🔀 **Model Aliases** | Auto-forward deprecated model IDs to current replacements (built-in + custom) |
-| ⚡ **Background Degradation** | Auto-route background tasks (titles, summaries) to cheaper models |
-| 💬 **सिस्टम प्रॉम्प्ट इंजेक्शन** | ग्लोबल सिस्टम प्रॉम्प्ट सभी अनुरोधों पर लागू किया गया |
-| 📄 **प्रतिक्रियाएं एपीआई** | कोडेक्स के लिए पूर्ण ओपनएआई रिस्पॉन्स एपीआई (`/v1/responses`) समर्थन |
+> 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)
-| फ़ीचर | यह क्या करता है |
-| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 🖼️ **छवि निर्माण** | `/v1/images/generations` - 4 प्रदाता, 9+ मॉडल |
-| 📐 **एंबेडिंग** | `/v1/embeddings` — 6 प्रदाता, 9+ मॉडल |
-| 🎤 **ऑडियो ट्रांस्क्रिप्शन** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |
-| 🔊 **टेक्स्ट-टू-स्पीच** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) |
-| 🛡️ **संयम** | `/v1/moderations` — सामग्री सुरक्षा जांच |
-| 🔀 **पुनर्रैंकिंग** | `/v1/rerank` — दस्तावेज़ प्रासंगिकता पुनर्रैंकिंग |
+| 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 |
-### 🛡️ लचीलापन और सुरक्षा
+### 🟢 IFLOW MODELS (Free OAuth — No Credit Card)
-| फ़ीचर | यह क्या करता है |
-| ------------------------------------- | ---------------------------------------------------------------------------- |
-| 🔌 **सर्किट ब्रेकर** | कॉन्फ़िगर करने योग्य थ्रेशोल्ड के साथ प्रति-प्रदाता स्वतः खोलें/बंद करें |
-| 🛡️ **एंटी-थंडरिंग झुंड** | एपीआई कुंजी प्रदाताओं के लिए म्यूटेक्स + सेमाफोर दर-सीमा |
-| 🧠 **सिमेंटिक कैश** | दो-स्तरीय कैश (हस्ताक्षर + सिमेंटिक) लागत और विलंबता को कम करता है |
-| ⚡ **निष्क्रियता का अनुरोध** | डुप्लिकेट अनुरोधों के लिए 5s डिडअप विंडो |
-| 🔒 **टीएलएस फ़िंगरप्रिंट स्पूफ़िंग** | Wreq-js के माध्यम से टीएलएस-आधारित बॉट डिटेक्शन को बायपास करें |
-| 🌐 **आईपी फ़िल्टरिंग** | एपीआई अभिगम नियंत्रण के लिए अनुमति सूची/अवरुद्ध सूची |
-| 📊 **संपादन योग्य दर सीमाएँ** | सिस्टम स्तर पर कॉन्फ़िगर करने योग्य आरपीएम, न्यूनतम अंतर और अधिकतम समवर्ती |
-| 💾 **Rate Limit Persistence** | Learned limits survive restarts via SQLite with 60s debounce + 24h staleness |
-| 🔄 **Token Refresh Resilience** | Per-provider circuit breaker (5 fails→30min) + 30s timeout per attempt |
-| 🛡 **एपीआई एंडपॉइंट सुरक्षा** | `/models` समापन बिंदु के लिए ऑथेंटिक गेटिंग + प्रदाता अवरोधन |
-| 🔒 **प्रॉक्सी दृश्यता** | रंग-कोडित बैज: 🟢 वैश्विक, 🟡 प्रदाता, 🔵 आईपी डिस्प्ले के साथ प्रति-कनेक्शन |
-| 🌐 **3-स्तरीय प्रॉक्सी कॉन्फ़िगरेशन** | वैश्विक, प्रति-प्रदाता, या प्रति-कनेक्शन स्तर पर प्रॉक्सी कॉन्फ़िगर करें |
+| 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 |
-### 📊 अवलोकनशीलता और विश्लेषण
+### 🟡 QWEN MODELS (Device Code Auth)
-| फ़ीचर | यह क्या करता है |
-| -------------------------------- | ------------------------------------------------------------------------------ |
-| 📝 **लॉगिंग का अनुरोध** | पूर्ण अनुरोध/प्रतिक्रिया लॉग के साथ डिबग मोड |
-| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |
-| 💾 **SQLite प्रॉक्सी लॉग्स** | लगातार प्रॉक्सी लॉग सर्वर पुनरारंभ होने से बचे रहते हैं |
-| 📊 **एनालिटिक्स डैशबोर्ड** | रिचार्ज-संचालित: स्टेट कार्ड, मॉडल उपयोग चार्ट, प्रदाता तालिका |
-| 📈 **प्रगति ट्रैकिंग** | स्ट्रीमिंग के लिए ऑप्ट-इन एसएसई प्रगति कार्यक्रम |
-| 🧪 **एलएलएम मूल्यांकन** | 4 मैच रणनीतियों के साथ गोल्डन सेट परीक्षण |
-| 🔍 **टेलीमेट्री के लिए अनुरोध** | p50/p95/p99 विलंबता एकत्रीकरण + एक्स-अनुरोध-आईडी ट्रेसिंग |
-| 📋 **लॉग्स डैशबोर्ड** | एकीकृत 4-टैब पृष्ठ: अनुरोध लॉग, प्रॉक्सी लॉग, ऑडिट लॉग, कंसोल |
-| 🖥️ **कंसोल लॉग व्यूअर** | लेवल फ़िल्टर, खोज, ऑटो-स्क्रॉल के साथ रीयल-टाइम टर्मिनल-शैली व्यूअर |
-| 📑 **फ़ाइल-आधारित लॉगिंग** | कंसोल इंटरसेप्टर रोटेशन के साथ सभी आउटपुट को JSON लॉग फ़ाइल में कैप्चर करता है |
-| 🏥 **स्वास्थ्य डैशबोर्ड** | सिस्टम अपटाइम, सर्किट ब्रेकर स्थिति, लॉकआउट, कैश आँकड़े |
-| 💰 **लागत ट्रैकिंग** | बजट प्रबंधन + प्रति-मॉडल मूल्य निर्धारण विन्यास |
+| 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) |
-### ☁️ परिनियोजन और सिंक
+### 🟣 GEMINI CLI (Google OAuth)
-| फ़ीचर | यह क्या करता है |
-| ---------------------------- | ---------------------------------------------------------------------------- | ----------------------------- |
-| 💾 **क्लाउड सिंक** | क्लाउडफ्लेयर वर्कर्स के माध्यम से सभी डिवाइसों में कॉन्फिगरेशन सिंक करें |
-| 🌐 **कहीं भी तैनात करें** | लोकलहोस्ट, वीपीएस, डॉकर, क्लाउडफ्लेयर वर्कर्स |
-| 🔑 **एपीआई कुंजी प्रबंधन** | प्रति प्रदाता एपीआई कुंजियाँ उत्पन्न करें, घुमाएँ और स्कोप करें |
-| 🧙 **ऑनबोर्डिंग विज़ार्ड** | पहली बार उपयोगकर्ताओं के लिए 4-चरणीय निर्देशित सेटअप |
-| 🔧 **सीएलआई टूल्स डैशबोर्ड** | क्लाउड, कोडेक्स, क्लाइन, ओपनक्लॉ, किलो, एंटीग्रेविटी | को एक-क्लिक से कॉन्फ़िगर करें |
-| 🔄 **डीबी बैकअप** | सभी सेटिंग्स के लिए स्वचालित बैकअप, पुनर्स्थापना, निर्यात और आयात |
-| 🌐 **अंतर्राष्ट्रीयकरण** | नेक्स्ट-इंटल के साथ पूर्ण i18n - अंग्रेजी + पुर्तगाली (ब्राजील) समर्थन |
-| 🌍 **भाषा चयनकर्ता** | रीयल-टाइम भाषा स्विचिंग के लिए हेडर में ग्लोब आइकन (🇺🇸/🇧🇷) |
-| 🧹 **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 |
-| 📂 **कस्टम डेटा निर्देशिका** | `DATA_DIR` env var डिफ़ॉल्ट `~/.omniroute` संग्रहण पथ को ओवरराइड करने के लिए |
+| Model | Prefix | Limit | Rate Limit |
+| ------------------------ | ------ | --------------------------- | ------------- |
+| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |
+| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |
-🚀 30. "मुझे ग्लू-कोड फैलाव के बिना एजेंटिक वर्कफ़्लो भेजने की आवश्यकता है"
+🚀 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)📖 सुविधा विवरण
+### ⚫ NVIDIA NIM (Free API Key — build.nvidia.com) -### 🎯 स्मार्ट 4-टियर फ़ॉलबैक +| 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) -- प्रति प्रदाता टोकन खपत -- उलटी गिनती रीसेट करें (5 घंटे, दैनिक, साप्ताहिक) -- भुगतान किए गए स्तरों के लिए लागत अनुमान -- मासिक खर्च रिपोर्ट +| 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) -- **ओपनएआई** ↔ **क्लाउड** ↔ **मिथुन** ↔ **ओपनएआई प्रतिक्रियाएं** -- आपका सीएलआई उपकरण ओपनएआई प्रारूप भेजता है → ओमनीरूट अनुवाद करता है → प्रदाता मूल प्रारूप प्राप्त करता है -- कस्टम ओपनएआई एंडपॉइंट्स का समर्थन करने वाले किसी भी टूल के साथ काम करता है -- **प्रतिक्रिया स्वच्छता** - सख्त ओपनएआई एसडीके संगतता के लिए गैर-मानक फ़ील्ड को हटा देता है -- **भूमिका सामान्यीकरण** - `developer` → गैर-OpenAI के लिए `system`; `system` → GLM/ERNIE मॉडल के लिए `user` -- **टैग निष्कर्षण के बारे में सोचें** - `💳 सदस्यता प्रदाता
- -### क्लाउड कोड (प्रो/मैक्स) - -**प्रो टिप:** जटिल कार्यों के लिए ओपस और गति के लिए सॉनेट का उपयोग करें। ओमनीरूट प्रति मॉडल कोटा ट्रैक करता है! - -### ओपनएआई कोडेक्स (प्लस/प्रो) - -### जेमिनी सीएलआई (मुफ़्त 180K/माह!) - -**सर्वोत्तम मूल्य:** विशाल निःशुल्क स्तर! सशुल्क स्तरों से पहले इसका उपयोग करें। - -### गिटहब कोपायलट +### Protocol Setup (MCP + A2A)
-
-### ग्रोक (निःशुल्क टियर उपलब्ध!)
+🔑 API कुंजी प्रदाता
+🧩 MCP Setup (Model Context Protocol)
-### एनवीडिया एनआईएम (मुफ़्त 1000 क्रेडिट!) +Start MCP transport in stdio mode: -1. साइन अप करें: [build.nvidia.com](https://build.nvidia.com) -2. निःशुल्क एपीआई कुंजी प्राप्त करें (1000 अनुमान क्रेडिट शामिल) -3. डैशबोर्ड → प्रदाता जोड़ें → एनवीडिया एनआईएम: - - एपीआई कुंजी: `nvapi-your-key` +```bash +omniroute --mcp +``` -**मॉडल:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, और 50+ अधिक +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: -1. साइन अप करें: [platform.deepseek.com](https://platform.deepseek.com) -2. एपीआई कुंजी प्राप्त करें -3. डैशबोर्ड → प्रदाता जोड़ें → डीपसीक +- `GET /api/mcp/status` +- `GET /api/mcp/tools` +- `GET /api/mcp/audit` +- `GET /api/mcp/audit/stats` -**मॉडल:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` +
+
-**उपयोग करें:** `glm/glm-4.7`
+🤝 A2A Setup (Agent2Agent)
-1. साइन अप करें: [console.groq.com](https://console.groq.com) -2. एपीआई कुंजी प्राप्त करें (फ्री टियर शामिल) -3. डैशबोर्ड → प्रदाता जोड़ें → ग्रोक +Discover the agent: -**मॉडल:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` +```bash +curl http://localhost:20128/.well-known/agent.json +``` -**प्रो टिप:** अल्ट्रा-फास्ट अनुमान - वास्तविक समय कोडिंग के लिए सर्वोत्तम! +Send a task: -### ओपनराउटर (100+ मॉडल) +```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."}]}}' +``` -1. साइन अप करें: [openrouter.ai](https://openrouter.ai) -2. एपीआई कुंजी प्राप्त करें -3. डैशबोर्ड → प्रदाता जोड़ें → ओपनराउटर +Manage lifecycle: -**मॉडल:** एक ही एपीआई कुंजी के माध्यम से सभी प्रमुख प्रदाताओं से 100+ मॉडल तक पहुंचें। +- `GET /api/a2a/status` +- `GET /api/a2a/tasks` +- `GET /api/a2a/tasks/:id` +- `POST /api/a2a/tasks/:id/cancel` -💰 सस्ते प्रदाता (बैकअप)
+Operational UI: -### GLM-4.7 (दैनिक रीसेट, $0.6/1 मिलियन) +- `/dashboard/a2a` for task/state/stream observability and smoke actions -1. साइन अप करें: [Zhipu AI](https://open.bigmodel.cn/) -2. कोडिंग योजना से एपीआई कुंजी प्राप्त करें -3. डैशबोर्ड → एपीआई कुंजी जोड़ें: - - प्रदाता: `glm` - - एपीआई कुंजी: `your-key` +
+
-### किमी K2 ($9/माह फ्लैट)
+🧪 End-to-end protocol validation
-**प्रो टिप:** कोडिंग प्लान 1/7 लागत पर 3× कोटा प्रदान करता है! प्रतिदिन सुबह 10:00 बजे रीसेट करें। +Validate both protocols with real clients: -### मिनीमैक्स एम2.1 (5 घंटे रीसेट, $0.20/1 मिलियन) +```bash +npm run test:protocols:e2e +``` -1. साइन अप करें: [MiniMax](https://www.minimax.io/) -2. एपीआई कुंजी प्राप्त करें -3. डैशबोर्ड → एपीआई कुंजी जोड़ें +This verifies: -**उपयोग:** `minimax/MiniMax-M2.1` +- MCP SDK client connect/list/call +- A2A discovery/send/stream/get/cancel +- Cross-check data in MCP audit and A2A task management APIs -**प्रो टिप:** लंबे संदर्भ के लिए सबसे सस्ता विकल्प (1M टोकन)! +
+
+
+💳 Subscription Providers
-1. सदस्यता लें: [Moonshot AI](https://platform.moonshot.ai/) -2. एपीआई कुंजी प्राप्त करें -3. डैशबोर्ड → एपीआई कुंजी जोड़ें +### Claude Code (Pro/Max) -**उपयोग करें:** `kimi/kimi-latest` +```bash +Dashboard → Providers → Connect Claude Code +→ OAuth login → Auto token refresh +→ 5-hour + weekly quota tracking -**प्रो टिप:** 10एम टोकन के लिए निश्चित $9/माह = $0.90/1एम प्रभावी लागत! +Models: + cc/claude-opus-4-6 + 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! -### आईफ्लो (8 मुफ़्त मॉडल) +### OpenAI Codex (Plus/Pro) -### क्वेन (3 मुफ़्त मॉडल) +```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) -### उदाहरण 1: सदस्यता अधिकतम करें → सस्ता बैकअप +Each Codex account now has policy toggles in `Dashboard -> Providers`: -### उदाहरण 2: केवल निःशुल्क (शून्य लागत) +- `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). + +### Gemini CLI (FREE 180K/month!) + +```bash +Dashboard → Providers → Connect Gemini CLI +→ Google OAuth +→ 180K completions/month + 1K/day + +Models: + gc/gemini-3-flash-preview + gc/gemini-2.5-pro +``` + +**Best Value:** Huge free tier! Use this before paid tiers. + +### 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-pro +``` + +
+
+
+🔑 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. + +
+
+
+💰 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)
+ +### iFlow (5 FREE models via OAuth) + +```bash +Dashboard → Connect iFlow +→ iFlow 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-6 (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 @@ -1045,196 +1650,471 @@ Models: Cost: $0 forever! ``` -🔧 CLI एकीकरण
+
+
---
-## 🐛 समस्या निवारण
+## समस्या निवारण
-🔧 CLI Integration
-### क्लाउड कोड +### Cursor IDE -एक-क्लिक कॉन्फ़िगरेशन के लिए डैशबोर्ड में **CLI टूल्स** पृष्ठ का उपयोग करें, या `~/.claude/settings.json` को मैन्युअल रूप से संपादित करें। +``` +Settings → Models → Advanced: + OpenAI API Base URL: http://localhost:20128/v1 + OpenAI API Key: [from OmniRoute dashboard] + Model: cc/claude-opus-4-6 +``` -### कोडेक्स सीएलआई +### Claude Code -### ओपनक्लॉ +Use the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually. -**विकल्प 1 - डैशबोर्ड (अनुशंसित):** +### Codex CLI -**विकल्प 2 - मैनुअल:** संपादित करें `~/.openclaw/openclaw.json`: +```bash +export OPENAI_BASE_URL="http://localhost:20128" +export OPENAI_API_KEY="your-omniroute-api-key" -> **ध्यान दें:** ओपनक्लाव केवल स्थानीय ओमनीरूट के साथ काम करता है। IPv6 रिज़ॉल्यूशन समस्याओं से बचने के लिए `localhost` के बजाय `127.0.0.1` का उपयोग करें। +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. + +समस्या निवारण मार्गदर्शिका का विस्तार करने के लिए क्लिक करें
+
+
+
+## 🛠️ Tech Stack
+
+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** -- सदस्यता कोटा ख़त्म → GLM/MiniMax पर फ़ॉलबैक -- कॉम्बो जोड़ें: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Subscription quota out → Fallback to GLM/MiniMax +- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -**OAuth टोकन समाप्त हो गया** +**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 +- Use free tier (Gemini CLI, iFlow) for non-critical tasks -**डैशबोर्ड गलत पोर्ट पर खुलता है** +**Dashboard/API ports are wrong** -- `PORT=20128` और `NEXT_PUBLIC_BASE_URL=http://localhost:20128` सेट करें +- `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** -- अपने चल रहे उदाहरण के लिए `BASE_URL` अंक सत्यापित करें -- अपने अपेक्षित क्लाउड एंडपॉइंट पर `CLOUD_URL` पॉइंट सत्यापित करें -- `NEXT_PUBLIC_*` मानों को सर्वर-साइड मानों के साथ संरेखित रखें +- 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** -- `.env` में `INITIAL_PASSWORD` को जांचें -- यदि सेट नहीं है, तो फ़ॉलबैक पासवर्ड `123456` है +- Check `INITIAL_PASSWORD` in `.env` +- If unset, fallback password is `123456` -**कोई अनुरोध लॉग नहीं** +**No request logs** -- `.env` में `ENABLE_REQUEST_LOGS=true` सेट करें +- Set `ENABLE_REQUEST_LOGS=true` in `.env` -**कनेक्शन परीक्षण OpenAI-संगत प्रदाताओं के लिए "अमान्य" दिखाता है** +**Connection test shows "Invalid" for OpenAI-compatible providers** -- कई प्रदाता `/models` समापन बिंदु को उजागर नहीं करते हैं -- ओमनीरूट v1.0.6+ में चैट पूर्णता के माध्यम से फ़ॉलबैक सत्यापन शामिल है -- सुनिश्चित करें कि आधार URL में `/v1` प्रत्यय शामिल हो +- 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** + +#### Why does Antigravity / Gemini CLI OAuth fail on remote servers? + +The **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console. + +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 + +# For Gemini CLI: +GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com +GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +``` + +**6. Restart OmniRoute** + +```bash +# npm: +npm run dev + +# Docker: +docker restart omniroute +``` + +**7. Try connecting again** + +Dashboard → Providers → Antigravity (or Gemini CLI) → OAuth + +Google will now redirect correctly to `https://your-server.com/callback`. --- -## 🛠️ +#### Temporary workaround (without custom credentials) -- **रनटाइम**: Node.js 18–22 LTS (⚠️ Node.js 24+ **समर्थित नहीं** है - `better-sqlite3` मूल बायनेरिज़ असंगत हैं) -- **भाषा**: टाइपस्क्रिप्ट 5.9 - **100% टाइपस्क्रिप्ट** `src/` और `open-sse/` (v1.0.6) में -- **फ्रेमवर्क**: नेक्स्ट.जेएस 16 + रिएक्ट 19 + टेलविंड सीएसएस 4 -- **डेटाबेस**: लोडीबी (JSON) + SQLite (डोमेन स्थिति + प्रॉक्सी लॉग) -- **स्ट्रीमिंग**: सर्वर-भेजे गए इवेंट (एसएसई) -- **प्रामाणिक**: OAuth 2.0 (PKCE) + JWT + API कुंजियाँ -- **परीक्षण**: Node.js परीक्षण धावक (368+ इकाई परीक्षण) -- **सीआई/सीडी**: गिटहब क्रियाएँ (ऑटो एनपीएम प्रकाशन + रिलीज पर डॉकर हब) -- **वेबसाइट**: [omniroute.online](https://omniroute.online) -- **पैकेज**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute) -- **डॉकर**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute) -- **लचीलापन**: सर्किट ब्रेकर, एक्सपोनेंशियल बैकऑफ़, एंटी-थंडरिंग झुंड, टीएलएस स्पूफिंग +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. --- -## 📖 दस्तावेज़ीकरण +
+
---
-## 👥 योगदानकर्ता
+🇧🇷 Versão em Português
-| दस्तावेज़ | विवरण | -| -------------------------------------------- | ------------------------------------------- | -| [User Guide](docs/USER_GUIDE.md) | प्रदाता, कॉम्बो, सीएलआई एकीकरण, तैनाती | -| [API Reference](docs/API_REFERENCE.md) | उदाहरण सहित सभी समापन बिंदु | -| [Troubleshooting](docs/TROUBLESHOOTING.md) | सामान्य समस्याएँ एवं समाधान | -| [Architecture](docs/ARCHITECTURE.md) | सिस्टम आर्किटेक्चर और आंतरिक | -| [Contributing](CONTRIBUTING.md) | विकास सेटअप और दिशानिर्देश | -| [OpenAPI Spec](docs/openapi.yaml) | ओपनएपीआई 3.0 विशिष्टता | -| [Security Policy](SECURITY.md) | भेद्यता रिपोर्टिंग और सुरक्षा प्रथाएं | -| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | संपूर्ण गाइड: VM + nginx + Cloudflare सेटअप | -| [Features Gallery](docs/FEATURES.md) | स्क्रीनशॉट के साथ विजुअल डैशबोर्ड टूर | +#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos? -### 📸 डैशबोर्ड पूर्वावलोकन +Os provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo. -डैशबोर्ड स्क्रीनशॉट देखने के लिए क्लिक करें
+As credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticação com: -| पेज | स्क्रीनशॉट | -| ----------------- | ------------------------------------------------- | -| **प्रदाता** |  | -| **कॉम्बोस** |  | -| **एनालिटिक्स** |  | -| **स्वास्थ्य** |  | -| **अनुवादक** |  | -| **सेटिंग्स** |  | -| **सीएलआई उपकरण** |  | -| **उपयोग लॉग** |  | -| **समाप्ति बिंदु** |  | +``` +Error 400: redirect_uri_mismatch +``` + +#### Solução: Configure suas próprias credenciais OAuth + +Você precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor. + +#### Passo a passo + +**1. Acesse o Google Cloud Console** + +Abra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) + +**2. Crie um novo OAuth 2.0 Client ID** + +- Clique em **"+ Create Credentials"** → **"OAuth client ID"** +- Tipo de aplicativo: **"Web application"** +- Nome: escolha qualquer nome (ex: `OmniRoute Remote`) + +**3. Adicione as Authorized Redirect URIs** + +No campo **"Authorized redirect URIs"**, adicione: + +``` +https://seu-servidor.com/callback +``` + +> Substitua `seu-servidor.com` pelo domínio ou IP do seu servidor (inclua a porta se necessário, ex: `http://45.33.32.156:20128/callback`). + +**4. Salve e copie as credenciais** + +Após criar, o Google mostrará o **Client ID** e o **Client Secret**. + +**5. Configure as variáveis de ambiente** + +No seu `.env` (ou nas variáveis de ambiente do Docker): + +```bash +# Para Antigravity: +ANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com +ANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret + +# Para Gemini CLI: +GEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com +GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret +GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret +``` + +**6. Reinicie o OmniRoute** + +```bash +# Se usando npm: +npm run dev + +# Se usando Docker: +docker restart omniroute +``` + +**7. Tente conectar novamente** + +Dashboard → Providers → Antigravity (ou Gemini CLI) → OAuth + +Agora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará. --- -## 🗺️ +#### Workaround temporário (sem configurar credenciais próprias) -ओम्निरूट ने कई विकास चरणों में **210+ सुविधाओं की योजना बनाई है**। यहां प्रमुख क्षेत्र हैं: +Se não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**: -| श्रेणी | नियोजित विशेषताएं | हाइलाइट्स | -| ---------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------- | -| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format | -| 🧠 **रूटिंग और इंटेलिजेंस** | 25+ | न्यूनतम-विलंबता रूटिंग, टैग-आधारित रूटिंग, कोटा प्रीफ़्लाइट, पी2सी खाता चयन | -| 🔒 **सुरक्षा एवं अनुपालन** | 20+ | एसएसआरएफ हार्डनिंग, क्रेडेंशियल क्लोकिंग, प्रति समापन बिंदु दर-सीमा, प्रबंधन कुंजी स्कोपिंग | -| 📊 **अवलोकनशीलता** | 15+ | ओपन टेलीमेट्री एकीकरण, वास्तविक समय कोटा निगरानी, प्रति मॉडल लागत ट्रैकिंग | -| 🔄 **प्रदाता एकीकरण** | 20+ | डायनेमिक मॉडल रजिस्ट्री, प्रदाता कूलडाउन, मल्टी-अकाउंट कोडेक्स, कोपायलट कोटा पार्सिंग | -| ⚡ **प्रदर्शन** | 15+ | दोहरी कैश परत, शीघ्र कैश, प्रतिक्रिया कैश, स्ट्रीमिंग कीपलाइव, बैच एपीआई | -| 🌐 **पारिस्थितिकी तंत्र** | 10+ | वेबसॉकेट एपीआई, कॉन्फिग हॉट-रीलोड, वितरित कॉन्फिग स्टोर, वाणिज्यिक मोड | +1. O OmniRoute abrirá a URL de autorização do Google +2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto) +3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue) +4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute +5. Clique em **"Connect"** -### 🔜 जल्द आ रहा है +> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não. -- 🔗 **ओपनकोड इंटीग्रेशन** - ओपनकोड एआई कोडिंग आईडीई के लिए मूल प्रदाता समर्थन -- 🔗 **TRAE एकीकरण** - TRAE AI विकास ढांचे के लिए पूर्ण समर्थन -- 📦 **बैच एपीआई** - थोक अनुरोधों के लिए अतुल्यकालिक बैच प्रोसेसिंग -- 🎯 **टैग-आधारित रूटिंग** - कस्टम टैग और मेटाडेटा के आधार पर रूट अनुरोध -- 💰 **न्यूनतम-लागत रणनीति** — स्वचालित रूप से सबसे सस्ते उपलब्ध प्रदाता का चयन करें - -> 📝 पूर्ण फीचर विशिष्टताएं [link](docs/new-features/) में उपलब्ध हैं (217 विस्तृत विवरण) +
+
+
+---
+
+## दस्तावेज़
+
+| Document | Description |
+| ---------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 16 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/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
+| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+
+---
+
+## 🗺️ Roadmap
+
+OmniRoute has **210+ 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, P2C account selection |
+| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |
+| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |
+| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider 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
[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
-### योगदान कैसे करें
+### How to Contribute
-1. रिपॉजिटरी को फोर्क करें
-2. अपनी फीचर शाखा बनाएं (`git checkout -b feature/amazing-feature`)
-3. अपने परिवर्तन प्रतिबद्ध करें (`git commit -m 'Add amazing feature'`)
-4. शाखा में पुश करें (`git push origin feature/amazing-feature`)
-5. एक पुल अनुरोध खोलें
+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
-विस्तृत दिशानिर्देशों के लिए [CONTRIBUTING.md](CONTRIBUTING.md) देखें।
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
-### एक नया संस्करण जारी करना
+### Releasing a New Version
```bash
# Create a release — npm publish happens automatically
-gh release create v1.0.6 --title "v1.0.6" --generate-notes
+gh release create v2.0.0 --title "v2.0.0" --generate-notes
```
---
-## 📊 सितारा इतिहास
+## 📊 Star History
## Stargazers over time
## [](https://starchart.cc/diegosouzapw/OmniRoute)
-## 🙏 आभार
+## 🙏 Acknowledgments
-**[decolua](https://github.com/decolua)** द्वारा **[decolua](https://github.com/decolua)** को विशेष धन्यवाद - मूल परियोजना जिसने इस फोर्क को प्रेरित किया। ओमनीरूट अतिरिक्त सुविधाओं, मल्टी-मोडल एपीआई और पूर्ण टाइपस्क्रिप्ट पुनर्लेखन के साथ उस अविश्वसनीय नींव पर आधारित है।
+Special thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.
-**[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** को विशेष धन्यवाद - मूल गो कार्यान्वयन जिसने इस जावास्क्रिप्ट पोर्ट को प्रेरित किया।
+Special thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.
---
-## 📄 लाइसेंस
+## लाइसेंस
-एमआईटी लाइसेंस - विवरण के लिए [LICENSE](LICENSE) देखें।
+MIT License - see [LICENSE](LICENSE) for details.
---
----
+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**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions) +- **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 + +
+ Built with ❤️ for developers who code 24/7
+
+ omniroute.online +
+
diff --git a/docs/i18n/in/docs/FEATURES.md b/docs/i18n/in/docs/FEATURES.md
new file mode 100644
index 0000000000..76ea57aa04
--- /dev/null
+++ b/docs/i18n/in/docs/FEATURES.md
@@ -0,0 +1,145 @@
+# OmniRoute — Dashboard Features Gallery (हिन्दी)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/FEATURES.md) · 🇪🇸 [es](../../es/docs/FEATURES.md) · 🇫🇷 [fr](../../fr/docs/FEATURES.md) · 🇩🇪 [de](../../de/docs/FEATURES.md) · 🇮🇹 [it](../../it/docs/FEATURES.md) · 🇷🇺 [ru](../../ru/docs/FEATURES.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FEATURES.md) · 🇯🇵 [ja](../../ja/docs/FEATURES.md) · 🇰🇷 [ko](../../ko/docs/FEATURES.md) · 🇸🇦 [ar](../../ar/docs/FEATURES.md) · 🇮🇳 [in](../../in/docs/FEATURES.md) · 🇹🇭 [th](../../th/docs/FEATURES.md) · 🇻🇳 [vi](../../vi/docs/FEATURES.md) · 🇮🇩 [id](../../id/docs/FEATURES.md) · 🇲🇾 [ms](../../ms/docs/FEATURES.md) · 🇳🇱 [nl](../../nl/docs/FEATURES.md) · 🇵🇱 [pl](../../pl/docs/FEATURES.md) · 🇸🇪 [sv](../../sv/docs/FEATURES.md) · 🇳🇴 [no](../../no/docs/FEATURES.md) · 🇩🇰 [da](../../da/docs/FEATURES.md) · 🇫🇮 [fi](../../fi/docs/FEATURES.md) · 🇵🇹 [pt](../../pt/docs/FEATURES.md) · 🇷🇴 [ro](../../ro/docs/FEATURES.md) · 🇭🇺 [hu](../../hu/docs/FEATURES.md) · 🇧🇬 [bg](../../bg/docs/FEATURES.md) · 🇸🇰 [sk](../../sk/docs/FEATURES.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FEATURES.md) · 🇮🇱 [he](../../he/docs/FEATURES.md) · 🇵🇭 [phi](../../phi/docs/FEATURES.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FEATURES.md)
+
+---
+
+Visual guide to every section of the OmniRoute dashboard.
+
+---
+
+## 🔌 Providers
+
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
+
+
+
+---
+
+## 🎨 Combos
+
+Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
+
+
+
+---
+
+## 📊 Analytics
+
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
+
+
+
+---
+
+## 🏥 System Health
+
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+
+
+
+---
+
+## 🔧 Translator Playground
+
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
+
+
+
+---
+
+## 🎮 Model Playground _(v2.0.9+)_
+
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
+
+---
+
+## 🎨 Themes _(v2.0.5+)_
+
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
+
+## ⚙️ Settings
+
+Comprehensive settings panel with tabs:
+
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning
+- **Advanced** — Configuration overrides
+
+
+
+---
+
+## 🔧 CLI Tools
+
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
+
+
+
+---
+
+## 🤖 CLI Agents _(v2.0.11+)_
+
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
+
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
+
+---
+
+## 🖼️ Media _(v2.0.3+)_
+
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
+
+## 📝 Request Logs
+
+Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
+
+
+
+---
+
+## 🌐 API Endpoint
+
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
+
+
+
+---
+
+## 🔑 API Key Management
+
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
+
+---
+
+## 📋 Audit Log
+
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
+
+---
+
+## 🖥️ Desktop Application
+
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
+
+Key features:
+
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
+
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.
diff --git a/docs/i18n/it/README.md b/docs/i18n/it/README.md
index cdd0ba1db2..5143093323 100644
--- a/docs/i18n/it/README.md
+++ b/docs/i18n/it/README.md
@@ -1,24 +1,94 @@
-+ omniroute.online +
-
-
- # 🚀 OmniRoute — Il Gateway IA Gratuito
+# 🚀 OmniRoute — The Free AI Gateway (Italiano)
-### Non smettere mai di programmare. Routing intelligente verso **modelli IA GRATUITI e economici** con fallback automatico.
-
-_Il tuo proxy API universale — un endpoint, 67+ provider, zero downtime._
-
-**Chat Completions • Embeddings • Generazione Immagini • Audio • Reranking • 100% TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Provider IA gratuito per i tuoi agenti di programmazione preferiti
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Connetti qualsiasi IDE o strumento CLI con IA tramite OmniRoute — gateway API gratuito per programmazione illimitata._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+` tags no longer leak to clients in SSE streaming responses (#585) |
+| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with per-provider/account quota enforcement, idempotency, SHA-256 storage, and optional GitHub issue reporting |
+| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG → generic fallback chain |
+| 🔄 **Model Auto-Sync** | 24h scheduler and manual UI toggle to sync model lists for built-in and custom OpenAI-compatible providers |
+| 🌐 **OpenCode Zen/Go** | Two new providers from @kang-heewon via PR #530: free tier + subscription tier via `OpencodeExecutor` |
+| 🐛 **Gemini CLI OAuth** | Actionable error when `GEMINI_OAUTH_CLIENT_SECRET` is missing in Docker (was cryptic Google error) |
+| 🐛 **OpenCode config** | `saveOpenCodeConfig()` now correctly writes TOML to `XDG_CONFIG_HOME` |
+| 🐛 **Pinned model override** | `body.model` correctly set to `pinnedModel` on context-cache protection |
+| 🐛 **Codex/Claude loop** | `tool_result` blocks now converted to text to stop infinite loops |
+| 🐛 **Login redirect** | Login no longer freezes after skipping password setup |
+| 🐛 **Windows paths** | MSYS2/Git-Bash paths (`/c/...`) normalized to `C:\...` automatically |
+
+---
+
+## 🖼️ Main Dashboard
+
+
-📡 Tutti gli agenti si connettono via ` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**Stop wasting money and hitting limits:**
-### 🆕 What's New in v3.0.0
+- Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**OmniRoute solves this:**
+
+- ✅ **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
+- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool
---
-[](https://www.npmjs.com/package/omniroute)
-[](https://hub.docker.com/r/diegosouzapw/omniroute)
-[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
-[](https://omniroute.online)
-[](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
+## 📧 Support
-[🌐 Sito Web](https://omniroute.online) • [🚀 Avvio Rapido](#-avvio-rapido) • [💡 Funzionalità](#-funzionalità-principali) • [📖 Docs](#-documentazione) • [💰 Prezzi](#-panoramica-prezzi)
+> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.
-🌐 **Available in:** 🇺🇸 [English](../../README.md) | 🇧🇷 [Português (Brasil)](../pt-BR/README.md) | 🇪🇸 [Español](../es/README.md) | 🇫🇷 [Français](../fr/README.md) | 🇮🇹 [Italiano](../it/README.md) | 🇷🇺 [Русский](../ru/README.md) | 🇨🇳 [中文 (简体)](../zh-CN/README.md) | 🇩🇪 [Deutsch](../de/README.md) | 🇮🇳 [हिन्दी](../in/README.md) | 🇹🇭 [ไทย](../th/README.md) | 🇺🇦 [Українська](../uk-UA/README.md) | 🇸🇦 [العربية](../ar/README.md) | 🇯🇵 [日本語](../ja/README.md) | 🇻🇳 [Tiếng Việt](../vi/README.md) | 🇧🇬 [Български](../bg/README.md) | 🇩🇰 [Dansk](../da/README.md) | 🇫🇮 [Suomi](../fi/README.md) | 🇮🇱 [עברית](../he/README.md) | 🇭🇺 [Magyar](../hu/README.md) | 🇮🇩 [Bahasa Indonesia](../id/README.md) | 🇰🇷 [한국어](../ko/README.md) | 🇲🇾 [Bahasa Melayu](../ms/README.md) | 🇳🇱 [Nederlands](../nl/README.md) | 🇳🇴 [Norsk](../no/README.md) | 🇵🇹 [Português (Portugal)](../pt/README.md) | 🇷🇴 [Română](../ro/README.md) | 🇵🇱 [Polski](../pl/README.md) | 🇸🇰 [Slovenčina](../sk/README.md) | 🇸🇪 [Svenska](../sv/README.md) | 🇵🇭 [Filipino](../phi/README.md)
-
-
-
----
-
-## 🖼️
-
-
-
- # 🚀 OmniRoute — Il Gateway IA Gratuito
+# 🚀 OmniRoute — The Free AI Gateway (Italiano)
-### Non smettere mai di programmare. Routing intelligente verso **modelli IA GRATUITI e economici** con fallback automatico.
-
-_Il tuo proxy API universale — un endpoint, 67+ provider, zero downtime._
-
-**Chat Completions • Embeddings • Generazione Immagini • Audio • Reranking • 100% TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Provider IA gratuito per i tuoi agenti di programmazione preferiti
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Connetti qualsiasi IDE o strumento CLI con IA tramite OmniRoute — gateway API gratuito per programmazione illimitata._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+
+
+[](https://www.npmjs.com/package/omniroute)
+[](https://www.npmjs.com/package/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
+[](https://omniroute.online)
+[](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)
+
+
+
+🌐 **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)
+
+---
+
+## 🆕 What's New in v3.0.0
+
+> **Upgrading from v2.9.5?** — See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes.
+
+| Area | Change |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection remediation |
+| ✅ **Route Validation** | All 176 API routes now validated with Zod schemas + `validateBody()` — CI `check:route-validation:t06` passes |
+| 🐛 **omniModel Tag Leak** | Internal `
+
+
+
+---
+
+## 📸 Dashboard Preview
+
+
+
+
+
+---
+
+### 🤖 Free AI Provider for your favorite coding agents
+
+_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._
Click to see dashboard screenshots
+ +| Page | Screenshot | +| -------------- | ------------------------------------------------- | +| **Providers** |  | +| **Combos** |  | +| **Analytics** |  | +| **Health** |  | +| **Translator** |  | +| **Settings** |  | +| **CLI Tools** |  | +| **Usage Logs** |  | +| **Endpoints** |  | + +|
-
+
OpenClaw @@ -92,587 +162,527 @@ _Connetti qualsiasi IDE o strumento CLI con IA tramite OmniRoute — gateway API |
http://localhost:20128/v1 o http://cloud.omniroute.online/v1 — una configurazione, modelli e quota illimitati
+📡 All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 — one config, unlimited models and quota
---
-### 🆕 What's New in v3.0.0
+## 🤔 Why OmniRoute?
-| Area | Change |
-| ------------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal ` Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `
-
-
-
----
-
-## 📸
-
-
-
-
-
----
-
-## 🤔 Perché OmniRoute?
-
-**Smetti di sprecare soldi e di sbattere contro i limiti:**
-
-- ...
- -| # | # | -| ----- | ---------------------------------------- | -| **1** |  | -| **2** |  | -| **3** |  | -| **4** |  | -| **5** |  | -| **6** |  | -| **7** |  | -| **8** |  | -| **9** |  | - - La quota dell'abbonamento scade inutilizzata ogni mese
-- I limiti di rate ti fermano nel mezzo della programmazione
-- API costose ($20-50/mese per provider)
-- Cambio manuale tra provider
-
-**OmniRoute risolve tutto questo:**
-
-- ✅ **Massimizza gli abbonamenti** — Traccia le quote, usa tutto prima del reset
-- ✅ **Fallback automatico** — Abbonamento → API Key → Economico → Gratuito, zero downtime
-- ✅ **Multi-account** — Round-robin tra account per provider
-- ✅ **Universale** — Funziona con Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, qualsiasi strumento CLI
-
----
-
-## 📧 Supporto
-
-> 💬 **Unisciti alla nostra community!** [Gruppo WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Ottieni aiuto, condividi consigli e rimani aggiornato.
-
-- **Sito Web**: [omniroute.online](https://omniroute.online)
+- **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**: [Gruppo della comunità](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **WhatsApp**: [Gruppo della comunità](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Progetto Originale**: [9router di decolua](https://github.com/decolua/9router)
+- **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`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 Come Funziona
+## 🔄 How It Works
```
┌─────────────┐
-│ Il tuo CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
+│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
│ Tool │
└──────┬──────┘
│ http://localhost:20128/v1
↓
┌─────────────────────────────────────────┐
-│ OmniRoute (Router Intelligente) │
-│ • Traduzione formato (OpenAI ↔ Claude) │
-│ • Tracciamento quote + Embeddings + Immagini │
-│ • Rinnovo automatico dei token │
+│ OmniRoute (Smart Router) │
+│ • Format translation (OpenAI ↔ Claude) │
+│ • Quota tracking + Embeddings + Images │
+│ • Auto token refresh │
└──────┬──────────────────────────────────┘
│
- ├─→ [Tier 1: ABBONAMENTO] Claude Code, Codex, Gemini CLI
- │ ↓ quota esaurita
- ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, ecc.
- │ ↓ limite budget
- ├─→ [Tier 3: ECONOMICO] GLM ($0.6/1M), MiniMax ($0.2/1M)
- │ ↓ limite budget
- └─→ [Tier 4: GRATUITO] iFlow, Qwen, Kiro (illimitato)
+ ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI
+ │ ↓ 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] iFlow, Qwen, Kiro (unlimited)
-Risultato: Non smettere mai di programmare, costo minimo
+Result: Never stop coding, minimal cost
```
---
-## 🎯 Cosa risolve OmniRoute: 30 punti critici reali e casi d'uso
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **Ogni sviluppatore che utilizza strumenti di intelligenza artificiale affronta questi problemi quotidianamente.** OmniRoute è stato creato per risolverli tutti: dai superamenti dei costi ai blocchi regionali, dai flussi OAuth interrotti alle operazioni di protocollo e all'osservabilità aziendale.
+> **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.
-
💸 1. "Pago un abbonamento costoso ma vengo comunque interrotto dai limiti"
+💸 1. "I pay for an expensive subscription but still get interrupted by limits"
-Gli sviluppatori pagano $ 20-200 al mese per Claude Pro, Codex Pro o GitHub Copilot. Anche pagando, la quota ha un tetto: 5 ore di utilizzo, limiti settimanali o limiti di tariffa al minuto. A metà sessione di codifica, il provider smette di rispondere e lo sviluppatore perde flusso e produttività. +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. -**Come OmniRoute risolve il problema:** +**How OmniRoute solves it:** -- **Fallback intelligente a 4 livelli**: se la quota dell'abbonamento si esaurisce, reindirizza automaticamente alla chiave API → Economico → Gratuito senza alcun intervento manuale -- **Monitoraggio delle quote in tempo reale**: mostra il consumo di token in tempo reale con il conto alla rovescia ripristinato (5 ore, giornaliero, settimanale) -- **Supporto multi-account**: più account per fornitore con round robin automatico: quando uno si esaurisce, passa a quello successivo -- **Combo personalizzate** — Catene di fallback personalizzabili con 6 strategie di bilanciamento (fill-first, round-robin, P2C, casuale, meno utilizzato, ottimizzato in termini di costi) -- **Quote aziendali Codex**: monitoraggio delle quote dello spazio di lavoro aziendale/team direttamente nella dashboard +- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention +- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly) +- **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 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
-` da modelli come DeepSeek R1 in `reasoning_content` standardizzati
-- **Uscita strutturata per Gemini** — `json_schema` → `responseMimeType`/`responseSchema` conversione automatica
-- **`stream` per impostazione predefinita è `false`** — Si allinea con le specifiche OpenAI, evitando SSE imprevisti negli SDK Python/Rust/Go
+- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 67+ 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
🔌 2. "Devo utilizzare più provider ma ognuno ha un'API diversa"
+🔌 2. "I need to use multiple providers but each has a different API"
-OpenAI utilizza un formato, Claude (Anthropic) ne utilizza un altro, Gemini ancora un altro. Se uno sviluppatore desidera testare modelli di fornitori diversi o eseguire il fallback tra di loro, deve riconfigurare gli SDK, modificare gli endpoint e gestire formati incompatibili. I provider personalizzati (FriendLI, NIM) hanno endpoint del modello non standard. +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. -**Come OmniRoute risolve il problema:** +**How OmniRoute solves it:** -- **Endpoint unificato**: un singolo `http://localhost:20128/v1` funge da proxy per tutti gli oltre 36 provider -- **Traduzione del formato** — Automatica e trasparente: OpenAI ↔ Claude ↔ Gemini ↔ API di risposta -- **Sanitizzazione della risposta**: rimuove i campi non standard (`x_groq`, `usage_breakdown`, `service_tier`) che interrompono OpenAI SDK v1.83+ -- **Normalizzazione del ruolo**: converte `developer` → `system` per provider non OpenAI; `system` → `user` per GLM/ERNIE -- **Think Tag Extraction** — Estrae i blocchi `
-
🌐 3. "Il mio fornitore di intelligenza artificiale blocca la mia regione/paese"
+🌐 3. "My AI provider blocks my region/country"
-Provider come OpenAI/Codex bloccano l'accesso da determinate regioni geografiche. Gli utenti ricevono errori come `unsupported_country_region_territory` durante le connessioni OAuth e API. Ciò è particolarmente frustrante per gli sviluppatori dei paesi in via di sviluppo. +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. -**Come OmniRoute risolve il problema:** +**How OmniRoute solves it:** -- **Configurazione proxy a 3 livelli**: proxy configurabile a 3 livelli: globale (tutto il traffico), per provider (un solo provider) e per connessione/chiave -- **Badge proxy con codice colore** — Indicatori visivi: 🟢 proxy globale, 🟡 proxy provider, 🔵 proxy di connessione, che mostra sempre l'IP -- **Scambio di token OAuth tramite proxy**: anche il flusso OAuth passa attraverso il proxy, risolvendo `unsupported_country_region_territory` -- **Test di connessione tramite proxy**: i test di connessione utilizzano il proxy configurato (non più bypass diretto) -- **Supporto SOCKS5**: supporto completo del proxy SOCKS5 per il routing in uscita -- **Spoofing dell'impronta digitale TLS**: impronta digitale TLS simile a un browser tramite `wreq-js` per bypassare il rilevamento dei bot +- **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
-` prefix
-- **Combo solo gratuiti** — Catena `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $ 0/mese senza tempi di inattività
-- **Crediti gratuiti NVIDIA NIM**: 1000 crediti gratuiti integrati
-- **Strategia di ottimizzazione dei costi**: strategia di routing che sceglie automaticamente il fornitore più economico disponibile
+- **Free-Only Combos** — Chain `gc/gemini-3-flash → 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
🆓 4. "Voglio usare l'intelligenza artificiale per programmare ma non ho soldi"
+🆓 4. "I want to use AI for coding but I have no money"
-Non tutti possono pagare $ 20-200 al mese per gli abbonamenti AI. Studenti, sviluppatori provenienti da paesi emergenti, hobbisti e liberi professionisti hanno bisogno di accedere a modelli di qualità a costo zero. +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. -**Come OmniRoute risolve il problema:** +**How OmniRoute solves it:** -- **Fornitori del livello gratuito integrati**: supporto nativo per fornitori gratuiti al 100%: iFlow (8 modelli illimitati), Qwen (3 modelli illimitati), Kiro (Claude gratis), Gemini CLI (180.000/mese gratuiti) +- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free) - **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/
-
🔒 5. "Devo proteggere il mio gateway AI da accessi non autorizzati"
+🔒 5. "I need to protect my AI gateway from unauthorized access"
-Quando si espone un gateway AI alla rete (LAN, VPS, Docker), chiunque abbia l'indirizzo può consumare i token/la quota dello sviluppatore. Senza protezione, le API sono vulnerabili ad usi impropri, tempestive iniezioni e abusi. +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. -**Come OmniRoute risolve il problema:** +**How OmniRoute solves it:** -- **Gestione delle chiavi API**: generazione, rotazione e ambito per provider con una pagina `/dashboard/api-manager` dedicata -- **Autorizzazioni a livello di modello**: limita le chiavi API a modelli specifici (`openai/*`, modelli con caratteri jolly), con l'interruttore Consenti tutto/Limita -- **API Endpoint Protection**: richiede una chiave per `/v1/models` e blocca provider specifici dall'elenco -- **Auth Guard + Protezione CSRF**: tutti i percorsi del dashboard protetti con middleware `withAuth` + token CSRF -- **Rate Limiter**: limitazione della velocità per IP con finestre configurabili -- **Filtro IP**: lista consentita/lista bloccata per il controllo degli accessi -- **Prompt Injection Guard**: sanificazione contro modelli di prompt dannosi -- **Crittografia AES-256-GCM**: credenziali crittografate a riposo +- **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. "Il mio provider è andato in tilt e ho perso il flusso di codifica"
+🛑 6. "My provider went down and I lost my coding flow"
-I fornitori di intelligenza artificiale possono diventare instabili, restituire errori 5xx o raggiungere limiti di velocità temporanei. Se uno sviluppatore dipende da un singolo fornitore, viene interrotto. Senza interruttori automatici, tentativi ripetuti possono bloccare l'applicazione. +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. -**Come OmniRoute risolve il problema:** +**How OmniRoute solves it:** -- **Interruttore automatico per provider**: apertura/chiusura automatica con soglie e raffreddamento configurabili (chiuso/aperto/semiaperto) -- **Backoff esponenziale**: ritardi progressivi tra i tentativi -- **Anti-Thundering Herd** — Mutex + protezione semaforo contro tempeste di tentativi simultanei -- **Catene di fallback combinate**: se il fornitore primario fallisce, cade automaticamente nella catena senza alcun intervento -- **Combo Circuit Breaker**: disabilita automaticamente i provider in errore all'interno di una catena combinata -- **Dashboard integrità**: monitoraggio del tempo di attività, stati degli interruttori automatici, blocchi, statistiche della cache, latenza p50/p95/p99 +- **Circuit Breaker per-model** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks +- **Exponential Backoff** — Progressive retry delays +- **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 +- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain +- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
-
🔧 7. "Configurare ogni strumento AI è noioso e ripetitivo"
+🔧 7. "Configuring each AI tool is tedious and repetitive"
-Gli sviluppatori utilizzano Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Ogni strumento necessita di una configurazione diversa (endpoint API, chiave, modello). La riconfigurazione quando si cambia fornitore o modello è una perdita di tempo. +Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time. -**Come OmniRoute risolve il problema:** +**How OmniRoute solves it:** -- **Dashboard degli strumenti CLI**: pagina dedicata con configurazione con un clic per Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline -- **GitHub Copilot Config Generator**: genera `chatLanguageModels.json` per VS Code con selezione di modelli in blocco -- **Procedura guidata di onboarding**: configurazione guidata in 4 passaggi per gli utenti alle prime armi -- **Un endpoint, tutti i modelli**: configura `http://localhost:20128/v1` una volta, accedi a oltre 36 provider +- **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 67+ providers
-
🔑 8. "Gestire token OAuth da più provider è un inferno"
+🔑 8. "Managing OAuth tokens from multiple providers is hell"
-Claude Code, Codex, Gemini CLI, Copilot: utilizzano tutti OAuth 2.0 con token in scadenza. Gli sviluppatori devono autenticarsi nuovamente costantemente, gestire `client_secret is missing`, `redirect_uri_mismatch` e errori sui server remoti. OAuth su LAN/VPS è particolarmente problematico. +Claude Code, Codex, Gemini CLI, 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. -**Come OmniRoute risolve il problema:** +**How OmniRoute solves it:** -- **Aggiornamento automatico dei token**: i token OAuth si aggiornano in background prima della scadenza -- **OAuth 2.0 (PKCE) integrato**: flusso automatico per Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow -- **OAuth multi-account**: account multipli per provider tramite estrazione di token JWT/ID -- **OAuth LAN/Correzione remota**: rilevamento IP privato per `redirect_uri` + modalità URL manuale per server remoti -- **OAuth Behind Nginx**: utilizza `window.location.origin` per la compatibilità con proxy inverso -- **Guida OAuth remota**: guida passo passo per le credenziali Google Cloud su VPS/Docker +- **Auto Token Refresh** — OAuth tokens refresh in background before expiration +- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow +- **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. "Non so quanto sto spendendo né dove"
+📊 9. "I don't know how much I'm spending or where"
-Gli sviluppatori utilizzano più fornitori a pagamento ma non hanno una visione unificata della spesa. Ogni fornitore ha il proprio dashboard di fatturazione, ma non esiste una visualizzazione consolidata. I costi imprevisti possono accumularsi. +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. -**Come OmniRoute risolve il problema:** +**How OmniRoute solves it:** -- **Dashboard di analisi dei costi**: monitoraggio dei costi per token e gestione del budget per fornitore -- **Limiti di budget per livello**: massimale di spesa per livello che attiva il fallback automatico -- **Configurazione dei prezzi per modello**: prezzi configurabili per modello -- **Statistiche di utilizzo per chiave API**: conteggio delle richieste e timestamp dell'ultimo utilizzo per chiave -- **Dashboard di analisi**: schede statistiche, grafico di utilizzo del modello, tabella dei fornitori con percentuali di successo e latenza +- **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. "Non riesco a diagnosticare errori e problemi nelle chiamate AI"
+🐛 10. "I can't diagnose errors and problems in AI calls"
-Quando una chiamata fallisce, lo sviluppatore non sa se si trattava di un limite di velocità, di un token scaduto, di un formato errato o di un errore del provider. Registri frammentati su diversi terminali. Senza osservabilità, il debug è un processo per tentativi ed errori. +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. -**Come OmniRoute risolve il problema:** +**How OmniRoute solves it:** -- **Dashboard dei registri unificati**: 4 schede: registri delle richieste, registri del proxy, registri di controllo, console -- **Visualizzatore log della console**: visualizzatore in stile terminale in tempo reale con livelli codificati a colori, scorrimento automatico, ricerca, filtro -- **Registri proxy SQLite**: registri persistenti che sopravvivono ai riavvii del server -- **Translator Playground** — 4 modalità di debug: Playground (traduzione del formato), Chat Tester (andata e ritorno), Test Bench (batch), Live Monitor (in tempo reale) -- **Telemetria richiesta**: latenza p50/p95/p99 + traccia X-Request-Id -- **Registrazione basata su file con rotazione**: l'interceptor della console acquisisce tutto nel registro JSON con rotazione basata sulle dimensioni +- **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 Proxy Logs** — Persistent logs that survive server restarts +- **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 Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation +- **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. "L'implementazione e la manutenzione del gateway sono complesse"
+🏗️ 11. "Deploying and maintaining the gateway is complex"
-L'installazione, la configurazione e la manutenzione di un proxy AI in diversi ambienti (locale, VPS, Docker, cloud) richiedono molto lavoro. Problemi come percorsi codificati, `EACCES` nelle directory, conflitti di porte e build multipiattaforma aggiungono attrito. +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. -**Come OmniRoute risolve il problema:** +**How OmniRoute solves it:** -- **Installazione globale npm** — `npm install -g omniroute && omniroute` — completata -- **Docker multipiattaforma** — AMD64 + ARM64 nativo (Apple Silicon, AWS Graviton, Raspberry Pi) -- **Docker Compose Profiles** — `base` (senza strumenti CLI) e `cli` (con Claude Code, Codex, OpenClaw) -- **App desktop Electron**: app nativa per Windows/macOS/Linux con barra delle applicazioni, avvio automatico, modalità offline -- **Modalità porta divisa**: API e dashboard su porte separate per scenari avanzati (proxy inverso, rete di contenitori) -- **Cloud Sync**: configura la sincronizzazione tra dispositivi tramite Cloudflare Workers -- **Backup DB**: backup, ripristino, esportazione e importazione automatici di tutte le impostazioni +- **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
-
🌍 12. "L'interfaccia è solo inglese e il mio team non parla inglese"
+🌍 12. "The interface is English-only and my team doesn't speak English"
-I team nei paesi non anglofoni, soprattutto in America Latina, Asia ed Europa, hanno difficoltà con le interfacce solo in inglese. Le barriere linguistiche riducono l'adozione e aumentano gli errori di configurazione. +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. -**Come OmniRoute risolve il problema:** +**How OmniRoute solves it:** -- **Dashboard i18n — 30 lingue** — Tutti gli oltre 500 tasti tradotti tra cui arabo, bulgaro, danese, tedesco, spagnolo, finlandese, francese, ebraico, hindi, ungherese, indonesiano, italiano, giapponese, coreano, malese, olandese, norvegese, polacco, portoghese (PT/BR), rumeno, russo, slovacco, svedese, tailandese, ucraino, vietnamita, cinese, filippino, inglese -- **Supporto RTL**: supporto da destra a sinistra per arabo ed ebraico -- **README multilingue**: 30 traduzioni complete di documentazione -- **Selettore lingua**: icona del globo nell'intestazione per la commutazione in tempo reale +- **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. "Ho bisogno di qualcosa di più della semplice chat: ho bisogno di incorporamenti, immagini, audio"
+🔄 13. "I need more than chat — I need embeddings, images, audio"
-L'intelligenza artificiale non è solo il completamento della chat. Gli sviluppatori devono generare immagini, trascrivere audio, creare incorporamenti per RAG, riclassificare i documenti e moderare i contenuti. Ogni API ha un endpoint e un formato diversi. +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. -**Come OmniRoute risolve il problema:** +**How OmniRoute solves it:** -- **Incorporamenti** — `/v1/embeddings` con 6 fornitori e oltre 9 modelli -- **Generazione di immagini** — `/v1/images/generations` con 10 provider e oltre 20 modelli (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI) -- **Da testo a video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) e SD WebUI -- **Trasformazione testo in musica** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen) -- **Trascrizione audio** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3 -- **Sintesi vocale** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, Inworld, Cartesia, PlayHT, + fornitori esistenti -- **Moderazioni** — `/v1/moderations` — Controlli di sicurezza dei contenuti -- **Riclassificazione** — `/v1/rerank`: riclassificazione della pertinenza del documento -- **API di risposta**: supporto `/v1/responses` completo per Codex +- **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. "Non ho modo di testare e confrontare la qualità tra i modelli"
+🧪 14. "I have no way to test and compare quality across models"
-Gli sviluppatori vogliono sapere quale modello è il migliore per il loro caso d'uso (codice, traduzione, ragionamento), ma il confronto manuale è lento. Non esistono strumenti di valutazione integrati. +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. -**Come OmniRoute risolve il problema:** +**How OmniRoute solves it:** -- **Valutazioni LLM**: test Golden Set con 10 casi precaricati che coprono saluti, matematica, geografia, generazione di codice, conformità JSON, traduzione, ribasso, rifiuto di sicurezza -- **4 strategie di corrispondenza** — `exact`, `contains`, `regex`, `custom` (funzione JS) -- **Translator Playground Test Bench**: test in batch con input multipli e output previsti, confronto tra provider -- **Chat Tester**: andata e ritorno completo con rendering della risposta visiva -- **Live Monitor**: flusso in tempo reale di tutte le richieste che passano attraverso il proxy +- **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. "Ho bisogno di scalare senza perdere prestazioni"
+📈 15. "I need to scale without losing performance"
-Man mano che il volume delle richieste cresce, senza la memorizzazione nella cache le stesse domande generano costi duplicati. Senza idempotenza, le richieste duplicate sprecano elaborazione. I limiti tariffari per fornitore devono essere rispettati. +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. -**Come OmniRoute risolve il problema:** +**How OmniRoute solves it:** -- **Cache semantica**: la cache a due livelli (firma + semantica) riduce costi e latenza -- **Idempotenza richiesta**: finestra di deduplicazione di 5 secondi per richieste identiche -- **Rilevamento del limite di velocità**: RPM per provider, gap minimo e monitoraggio simultaneo massimo -- **Limiti di velocità modificabili**: impostazioni predefinite configurabili in Impostazioni → Resilienza con persistenza -- **Cache di convalida della chiave API**: cache a 3 livelli per prestazioni di produzione -- **Dashboard integrità con telemetria**: latenza p50/p95/p99, statistiche cache, tempo di attività +- **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 +- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence +- **API Key Validation Cache** — 3-tier cache for production performance +- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
-
🤖 16. "Voglio controllare il comportamento del modello a livello globale"
+🤖 16. "I want to control model behavior globally"
-Sviluppatori che desiderano tutte le risposte in una lingua specifica, con un tono specifico o che desiderano limitare i token di ragionamento. Configurarlo in ogni strumento/richiesta non è pratico. +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. -**Come OmniRoute risolve il problema:** +**How OmniRoute solves it:** -- **Inserimento prompt di sistema**: prompt globale applicato a tutte le richieste -- **Thinking Budget Validation**: controllo dell'allocazione dei token tramite ragionamento per richiesta (passthrough, automatico, personalizzato, adattivo) -- **6 Strategie di routing**: strategie globali che determinano la modalità di distribuzione delle richieste -- **Wildcard Router**: i modelli `provider/*` instradano dinamicamente a qualsiasi provider -- **Abilita/Disabilita combo**: attiva/disattiva le combo direttamente dalla dashboard -- **Attiva/disattiva provider**: attiva/disattiva tutte le connessioni per un provider con un clic -- **Fornitori bloccati**: esclude fornitori specifici dall'elenco `/v1/models` +- **System Prompt Injection** — Global prompt applied to all requests +- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive) +- **6 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 +- **Provider Toggle** — Enable/disable all connections for a provider with one click +- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
-
🧰 17. "Ho bisogno degli strumenti MCP come funzionalità di prodotto di prima classe"
+🧰 17. "I need MCP tools as first-class product capabilities"
-Molti gateway AI espongono MCP solo come dettaglio di implementazione nascosto. I team hanno bisogno di un livello operativo visibile e gestibile. +Many AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer. -**Come OmniRoute risolve il problema:** +**How OmniRoute solves it:** -- MCP viene visualizzato nella navigazione del dashboard e nella scheda del protocollo dell'endpoint -- Pagina di gestione MCP dedicata con processo, strumenti, ambiti e audit -- Avvio rapido integrato per `omniroute --mcp` e onboarding del client +- 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. "Ho bisogno dell'orchestrazione A2A con percorsi di attività di sincronizzazione + streaming"
+🧠 18. "I need A2A orchestration with sync + stream task paths"
-I flussi di lavoro degli agenti necessitano sia di risposte dirette che di esecuzione in streaming di lunga durata con controllo del ciclo di vita. +Agent workflows need both direct replies and long-running streamed execution with lifecycle control. -**Come OmniRoute risolve il problema:** +**How OmniRoute solves it:** -- Endpoint A2A JSON-RPC (`POST /a2a`) con `message/send` e `message/stream` -- Streaming SSE con propagazione dello stato terminale -- API del ciclo di vita delle attività per `tasks/get` e `tasks/cancel` +- 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. "Ho bisogno dello stato reale del processo MCP, non di uno stato indovinato"
+🛰️ 19. "I need real MCP process health, not guessed status"
-I team operativi devono sapere se MCP è effettivamente attivo, non solo se un'API è raggiungibile. +Operational teams need to know if MCP is actually alive, not just whether an API is reachable. -**Come OmniRoute risolve il problema:** +**How OmniRoute solves it:** -- File heartbeat di runtime con PID, timestamp, trasporto, conteggio strumenti e modalità ambito -- API di stato MCP che combina battito cardiaco + attività recente -- Schede di stato dell'interfaccia utente per l'aggiornamento di processo/tempo di attività/battito cardiaco +- 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. "Ho bisogno dell'esecuzione verificabile dello strumento MCP"
+📋 20. "I need auditable MCP tool execution"
-Quando gli strumenti modificano la configurazione o attivano azioni operative, i team necessitano di tracciabilità forense. +When tools mutate config or trigger ops actions, teams need forensic traceability. -**Come OmniRoute risolve il problema:** +**How OmniRoute solves it:** -- Registrazione di controllo supportata da SQLite per le chiamate allo strumento MCP -- Filtri per strumento, successo/fallimento, chiave API e impaginazione -- Tabella di controllo della dashboard + endpoint statistici per l'automazione +- 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. "Ho bisogno di autorizzazioni MCP con ambito per integrazione"
+🔐 21. "I need scoped MCP permissions per integration"
-Client diversi dovrebbero avere accesso con privilegi minimi alle categorie di strumenti. +Different clients should have least-privilege access to tool categories. -**Come OmniRoute risolve il problema:** +**How OmniRoute solves it:** -- 9 ambiti MCP granulari per l'accesso controllato agli strumenti -- Applicazione dell'ambito e visibilità nell'interfaccia utente di gestione MCP -- Postura predefinita sicura per gli strumenti operativi +- 9 granular MCP scopes for controlled tool access +- Scope enforcement and visibility in MCP management UI +- Safe default posture for operational tooling
-
⚙️ 22. "Ho bisogno di controlli operativi senza ridistribuirmi"
+⚙️ 22. "I need operational controls without redeploying"
-I team necessitano di rapidi cambiamenti di runtime durante incidenti o eventi di costo. +Teams need quick runtime changes during incidents or cost events. -**Come OmniRoute risolve il problema:** +**How OmniRoute solves it:** -- Cambia l'attivazione combinata direttamente dalla dashboard MCP -- Applicare profili di resilienza da pacchetti di policy predefiniti -- Ripristinare lo stato dell'interruttore dallo stesso pannello operativo +- Switch combo activation directly from MCP dashboard +- Apply resilience profiles from pre-defined policy packs +- Reset circuit breaker state from the same operations panel
-
🔄 23. "Ho bisogno di visibilità e cancellazione del ciclo di vita delle attività A2A in tempo reale"
+🔄 23. "I need live A2A task lifecycle visibility and cancellation"
-Senza visibilità del ciclo di vita, gli incidenti relativi alle attività diventano difficili da valutare. +Without lifecycle visibility, task incidents become hard to triage. -**Come OmniRoute risolve il problema:** +**How OmniRoute solves it:** -- Elenco/filtro delle attività per stato/competenza con impaginazione -- Esamina i metadati, gli eventi e gli artefatti delle attività -- Endpoint di annullamento dell'attività e azione dell'interfaccia utente con conferma +- 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. "Ho bisogno di metriche di flusso attive per il carico A2A"
+🌊 24. "I need active stream metrics for A2A load"
-I flussi di lavoro in streaming richiedono informazioni operative sulla concorrenza e sulle connessioni live. +Streaming workflows require operational insight into concurrency and live connections. -**Come OmniRoute risolve il problema:** +**How OmniRoute solves it:** -- Contatori di flussi attivi integrati nello stato A2A -- Timestamp dell'ultima attività e conteggi per stato -- Schede dashboard A2A per il monitoraggio delle operazioni in tempo reale +- Active stream counters integrated into A2A status +- Last task timestamp and per-state counts +- A2A dashboard cards for real-time ops monitoring
-
🪪 25. "Ho bisogno del rilevamento degli agenti standard per i clienti"
+🪪 25. "I need standard agent discovery for clients"
-I client e gli agenti di orchestrazione esterni necessitano di metadati leggibili dal computer per l'onboarding. +External clients and orchestrators need machine-readable metadata for onboarding. -**Come OmniRoute risolve il problema:** +**How OmniRoute solves it:** -- Carta Agente esposta a `/.well-known/agent.json` -- Capacità e competenze mostrate nell'interfaccia utente di gestione -- L'API di stato A2A include metadati di rilevamento per l'automazione +- Agent Card exposed at `/.well-known/agent.json` +- Capabilities and skills shown in management UI +- A2A status API includes discovery metadata for automation
-
🧭 26. "Ho bisogno della rilevabilità del protocollo nella UX del prodotto"
+🧭 26. "I need protocol discoverability in the product UX"
-Se gli utenti non riescono a scoprire le superfici del protocollo, l'adozione e la qualità del supporto diminuiscono. +If users cannot discover protocol surfaces, adoption and support quality drop. -**Come OmniRoute risolve il problema:** +**How OmniRoute solves it:** -- Voci della barra laterale per MCP e A2A -- Scheda Protocolli della pagina Endpoint con avvio rapido e stato -- Collegamenti dalla panoramica alle dashboard di gestione dedicate +- 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. "Ho bisogno della convalida del protocollo end-to-end con clienti reali"
+🧪 27. "I need end-to-end protocol validation with real clients"
-I test simulati non sono sufficienti per verificare la compatibilità del protocollo prima del rilascio. +Mock tests are not enough to validate protocol compatibility before release. -**Come OmniRoute risolve il problema:** +**How OmniRoute solves it:** -- Suite E2E che avvia l'app e utilizza il trasporto client SDK MCP reale -- Test client A2A per i flussi di rilevamento, invio, streaming, acquisizione e annullamento -- Effettuare un controllo incrociato delle asserzioni con l'audit MCP e le API delle attività A2A +- 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. "Ho bisogno di osservabilità unificata su tutte le interfacce"
+📡 28. "I need unified observability across all interfaces"
-Suddividere l'osservabilità per protocollo crea punti ciechi e un MTTR più lungo. +Splitting observability by protocol creates blind spots and longer MTTR. -**Come OmniRoute risolve il problema:** +**How OmniRoute solves it:** -- Dashboard/registri/analisi unificati in un unico prodotto -- Salute + audit + richiesta di telemetria su livelli OpenAI, MCP e A2A -- API operative per stato e automazione +- Unified dashboards/logs/analytics in one product +- Health + audit + request telemetry across OpenAI, MCP, and A2A layers +- Operational APIs for status and automation
-
💼 29. "Ho bisogno di un runtime per proxy + strumenti + orchestrazione agente"
+💼 29. "I need one runtime for proxy + tools + agent orchestration"
-L'esecuzione di numerosi servizi separati aumenta i costi operativi e le modalità di guasto. +Running many separate services increases operational cost and failure modes. -**Come OmniRoute risolve il problema:** +**How OmniRoute solves it:** -- Proxy compatibile con OpenAI, server MCP e server A2A in uno stack -- Autenticazione condivisa, resilienza, archivio dati e osservabilità -- Modello politico coerente su tutte le superfici di interazione +- 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
-
-### Playbook di esempio (casi d'uso integrati)
+### Example Playbooks (Integrated Use Cases)
-**Playbook A: massimizza l'abbonamento a pagamento + backup economico**
+**Playbook A: Maximize paid subscription + cheap backup**
```txt
Combo: "maximize-claude"
@@ -684,7 +694,7 @@ Monthly cost: $20 + small backup spend
Outcome: higher quality, near-zero interruption
```
-**Playbook B: stack di codifica a costo zero**
+**Playbook B: Zero-cost coding stack**
```txt
Combo: "free-forever"
@@ -696,7 +706,7 @@ Monthly cost: $0
Outcome: stable free coding workflow
```
-**Playbook C: catena di fallback sempre attiva 24 ore su 24, 7 giorni su 7**
+**Playbook C: 24/7 always-on fallback chain**
```txt
Combo: "always-on"
@@ -709,65 +719,132 @@ Combo: "always-on"
Outcome: deep fallback depth for deadline-critical workloads
```
-**Playbook D: operazioni dell'agente con MCP + A2A**
+**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/mcp and /dashboard/a2a
-4) Control incidents with resilience profile + task cancellation
+3) Observe via /dashboard/endpoint (MCP and A2A tabs)
+4) Toggle services via inline status controls
```
---
-## ⚡ Avvio Rapido
+## 🆓 Start Free — Zero Configuration Cost
-**1. Installa globalmente:**
+> 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 **iFlow** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |
+| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |
+| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |
+| 5 | `/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).
+
+## Avvio Rapido
+
+### 1) Install and run
```bash
npm install -g omniroute
omniroute
```
-🎉 La Dashboard si apre su `http://localhost:20128`
+> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:
+>
+> ```bash
+> pnpm install -g omniroute
+> pnpm approve-builds -g # Select all packages → approve
+> omniroute
+> ```
-| Comando | Descrizione |
-| ----------------------- | ------------------------------------------- |
-| `omniroute` | Avviare il server (porta predefinita 20128) |
-| `omniroute --port 3000` | Usare una porta personalizzata |
-| `omniroute --no-open` | Non aprire il browser automaticamente |
-| `omniroute --help` | Mostrare l'aiuto |
+Dashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.
-**2. Connetti un provider GRATUITO:**
+| 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 |
-Dashboard → Provider → Connetti **Claude Code** o **Antigravity** → Login OAuth → Fatto!
+Optional split-port mode:
-**3. Usa nel tuo strumento CLI:**
-
-```
-Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Impostazioni:
- Endpoint: http://localhost:20128/v1
- API Key: [copia dalla dashboard]
- Model: if/kimi-k2-thinking
+```bash
+PORT=20128 DASHBOARD_PORT=20129 omniroute
+# API: http://localhost:20128/v1
+# Dashboard: http://localhost:20129
```
-**Tutto qui!** Inizia a programmare con modelli IA GRATUITI.
+### 2) Connect providers and create your API key
-**Alternativa — eseguire dal codice sorgente:**
+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
+
+```txt
+Base URL: http://localhost:20128/v1
+API Key: [copy from Endpoint page]
+Model: if/kimi-k2-thinking (or any provider/model prefix)
+```
+
+Works with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.
+
+### 4) Enable and validate protocols (v2.0)
+
+**MCP (for tool-driven operations):**
+
+```bash
+omniroute --mcp
+```
+
+Then connect your MCP client over `stdio` and test tools like:
+
+- `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 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
+PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev
```
---
## 🐳 Docker
-OmniRoute è disponibile come immagine Docker pubblica su [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
+OmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
-**Avvio rapido:**
+**Quick run:**
```bash
docker run -d \
@@ -778,10 +855,10 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Con file di ambiente:**
+**With environment file:**
```bash
-# Copia e modifica il .env prima
+# Copy and edit .env first
cp .env.example .env
docker run -d \
@@ -793,295 +870,627 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Con Docker Compose:**
+**Using Docker Compose:**
```bash
-# Profilo base (senza strumenti CLI)
+# Base profile (no CLI tools)
docker compose --profile base up -d
-# Profilo CLI (Claude Code, Codex, OpenClaw integrati)
+# CLI profile (Claude Code, Codex, OpenClaw built-in)
docker compose --profile cli up -d
```
-| Immagine | Tag | Dimensione | Descrizione |
-| ------------------------ | -------- | ---------- | ----------------------- |
-| `diegosouzapw/omniroute` | `latest` | ~250MB | Ultima versione stabile |
-| `diegosouzapw/omniroute` | `1.0.6` | ~250MB | Versione attuale |
+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.
+- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.
+- 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` | `1.0.3` | ~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
+### Avvio Rapido
+
```bash
-npm run electron:dev # Development mode
+# 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)
+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)
---
-## 💰 Panoramica Prezzi
+## 💰 Pricing at a Glance
-| Tier | Provider | Costo | Reset Quota | Ideale Per |
-| ------------------ | ----------------- | ---------------------------- | --------------------- | ------------------------------- |
-| **💳 ABBONAMENTO** | Claude Code (Pro) | $20/mese | 5h + settimanale | Già abbonato |
-| | Codex (Plus/Pro) | $20-200/mese | 5h + settimanale | Utenti OpenAI |
-| | Gemini CLI | **GRATUITO** | 180K/mese + 1K/giorno | Tutti! |
-| | GitHub Copilot | $10-19/mese | Mensile | Utenti GitHub |
-| **🔑 API KEY** | NVIDIA NIM | **GRATUITO** (1000 crediti) | Una tantum | Test gratuiti |
-| | DeepSeek | A consumo | Nessuno | Miglior rapporto qualità-prezzo |
-| | Groq | Livello gratis + a pagamento | Limitato | Inferenza ultra-veloce |
-| | xAI (Grok) | A consumo | Nessuno | Modelli Grok |
-| | Mistral | Livello gratis + a pagamento | Limitato | IA Europea |
-| | OpenRouter | A consumo | Nessuno | 100+ modelli |
-| **💰 ECONOMICO** | GLM-4.7 | $0.6/1M | Giornaliero 10h | Backup economico |
-| | MiniMax M2.1 | $0.2/1M | Rotativo 5h | Opzione più economica |
-| | Kimi K2 | $9/mese fisso | 10M token/mese | Costo prevedibile |
-| **🆓 GRATUITO** | iFlow | $0 | Illimitato | 8 modelli gratuiti |
-| | Qwen | $0 | Illimitato | 3 modelli gratuiti |
-| | Kiro | $0 | Illimitato | Claude gratuito |
+| 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 |
+| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |
+| | 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** | iFlow | **$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 |
-**💡 Consiglio Pro:** Inizia con Gemini CLI (180K gratis/mese) + iFlow (illimitato gratis) = $0 di costo!
+> 🆕 **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
+iFlow (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.
---
-## 💡 Funzionalità Principali
+---
-### 🧠 Routing & Intelligenza
+## 🆓 Free Models — What You Actually Get
-| Funzionalità | Cosa Fa |
-| ---------------------------------------- | ----------------------------------------------------------------------------- |
-| 🎯 **Fallback intelligente 4 livelli** | Auto-routing: Abbonamento → API Key → Economico → Gratuito |
-| 📊 **Tracciamento quote in tempo reale** | Conteggio token live + countdown reset per provider |
-| 🔄 **Traduzione di formato** | OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro trasparente |
-| 👥 **Supporto multi-account** | Account multipli per provider con selezione intelligente |
-| 🔄 **Rinnovo automatico dei token** | I token OAuth si rinnovano automaticamente con retry |
-| 🎨 **Combo personalizzati** | 6 strategie: fill-first, round-robin, p2c, random, least-used, cost-optimized |
-| 🧩 **Modelli personalizzati** | Aggiungi qualsiasi ID modello a qualsiasi provider |
-| 🌐 **Router wildcard** | Instrada pattern `provider/*` verso qualsiasi provider dinamicamente |
-| 🧠 **Budget di ragionamento** | Modalità passthrough, auto, custom e adaptive per modelli di ragionamento |
-| 🔀 **Model Aliases** | Auto-forward deprecated model IDs to current replacements (built-in + custom) |
-| ⚡ **Background Degradation** | Auto-route background tasks (titles, summaries) to cheaper models |
-| 💬 **Iniezione System Prompt** | System prompt globale applicato a tutte le richieste |
-| 📄 **API Responses** | Supporto completo per OpenAI Responses API (`/v1/responses`) per Codex |
+> 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.
-### 🎵 API Multi-modali
+### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)
-| Funzionalità | Cosa Fa |
-| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 🖼️ **Generazione immagini** | `/v1/images/generations` — 4 provider, 9+ modelli |
-| 📐 **Embeddings** | `/v1/embeddings` — 6 provider, 9+ modelli |
-| 🎤 **Trascrizione audio** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |
-| 🔊 **Testo a voce** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) |
-| 🛡️ **Moderazioni** | `/v1/moderations` — Controlli di sicurezza |
-| 🔀 **Reranking** | `/v1/rerank` — Riclassificazione rilevanza documenti |
+| 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 |
-### 🛡️ Resilienza & Sicurezza
+### 🟢 IFLOW MODELS (Free OAuth — No Credit Card)
-| Funzionalità | Cosa Fa |
-| ------------------------------- | -------------------------------------------------------------------------------------- |
-| 🔌 **Circuit Breaker** | Apertura/chiusura auto per provider con soglie configurabili |
-| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |
-| 🛡️ **Anti-Thundering Herd** | Mutex + semaforo rate-limit per provider con API key |
-| 🧠 **Cache semantica** | Cache a due livelli (firma + semantica) riduce costi e latenza |
-| ⚡ **Idempotenza richieste** | Finestra dedup 5s per richieste duplicate |
-| 🔒 **Spoofing TLS Fingerprint** | Bypass rilevamento bot tramite wreq-js |
-| 🔏 **CLI Fingerprint Matching** | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP** |
-| 🌐 **Filtro IP** | Allowlist/blocklist per controllo accesso API |
-| 📊 **Rate limit modificabili** | RPM, gap minimo e concorrenza massima configurabili |
-| 💾 **Rate Limit Persistence** | Learned limits survive restarts via SQLite with 60s debounce + 24h staleness |
-| 🔄 **Token Refresh Resilience** | Per-provider circuit breaker (5 fails→30min) + 30s timeout per attempt |
+| 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 |
-### 📊 Osservabilità & Analytics
+### 🟡 QWEN MODELS (Device Code Auth)
-| Funzionalità | Cosa Fa |
-| -------------------------------- | ------------------------------------------------------------ |
-| 📝 **Log richieste** | Modalità debug con log completi richiesta/risposta |
-| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |
-| 💾 **Log SQLite** | Log proxy persistenti che sopravvivono ai riavvii |
-| 📊 **Dashboard analytics** | Recharts: card statistiche, grafico uso, tabella provider |
-| 📈 **Tracciamento progresso** | Eventi SSE di progresso opt-in per lo streaming |
-| 🧪 **Valutazioni LLM** | Test con golden set e 4 strategie di corrispondenza |
-| 🔍 **Telemetria richieste** | Aggregazione latenza p50/p95/p99 + tracciamento X-Request-Id |
-| 📋 **Log + Quote** | Pagine dedicate per navigazione log e tracciamento quote |
-| 🏥 **Dashboard salute** | Uptime, stati circuit breaker, lockout, statistiche cache |
-| 💰 **Tracciamento costi** | Gestione budget + configurazione prezzi per modello |
+| 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) |
-### ☁️ Deploy & Sincronizzazione
+### 🟣 GEMINI CLI (Google OAuth)
-| Funzionalità | Cosa Fa |
-| -------------------------------- | -------------------------------------------------------------------------------- |
-| 💾 **Cloud Sync** | Sincronizza impostazioni tra dispositivi via Cloudflare Workers |
-| 🌐 **Deploy ovunque** | Localhost, VPS, Docker, Cloudflare Workers |
-| 🔑 **Gestione API Key** | Genera, ruota e limita API key per provider |
-| 🧙 **Assistente configurazione** | Setup guidato in 4 passaggi per nuovi utenti |
-| 🔧 **Dashboard CLI Tools** | Configurazione con un clic per Claude, Codex, Cline, OpenClaw, Kilo, Antigravity |
-| 🔄 **Backup DB** | Backup e ripristino automatici di tutte le impostazioni |
+| Model | Prefix | Limit | Rate Limit |
+| ------------------------ | ------ | --------------------------- | ------------- |
+| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |
+| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |
+
+### ⚫ 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
+> iFlow (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 v2.0 is built as an operational platform, not just a relay proxy.
+
+### 🆕 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 Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |
+| 🤖 **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 (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) |
+| 🤝 **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** | 9 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 combo, apply resilience profiles, reset breakers from one control surface |
+
+### 🧠 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** | 6 balancing strategies + fallback chain control |
+| 🌐 **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) |
+| 💬 **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 |
+| ----------------------------------- | -------------------------------------------------------------------------------------- |
+| 🔌 **Circuit Breakers** | Per-model trip/recover with threshold controls |
+| 🎯 **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 |
+| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |
+| 🔑 **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 |
+
+### 📊 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 |
+| 📋 **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 |
+
+### ☁️ Deployment & Platform
+
+| Feature | What It Does |
+| ----------------------------- | --------------------------------------------------------- |
+| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |
+| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |
+| 💾 **Cloud Sync** | Configuration sync via cloud worker |
+| 🔄 **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 |
+
+### Feature Deep Dive
+
+#### Smart fallback with practical cost control
+
+```txt
+Combo: "my-coding-stack"
+ 1. cc/claude-opus-4-6
+ 2. nvidia/llama-3.3-70b
+ 3. glm/glm-4.7
+ 4. if/kimi-k2-thinking
+```
+
+When quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.
+
+#### 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)
+
+#### 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)
🚀 30. "Ho bisogno di spedire flussi di lavoro di agenti senza la proliferazione del codice adesivo"
+🚀 30. "I need to ship agentic workflows without glue-code sprawl"
-I team perdono velocità quando uniscono più servizi e script ad hoc. +Teams lose velocity when stitching multiple ad-hoc services and scripts. -**Come OmniRoute risolve il problema:** +**How OmniRoute solves it:** -- Strategia endpoint unificata per clienti e agenti -- Interfacce utente di gestione del protocollo integrate e percorsi di convalida del fumo -- Fondamenti pronti per la produzione (sicurezza, registrazione, resilienza, backup) +- Unified endpoint strategy for clients and agents +- Built-in protocol management UIs and smoke validation paths +- Production-ready foundations (security, logging, resilience, backup)
-
-## 🧪 Valutazioni (Evals)
+📖 Dettagli funzionalità
+🧩 MCP Setup (Model Context Protocol)
-### 🎯 Fallback intelligente 4 livelli +Start MCP transport in stdio mode: -Crea combo con fallback automatico: - -``` -Combo: "my-coding-stack" - 1. cc/claude-opus-4-6 (il tuo abbonamento) - 2. nvidia/llama-3.3-70b (API NVIDIA gratuita) - 3. glm/glm-4.7 (backup economico, $0.6/1M) - 4. if/kimi-k2-thinking (fallback gratuito) - -→ Cambia automaticamente quando la quota si esaurisce o si verificano errori +```bash +omniroute --mcp ``` -### 📊 Tracciamento quote in tempo reale +Recommended validation flow: -- Consumo token per provider -- Countdown reset (5 ore, giornaliero, settimanale) -- Stima dei costi per livelli a pagamento -- Report spese mensili +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. -### 🔄 Traduzione di formato +Useful APIs for automation: -Traduzione trasparente tra formati: - -- **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **OpenAI Responses** -- Il tuo CLI invia in formato OpenAI → OmniRoute traduce → Il provider riceve il formato nativo -- Funziona con qualsiasi strumento che supporti endpoint OpenAI personalizzati - -### 👥 Supporto multi-account - -- Aggiungi account multipli per provider -- Round-robin automatico o routing per priorità -- Fallback all'account successivo quando la quota viene raggiunta - -### 🔄 Rinnovo automatico dei token - -- I token OAuth si rinnovano automaticamente prima della scadenza -- Nessuna necessità di ri-autenticazione manuale -- Esperienza trasparente su tutti i provider - -### 🎨 Combo personalizzati - -- Crea combinazioni di modelli illimitate -- 6 strategie: fill-first, round-robin, power-of-two-choices, random, least-used, cost-optimized -- Condividi combo tra dispositivi con Cloud Sync - -### 🏥 Dashboard salute - -- Stato del sistema (uptime, versione, utilizzo memoria) -- Stati circuit breaker per provider (Closed/Open/Half-Open) -- Stato rate limit e lockout attivi -- Statistiche cache firme -- Telemetria latenza (p50/p95/p99) + cache prompt -- Reset salute con un clic - -### 🔧 Playground del traduttore - -- Debug, test e visualizzazione delle traduzioni di formato API -- Invia richieste e vedi come OmniRoute traduce tra formati dei provider -- Inestimabile per risolvere problemi di integrazione - -### 💾 Cloud Sync - -- Sincronizza provider, combo e impostazioni tra dispositivi -- Sincronizzazione in background automatica -- Archiviazione criptata sicura +- `GET /api/mcp/status` +- `GET /api/mcp/tools` +- `GET /api/mcp/audit` +- `GET /api/mcp/audit/stats`
+
🤝 A2A Setup (Agent2Agent)
-OmniRoute include un framework di valutazione integrato per testare la qualità delle risposte LLM contro un golden set. Accesso via **Analytics → Evals** nella dashboard. +Discover the agent: -### Set integrato +```bash +curl http://localhost:20128/.well-known/agent.json +``` -Il "OmniRoute Golden Set" precaricato contiene 10 casi di test: +Send a task: -- Saluti, matematica, geografia, generazione codice -- Conformità formato JSON, traduzione, markdown -- Rifiuto sicurezza (contenuto nocivo), conteggio, logica booleana +```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."}]}}' +``` -### Strategie di valutazione +Manage lifecycle: -| Strategia | Descrizione | Esempio | -| ---------- | ---------------------------------------------------------- | -------------------------------- | -| `exact` | L'output deve corrispondere esattamente | `"4"` | -| `contains` | L'output deve contenere la sottostringa (case-insensitive) | `"Paris"` | -| `regex` | L'output deve corrispondere al pattern regex | `"1.*2.*3"` | -| `custom` | Funzione JS personalizzata restituisce true/false | `(output) => output.length > 10` | +- `GET /api/a2a/status` +- `GET /api/a2a/tasks` +- `GET /api/a2a/tasks/:id` +- `POST /api/a2a/tasks/:id/cancel` ---- +Operational UI: -## 📖 Guida alla Configurazione +- `/dashboard/a2a` for task/state/stream observability and smoke actions + +
-
+
+💳 Provider per abbonamento
+🧪 End-to-end protocol validation
+ +Validate both protocols with real clients: + +```bash +npm run test:protocols:e2e +``` + +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) ```bash -Dashboard → Provider → Connetti Claude Code -→ Login OAuth → Rinnovo automatico token -→ Tracciamento quota 5h + settimanale +Dashboard → Providers → Connect Claude Code +→ OAuth login → Auto token refresh +→ 5-hour + weekly quota tracking -Modelli: +Models: cc/claude-opus-4-6 cc/claude-sonnet-4-5-20250929 cc/claude-haiku-4-5-20251001 ``` -**Consiglio Pro:** Usa Opus per compiti complessi, Sonnet per velocità. OmniRoute traccia la quota per modello! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! ### OpenAI Codex (Plus/Pro) ```bash -Dashboard → Provider → Connetti Codex -→ Login OAuth (porta 1455) -→ Reset 5h + settimanale +Dashboard → Providers → Connect Codex +→ OAuth login (port 1455) +→ 5-hour + weekly reset -Modelli: +Models: cx/gpt-5.2-codex cx/gpt-5.1-codex-max ``` -### Gemini CLI (GRATUITO 180K/mese!) +#### 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). + +### Gemini CLI (FREE 180K/month!) ```bash -Dashboard → Provider → Connetti Gemini CLI +Dashboard → Providers → Connect Gemini CLI → Google OAuth -→ 180K completions/mese + 1K/giorno +→ 180K completions/month + 1K/day -Modelli: +Models: gc/gemini-3-flash-preview gc/gemini-2.5-pro ``` -**Miglior valore:** Livello gratuito enorme! Usa prima dei livelli a pagamento. +**Best Value:** Huge free tier! Use this before paid tiers. ### GitHub Copilot ```bash -Dashboard → Provider → Connetti GitHub +Dashboard → Providers → Connect GitHub → OAuth via GitHub -→ Reset mensile (1° del mese) +→ Monthly reset (1st of month) -Modelli: +Models: gh/gpt-5 gh/claude-4.5-sonnet gh/gemini-3-pro @@ -1090,95 +1499,95 @@ Modelli:
-
🔑 Provider per API Key
+🔑 API Key Providers
-### NVIDIA NIM (GRATUITO 1000 crediti!) +### NVIDIA NIM (FREE developer access — 70+ models) -1. Registrati: [build.nvidia.com](https://build.nvidia.com) -2. Ottieni una API key gratuita (1000 crediti di inferenza inclusi) -3. Dashboard → Aggiungi Provider → NVIDIA NIM: +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` -**Modelli:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct` e 50+ altri +**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more -**Consiglio Pro:** API compatibile OpenAI — funziona perfettamente con la traduzione di formato di OmniRoute! +**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation! ### DeepSeek -1. Registrati: [platform.deepseek.com](https://platform.deepseek.com) -2. Ottieni una API key -3. Dashboard → Aggiungi Provider → DeepSeek +1. Sign up: [platform.deepseek.com](https://platform.deepseek.com) +2. Get API key +3. Dashboard → Add Provider → DeepSeek -**Modelli:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` +**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` -### Groq (Livello gratuito disponibile!) +### Groq (Free Tier Available!) -1. Registrati: [console.groq.com](https://console.groq.com) -2. Ottieni una API key (livello gratuito incluso) -3. Dashboard → Aggiungi Provider → Groq +1. Sign up: [console.groq.com](https://console.groq.com) +2. Get API key (free tier included) +3. Dashboard → Add Provider → Groq -**Modelli:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` +**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` -**Consiglio Pro:** Inferenza ultra-veloce — ideale per programmazione in tempo reale! +**Pro Tip:** Ultra-fast inference — best for real-time coding! -### OpenRouter (100+ modelli) +### OpenRouter (100+ Models) -1. Registrati: [openrouter.ai](https://openrouter.ai) -2. Ottieni una API key -3. Dashboard → Aggiungi Provider → OpenRouter +1. Sign up: [openrouter.ai](https://openrouter.ai) +2. Get API key +3. Dashboard → Add Provider → OpenRouter -**Modelli:** Accesso a 100+ modelli da tutti i principali provider tramite una singola API key. +**Models:** Access 100+ models from all major providers through a single API key.
-
💰 Provider economici (Backup)
+💰 Cheap Providers (Backup)
-### GLM-4.7 (Reset giornaliero, $0.6/1M) +### GLM-4.7 (Daily reset, $0.6/1M) -1. Registrati: [Zhipu AI](https://open.bigmodel.cn/) -2. Ottieni la API key dal Coding Plan -3. Dashboard → Aggiungi API Key: +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` -**Usa:** `glm/glm-4.7` +**Use:** `glm/glm-4.7` -**Consiglio Pro:** Il Coding Plan offre 3× quota a 1/7 del costo! Reset giornaliero alle 10:00. +**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -### MiniMax M2.1 (Reset 5h, $0.20/1M) +### MiniMax M2.1 (5h reset, $0.20/1M) -1. Registrati: [MiniMax](https://www.minimax.io/) -2. Ottieni una API key -3. Dashboard → Aggiungi API Key +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key +3. Dashboard → Add API Key -**Usa:** `minimax/MiniMax-M2.1` +**Use:** `minimax/MiniMax-M2.1` -**Consiglio Pro:** L'opzione più economica per contesto lungo (1M token)! +**Pro Tip:** Cheapest option for long context (1M tokens)! -### Kimi K2 ($9/mese fisso) +### Kimi K2 ($9/month flat) -1. Abbonati: [Moonshot AI](https://platform.moonshot.ai/) -2. Ottieni una API key -3. Dashboard → Aggiungi API Key +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key +3. Dashboard → Add API Key -**Usa:** `kimi/kimi-latest` +**Use:** `kimi/kimi-latest` -**Consiglio Pro:** $9/mese fisso per 10M token = $0.90/1M di costo effettivo! +**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
-
🆓 Provider GRATUITI (Backup d'emergenza)
+🆓 FREE Providers (Emergency Backup)
-### iFlow (8 modelli GRATUITI) +### iFlow (5 FREE models via OAuth) ```bash -Dashboard → Connetti iFlow -→ Login OAuth iFlow -→ Utilizzo illimitato +Dashboard → Connect iFlow +→ iFlow OAuth login +→ Unlimited usage -Modelli: +Models: if/kimi-k2-thinking if/qwen3-coder-plus if/glm-4.7 @@ -1186,26 +1595,26 @@ Modelli: if/deepseek-r1 ``` -### Qwen (3 modelli GRATUITI) +### Qwen (4 FREE models via Device Code) ```bash -Dashboard → Connetti Qwen -→ Autorizzazione con codice dispositivo -→ Utilizzo illimitato +Dashboard → Connect Qwen +→ Device code authorization +→ Unlimited usage -Modelli: +Models: qw/qwen3-coder-plus qw/qwen3-coder-flash ``` -### Kiro (Claude GRATUITO) +### Kiro (Claude FREE) ```bash -Dashboard → Connetti Kiro -→ AWS Builder ID o Google/GitHub -→ Utilizzo illimitato +Dashboard → Connect Kiro +→ AWS Builder ID or Google/GitHub +→ Unlimited usage -Modelli: +Models: kr/claude-sonnet-4.5 kr/claude-haiku-4.5 ``` @@ -1213,51 +1622,51 @@ Modelli:
-
🎨 Creare combo
+🎨 Create Combos
-### Esempio 1: Massimizzare abbonamento → Backup economico +### Example 1: Maximize Subscription → Cheap Backup ``` -Dashboard → Combo → Crea nuovo +Dashboard → Combos → Create New -Nome: premium-coding -Modelli: - 1. cc/claude-opus-4-6 (Abbonamento principale) - 2. glm/glm-4.7 (Backup economico, $0.6/1M) - 3. minimax/MiniMax-M2.1 (Fallback più economico, $0.20/1M) +Name: premium-coding +Models: + 1. cc/claude-opus-4-6 (Subscription primary) + 2. glm/glm-4.7 (Cheap backup, $0.6/1M) + 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M) -Usa nel CLI: premium-coding +Use in CLI: premium-coding ``` -### Esempio 2: Solo gratuiti (Costo zero) +### Example 2: Free-Only (Zero Cost) ``` -Nome: free-combo -Modelli: - 1. gc/gemini-3-flash-preview (180K gratis/mese) - 2. if/kimi-k2-thinking (illimitato) - 3. qw/qwen3-coder-plus (illimitato) +Name: free-combo +Models: + 1. gc/gemini-3-flash-preview (180K free/month) + 2. if/kimi-k2-thinking (unlimited) + 3. qw/qwen3-coder-plus (unlimited) -Costo: $0 per sempre! +Cost: $0 forever! ```
-
---
-## 🐛 Risoluzione Problemi
+## Risoluzione dei Problemi
🔧 Integrazione CLI
+🔧 CLI Integration
### Cursor IDE ``` -Impostazioni → Modelli → Avanzato: +Settings → Models → Advanced: OpenAI API Base URL: http://localhost:20128/v1 - OpenAI API Key: [dalla dashboard OmniRoute] + OpenAI API Key: [from OmniRoute dashboard] Model: cc/claude-opus-4-6 ``` ### Claude Code -Usa la pagina **CLI Tools** nella dashboard per la configurazione con un clic, o modifica `~/.claude/settings.json` manualmente. +Use the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually. ### Codex CLI @@ -1270,13 +1679,13 @@ codex "your prompt" ### OpenClaw -**Opzione 1 — Dashboard (consigliato):** +**Option 1 — Dashboard (recommended):** ``` -Dashboard → CLI Tools → OpenClaw → Seleziona Modello → Applica +Dashboard → CLI Tools → OpenClaw → Select Model → Apply ``` -**Opzione 2 — Manuale:** Modifica `~/.openclaw/openclaw.json`: +**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`: ```json { @@ -1292,155 +1701,420 @@ Dashboard → CLI Tools → OpenClaw → Seleziona Modello → Applica } ``` -> **Nota:** OpenClaw funziona solo con OmniRoute locale. Usa `127.0.0.1` invece di `localhost` per evitare problemi di risoluzione IPv6. +> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues. ### Cline / Continue / RooCode ``` -Impostazioni → Configurazione API: +Settings → API Configuration: Provider: OpenAI Compatible Base URL: http://localhost:20128/v1 - API Key: [dalla dashboard OmniRoute] + 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. +
-
-- **Runtime**: Node.js 20+
-- **Linguaggio**: TypeScript 5.9 — **100% TypeScript** in `src/` e `open-sse/` (v1.0.6)
+## 🛠️ Tech Stack
+
+Clicca per espandere la guida alla risoluzione problemi
+Click to expand troubleshooting guide
**"Language model did not provide messages"** -- Quota del provider esaurita → Controlla il tracker quote nella dashboard -- Soluzione: Usa un combo con fallback o passa a un livello più economico +- Provider quota exhausted → Check dashboard quota tracker +- Solution: Use combo fallback or switch to cheaper tier **Rate limiting** -- Quota abbonamento esaurita → Fallback a GLM/MiniMax -- Aggiungi combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Subscription quota out → Fallback to GLM/MiniMax +- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -**Token OAuth scaduto** +**OAuth token expired** -- Rinnovato automaticamente da OmniRoute -- Se il problema persiste: Dashboard → Provider → Riconnetti +- Auto-refreshed by OmniRoute +- If issues persist: Dashboard → Provider → Reconnect -**Costi elevati** +**High costs** -- Controlla le statistiche di utilizzo in Dashboard → Costi -- Cambia il modello principale a GLM/MiniMax -- Usa il livello gratuito (Gemini CLI, iFlow) per compiti non critici +- Check usage stats in Dashboard → Costs +- Switch primary model to GLM/MiniMax +- Use free tier (Gemini CLI, iFlow) for non-critical tasks -**La dashboard si apre sulla porta sbagliata** +**Dashboard/API ports are wrong** -- Imposta `PORT=20128` e `NEXT_PUBLIC_BASE_URL=http://localhost:20128` +- `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) -**Errori cloud sync** +**Cloud sync errors** -- Verifica che `BASE_URL` punti alla tua istanza in esecuzione -- Verifica che `CLOUD_URL` punti all'endpoint cloud previsto -- Mantieni i valori `NEXT_PUBLIC_*` allineati con i valori del server +- 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 -**Il primo login non funziona** +**First login not working** -- Controlla `INITIAL_PASSWORD` nel `.env` -- Se non impostata, la password predefinita è `123456` +- Check `INITIAL_PASSWORD` in `.env` +- If unset, fallback password is `123456` -**Nessun log delle richieste** +**No request logs** -- Imposta `ENABLE_REQUEST_LOGS=true` nel `.env` +- Set `ENABLE_REQUEST_LOGS=true` in `.env` -**Il test di connessione mostra "Invalid" per provider compatibili OpenAI** +**Connection test shows "Invalid" for OpenAI-compatible providers** -- Molti provider non espongono l'endpoint `/models` -- OmniRoute v1.0.6+ include validazione fallback tramite chat completions -- Assicurati che la URL base includa il suffisso `/v1` +- 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** + +#### Why does Antigravity / Gemini CLI OAuth fail on remote servers? + +The **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console. + +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 + +# For Gemini CLI: +GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com +GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +``` + +**6. Restart OmniRoute** + +```bash +# npm: +npm run dev + +# Docker: +docker restart omniroute +``` + +**7. Try connecting again** + +Dashboard → Providers → Antigravity (or Gemini CLI) → OAuth + +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. + +--- + +
+
---
-## 🛠️
+🇧🇷 Versão em Português
+ +#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos? + +Os provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo. + +As credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticação com: + +``` +Error 400: redirect_uri_mismatch +``` + +#### Solução: Configure suas próprias credenciais OAuth + +Você precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor. + +#### Passo a passo + +**1. Acesse o Google Cloud Console** + +Abra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) + +**2. Crie um novo OAuth 2.0 Client ID** + +- Clique em **"+ Create Credentials"** → **"OAuth client ID"** +- Tipo de aplicativo: **"Web application"** +- Nome: escolha qualquer nome (ex: `OmniRoute Remote`) + +**3. Adicione as Authorized Redirect URIs** + +No campo **"Authorized redirect URIs"**, adicione: + +``` +https://seu-servidor.com/callback +``` + +> Substitua `seu-servidor.com` pelo domínio ou IP do seu servidor (inclua a porta se necessário, ex: `http://45.33.32.156:20128/callback`). + +**4. Salve e copie as credenciais** + +Após criar, o Google mostrará o **Client ID** e o **Client Secret**. + +**5. Configure as variáveis de ambiente** + +No seu `.env` (ou nas variáveis de ambiente do Docker): + +```bash +# Para Antigravity: +ANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com +ANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret + +# Para Gemini CLI: +GEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com +GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret +GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret +``` + +**6. Reinicie o OmniRoute** + +```bash +# Se usando npm: +npm run dev + +# Se usando Docker: +docker restart omniroute +``` + +**7. Tente conectar novamente** + +Dashboard → Providers → Antigravity (ou Gemini CLI) → OAuth + +Agora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará. + +--- + +#### Workaround temporário (sem configurar credenciais próprias) + +Se não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**: + +1. O OmniRoute abrirá a URL de autorização do Google +2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto) +3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue) +4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute +5. Clique em **"Connect"** + +> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.
+
---
-## 📖 Documentazione
+## Documentazione
-| Documento | Descrizione |
-| ----------------------------------------------- | -------------------------------------------------- |
-| [Guida Utente](docs/USER_GUIDE.md) | Provider, combo, integrazione CLI, deploy |
-| [Riferimento API](docs/API_REFERENCE.md) | Tutti gli endpoint con esempi |
-| [Risoluzione Problemi](docs/TROUBLESHOOTING.md) | Problemi comuni e soluzioni |
-| [Architettura](docs/ARCHITECTURE.md) | Architettura del sistema e dettagli interni |
-| [Come Contribuire](CONTRIBUTING.md) | Setup di sviluppo e linee guida |
-| [Spec OpenAPI](docs/openapi.yaml) | Specifica OpenAPI 3.0 |
-| [Politica di Sicurezza](SECURITY.md) | Segnalazione vulnerabilità e pratiche di sicurezza |
+| Document | Description |
+| ---------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 16 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/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
+| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
-## 🗺️
+## 🗺️ Roadmap
-## 👥 Contributori
+OmniRoute has **210+ 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, P2C account selection |
+| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |
+| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |
+| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider 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
[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
-### Come Contribuire
+### How to Contribute
-1. Fai il fork del repository
-2. Crea il tuo branch di funzionalità (`git checkout -b feature/amazing-feature`)
-3. Fai il commit delle modifiche (`git commit -m 'Add amazing feature'`)
-4. Fai il push al branch (`git push origin feature/amazing-feature`)
-5. Apri una Pull Request
+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
-Consulta [CONTRIBUTING.md](CONTRIBUTING.md) per le linee guida dettagliate.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
-### Rilasciare una nuova versione
+### Releasing a New Version
```bash
-# Crea un rilascio — la pubblicazione npm avviene automaticamente
-gh release create v1.0.6 --title "v1.0.6" --generate-notes
+# Create a release — npm publish happens automatically
+gh release create v2.0.0 --title "v2.0.0" --generate-notes
```
---
-## 📊 Cronologia Stelle
+## 📊 Star History
## Stargazers over time
## [](https://starchart.cc/diegosouzapw/OmniRoute)
-## 🙏 Ringraziamenti
+## 🙏 Acknowledgments
-Un ringraziamento speciale a **[9router](https://github.com/decolua/9router)** di **[decolua](https://github.com/decolua)** — il progetto originale che ha ispirato questo fork. OmniRoute si costruisce su quell'incredibile base con funzionalità aggiuntive, API multi-modali e una riscrittura completa in TypeScript.
+Special thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.
-Un ringraziamento speciale a **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — l'implementazione originale in Go che ha ispirato questo porting in JavaScript.
+Special thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.
---
-## 📄 Licenza
+## Licenza
-Licenza MIT — vedi [LICENSE](LICENSE) per i dettagli.
+MIT License - see [LICENSE](LICENSE) for details.
---
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**: LowDB (JSON) + SQLite (stato dominio + log proxy) +- **Database**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions) +- **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 -- **Testing**: Node.js test runner (368+ test unitari) -- **CI/CD**: GitHub Actions (pubblicazione automatica npm + Docker Hub al rilascio) -- **Sito Web**: [omniroute.online](https://omniroute.online) -- **Pacchetto**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute) +- **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) -- **Resilienza**: Circuit breaker, backoff esponenziale, anti-thundering herd, TLS spoofing +- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing + +
- Fatto con ❤️ per gli sviluppatori che programmano 24/7
+ Built with ❤️ for developers who code 24/7
omniroute.online
+
diff --git a/docs/i18n/it/docs/FEATURES.md b/docs/i18n/it/docs/FEATURES.md
new file mode 100644
index 0000000000..ad12da09c2
--- /dev/null
+++ b/docs/i18n/it/docs/FEATURES.md
@@ -0,0 +1,145 @@
+# OmniRoute — Dashboard Features Gallery (Italiano)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/FEATURES.md) · 🇪🇸 [es](../../es/docs/FEATURES.md) · 🇫🇷 [fr](../../fr/docs/FEATURES.md) · 🇩🇪 [de](../../de/docs/FEATURES.md) · 🇮🇹 [it](../../it/docs/FEATURES.md) · 🇷🇺 [ru](../../ru/docs/FEATURES.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FEATURES.md) · 🇯🇵 [ja](../../ja/docs/FEATURES.md) · 🇰🇷 [ko](../../ko/docs/FEATURES.md) · 🇸🇦 [ar](../../ar/docs/FEATURES.md) · 🇮🇳 [in](../../in/docs/FEATURES.md) · 🇹🇭 [th](../../th/docs/FEATURES.md) · 🇻🇳 [vi](../../vi/docs/FEATURES.md) · 🇮🇩 [id](../../id/docs/FEATURES.md) · 🇲🇾 [ms](../../ms/docs/FEATURES.md) · 🇳🇱 [nl](../../nl/docs/FEATURES.md) · 🇵🇱 [pl](../../pl/docs/FEATURES.md) · 🇸🇪 [sv](../../sv/docs/FEATURES.md) · 🇳🇴 [no](../../no/docs/FEATURES.md) · 🇩🇰 [da](../../da/docs/FEATURES.md) · 🇫🇮 [fi](../../fi/docs/FEATURES.md) · 🇵🇹 [pt](../../pt/docs/FEATURES.md) · 🇷🇴 [ro](../../ro/docs/FEATURES.md) · 🇭🇺 [hu](../../hu/docs/FEATURES.md) · 🇧🇬 [bg](../../bg/docs/FEATURES.md) · 🇸🇰 [sk](../../sk/docs/FEATURES.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FEATURES.md) · 🇮🇱 [he](../../he/docs/FEATURES.md) · 🇵🇭 [phi](../../phi/docs/FEATURES.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FEATURES.md)
+
+---
+
+Visual guide to every section of the OmniRoute dashboard.
+
+---
+
+## 🔌 Providers
+
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
+
+
+
+---
+
+## 🎨 Combos
+
+Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
+
+
+
+---
+
+## 📊 Analytics
+
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
+
+
+
+---
+
+## 🏥 System Health
+
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+
+
+
+---
+
+## 🔧 Translator Playground
+
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
+
+
+
+---
+
+## 🎮 Model Playground _(v2.0.9+)_
+
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
+
+---
+
+## 🎨 Themes _(v2.0.5+)_
+
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
+
+## ⚙️ Settings
+
+Comprehensive settings panel with tabs:
+
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning
+- **Advanced** — Configuration overrides
+
+
+
+---
+
+## 🔧 CLI Tools
+
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
+
+
+
+---
+
+## 🤖 CLI Agents _(v2.0.11+)_
+
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
+
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
+
+---
+
+## 🖼️ Media _(v2.0.3+)_
+
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
+
+## 📝 Request Logs
+
+Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
+
+
+
+---
+
+## 🌐 API Endpoint
+
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
+
+
+
+---
+
+## 🔑 API Key Management
+
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
+
+---
+
+## 📋 Audit Log
+
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
+
+---
+
+## 🖥️ Desktop Application
+
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
+
+Key features:
+
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
+
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.
diff --git a/docs/i18n/ja/README.md b/docs/i18n/ja/README.md
index 14e562a8e7..492aecaae9 100644
--- a/docs/i18n/ja/README.md
+++ b/docs/i18n/ja/README.md
@@ -1,24 +1,94 @@
-omniroute.online
-
-
- # 🚀 OmniRoute — 無料の AI ゲートウェイ
+# 🚀 OmniRoute — The Free AI Gateway (日本語)
-### コーディングを決してやめないでください。自動フォールバックを備えた **無料および低コストの AI モデル**へのスマート ルーティング。
-
-_ユニバーサル API プロキシ — 1 つのエンドポイント、36 以上のプロバイダー、ダウンタイムなし。_
-
-**チャット補完 • 埋め込み • 画像生成 • オーディオ • 再ランキング • 100% TypeScript **
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 お気に入りのコーディング エージェント向けの無料 AI プロバイダー
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_AI を活用した IDE または CLI ツールを、無制限のコーディングのための無料 API ゲートウェイである OmniRoute 経由で接続します。_
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+` tags no longer leak to clients in SSE streaming responses (#585) |
+| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with per-provider/account quota enforcement, idempotency, SHA-256 storage, and optional GitHub issue reporting |
+| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG → generic fallback chain |
+| 🔄 **Model Auto-Sync** | 24h scheduler and manual UI toggle to sync model lists for built-in and custom OpenAI-compatible providers |
+| 🌐 **OpenCode Zen/Go** | Two new providers from @kang-heewon via PR #530: free tier + subscription tier via `OpencodeExecutor` |
+| 🐛 **Gemini CLI OAuth** | Actionable error when `GEMINI_OAUTH_CLIENT_SECRET` is missing in Docker (was cryptic Google error) |
+| 🐛 **OpenCode config** | `saveOpenCodeConfig()` now correctly writes TOML to `XDG_CONFIG_HOME` |
+| 🐛 **Pinned model override** | `body.model` correctly set to `pinnedModel` on context-cache protection |
+| 🐛 **Codex/Claude loop** | `tool_result` blocks now converted to text to stop infinite loops |
+| 🐛 **Login redirect** | Login no longer freezes after skipping password setup |
+| 🐛 **Windows paths** | MSYS2/Git-Bash paths (`/c/...`) normalized to `C:\...` automatically |
+
+---
+
+## 🖼️ Main Dashboard
+
+
-📡 すべてのエージェントは ` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**Stop wasting money and hitting limits:**
-### 🆕 What's New in v3.0.0
+- Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**OmniRoute solves this:**
+
+- ✅ **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
+- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool
---
-[](https://www.npmjs.com/package/omniroute)
-[](https://hub.docker.com/r/diegosouzapw/omniroute)
-[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
-[](https://omniroute.online)
-[](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
+## 📧 Support
-[🌐 ウェブサイト](https://omniroute.online) • [🚀 クイックスタート](#-クイックスタート) • [💡 主な機能](#-主な機能) • [📖 ドキュメント](#-ドキュメント) • [💰 料金](#-価格の概要) • [💬 WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
+> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.
-🌐 **対応言語:** 🇺🇸 [English](../../README.md) | 🇧🇷 [Português (Brasil)](../pt-BR/README.md) | 🇪🇸 [Español](../es/README.md) | 🇫🇷 [Français](../fr/README.md) | 🇮🇹 [Italiano](../it/README.md) | 🇷🇺 [Русский](../ru/README.md) | 🇨🇳 [中文 (简体)](../zh-CN/README.md) | 🇩🇪 [Deutsch](../de/README.md) | 🇮🇳 [हिन्दी](../in/README.md) | 🇹🇭 [ไทย](../th/README.md) | 🇺🇦 [Українська](../uk-UA/README.md) | 🇸🇦 [العربية](../ar/README.md) | 🇯🇵 [日本語](../ja/README.md) | 🇻🇳 [Tiếng Việt](../vi/README.md) | 🇧🇬 [Български](../bg/README.md) | 🇩🇰 [Dansk](../da/README.md) | 🇫🇮 [Suomi](../fi/README.md) | 🇮🇱 [עברית](../he/README.md) | 🇭🇺 [Magyar](../hu/README.md) | 🇮🇩 [Bahasa Indonesia](../id/README.md) | 🇰🇷 [한국어](../ko/README.md) | 🇲🇾 [Bahasa Melayu](../ms/README.md) | 🇳🇱 [Nederlands](../nl/README.md) | 🇳🇴 [Norsk](../no/README.md) | 🇵🇹 [Português (Portugal)](../pt/README.md) | 🇷🇴 [Română](../ro/README.md) | 🇵🇱 [Polski](../pl/README.md) | 🇸🇰 [Slovenčina](../sk/README.md) | 🇸🇪 [Svenska](../sv/README.md) | 🇵🇭 [Filipino](../phi/README.md)
-
-
-
----
-
-## 🖼️
-
-
-
- # 🚀 OmniRoute — 無料の AI ゲートウェイ
+# 🚀 OmniRoute — The Free AI Gateway (日本語)
-### コーディングを決してやめないでください。自動フォールバックを備えた **無料および低コストの AI モデル**へのスマート ルーティング。
-
-_ユニバーサル API プロキシ — 1 つのエンドポイント、36 以上のプロバイダー、ダウンタイムなし。_
-
-**チャット補完 • 埋め込み • 画像生成 • オーディオ • 再ランキング • 100% TypeScript **
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 お気に入りのコーディング エージェント向けの無料 AI プロバイダー
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_AI を活用した IDE または CLI ツールを、無制限のコーディングのための無料 API ゲートウェイである OmniRoute 経由で接続します。_
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+
+
+[](https://www.npmjs.com/package/omniroute)
+[](https://www.npmjs.com/package/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
+[](https://omniroute.online)
+[](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)
+
+
+
+🌐 **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)
+
+---
+
+## 🆕 What's New in v3.0.0
+
+> **Upgrading from v2.9.5?** — See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes.
+
+| Area | Change |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection remediation |
+| ✅ **Route Validation** | All 176 API routes now validated with Zod schemas + `validateBody()` — CI `check:route-validation:t06` passes |
+| 🐛 **omniModel Tag Leak** | Internal `
+
+
+
+---
+
+## 📸 Dashboard Preview
+
+
+
+
+
+---
+
+### 🤖 Free AI Provider for your favorite coding agents
+
+_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._
Click to see dashboard screenshots
+ +| Page | Screenshot | +| -------------- | ------------------------------------------------- | +| **Providers** |  | +| **Combos** |  | +| **Analytics** |  | +| **Health** |  | +| **Translator** |  | +| **Settings** |  | +| **CLI Tools** |  | +| **Usage Logs** |  | +| **Endpoints** |  | + +|
-
+
OpenClaw @@ -92,113 +162,52 @@ _AI を活用した IDE または CLI ツールを、無制限のコーディン |
http://localhost:20128/v1 または http://cloud.omniroute.online/v1 経由で接続します — 1 つの構成、無制限のモデルとクォータ
+📡 All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 — one config, unlimited models and quota
---
-### 🆕 What's New in v3.0.0
+## 🤔 Why OmniRoute?
-| Area | Change |
-| ------------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal ` Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `
-
-
-
----
-
-## 📸
-
-
-
-
-
----
-
-## 🤔 なぜオムニルートなのか?
-
-**お金の無駄遣いや限界に達するのはやめましょう:**
-
-- ...
- -| # | # | -| ----- | ---------------------------------------- | -| **1** |  | -| **2** |  | -| **3** |  | -| **4** |  | -| **5** |  | -| **6** |  | -| **7** |  | -| **8** |  | -| **9** |  | - - サブスクリプション割り当ては毎月未使用のまま期限切れになります
-- レート制限によりコーディングの途中で停止する
-- 高価な API (プロバイダーごとに月額 20 ～ 50 ドル)
-- プロバイダー間の手動切り替え
-
-**OmniRoute はこれを解決します:**
-
-- ✅ **サブスクリプションを最大化** - クォータを追跡し、リセットする前にすべてのビットを使用します
-- ✅ **自動フォールバック** - サブスクリプション → API キー → 安価 → 無料、ダウンタイムなし
-- ✅ **マルチアカウント** - プロバイダーごとのアカウント間のラウンドロビン
-- ✅ **ユニバーサル** - Claude Code、Codex、Gemini CLI、Cursor、Cline、OpenClaw、あらゆる CLI ツールで動作します
-
----
-
-## 📧 サポート
-
-> 💬 **コミュニティに参加してください!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — ヘルプを取得し、ヒントを共有し、最新情報を入手してください。
-
-- **ウェブサイト**: [omniroute.online](https://omniroute.online)
+- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **問題**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **オリジナル プロジェクト**: [9router by decolua](https://github.com/decolua/9router)
+- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 仕組み
+## 🔄 How It Works
```
┌─────────────┐
@@ -227,452 +236,453 @@ Result: Never stop coding, minimal cost
---
-## 🎯 OmniRoute が解決するもの — 30 の実際の問題点とユースケース
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **AI ツールを使用するすべての開発者は、これらの問題に日々直面しています。** OmniRoute は、コスト超過から地域ブロック、壊れた OAuth フローからプロトコル操作、企業の可観測性まで、それらすべてを解決するために構築されました。
+> **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.
-
💸 1. 「高価なサブスクリプションの料金を支払っているのに、制限によって中断されます」
+💸 1. "I pay for an expensive subscription but still get interrupted by limits"
-開発者は、Claude Pro、Codex Pro、または GitHub Copilot に月額 20 ～ 200 ドルを支払います。有料であっても、割り当てには上限があり、5 時間の使用量、週ごとの制限、または分ごとのレート制限があります。コーディング セッションの途中でプロバイダーが応答を停止し、開発者はフローと生産性を失います。 +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. -**OmniRoute がそれを解決する方法:** +**How OmniRoute solves it:** -- **スマート 4 層フォールバック** — サブスクリプション クォータが不足すると、手動介入なしで自動的に API キー→格安→無料にリダイレクトされます。 -- **リアルタイム クォータ トラッキング** — リセット カウントダウン (5 時間、毎日、毎週) でトークンの消費量をリアルタイムで表示します。 -- **マルチアカウントのサポート** — 自動ラウンドロビンによるプロバイダーごとの複数のアカウント — 1 つのアカウントがなくなると、次のアカウントに切り替わります -- **カスタム コンボ** — 6 つのバランシング戦略 (フィルファースト、ラウンドロビン、P2C、ランダム、最小使用、コスト最適化) を備えたカスタマイズ可能なフォールバック チェーン -- **Codex Business クォータ** — ビジネス/チームのワークスペース クォータをダッシュボードで直接監視 +- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention +- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly) +- **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 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
-` ブロックを標準化された `reasoning_content` に抽出します。
-- **Gemini の構造化出力** — `json_schema` → `responseMimeType`/`responseSchema` 自動変換
-- **`stream` のデフォルトは `false`** — OpenAI 仕様に準拠し、Python/Rust/Go SDK での予期しない SSE を回避します
+- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 67+ 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
🔌 2. 「複数のプロバイダーを使用する必要がありますが、それぞれに異なる API があります」
+🔌 2. "I need to use multiple providers but each has a different API"
-OpenAI は 1 つの形式を使用し、Claude (Anthropic) は別の形式を使用し、Gemini はさらに別の形式を使用します。開発者が異なるプロバイダーのモデルをテストしたり、プロバイダー間でフォールバックしたりする場合は、SDK を再構成し、エンドポイントを変更し、互換性のない形式に対処する必要があります。カスタム プロバイダー (FriendLI、NIM) には、非標準モデルのエンドポイントがあります。 +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. -**OmniRoute がそれを解決する方法:** +**How OmniRoute solves it:** -- **統合エンドポイント** - 単一の `http://localhost:20128/v1` が 36 を超えるすべてのプロバイダーのプロキシとして機能します -- **フォーマット変換** — 自動かつ透過的: OpenAI ↔ Claude ↔ Gemini ↔ Responses API -- **レスポンスのサニタイズ** — OpenAI SDK v1.83 以降を破壊する非標準フィールド (`x_groq`、`usage_breakdown`、`service_tier`) を除去します。 -- **ロールの正規化** — 非 OpenAI プロバイダーに対して `developer` → `system` を変換します。 GLM/ERNIE 用 `system` → `user` -- **Think Tag Extraction** — DeepSeek R1 などのモデルから `
-
🌐 3. 「AI プロバイダーが私の地域/国をブロックしています」
+🌐 3. "My AI provider blocks my region/country"
-OpenAI/Codex などのプロバイダーは、特定の地理的地域からのアクセスをブロックします。 OAuth および API 接続中に、ユーザーは `unsupported_country_region_territory` のようなエラーを受け取ります。これは、発展途上国の開発者にとって特にイライラさせられます。 +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. -**OmniRoute がそれを解決する方法:** +**How OmniRoute solves it:** -- **3 レベルのプロキシ構成** — 3 つのレベルで構成可能なプロキシ: グローバル (すべてのトラフィック)、プロバイダーごと (1 つのプロバイダーのみ)、および接続/キーごと -- **色分けされたプロキシ バッジ** — 視覚的なインジケーター: 🟢 グローバル プロキシ、🟡 プロバイダー プロキシ、🔵 接続プロキシ、常に IP を表示 -- **プロキシを介した OAuth トークン交換** — OAuth フローもプロキシを通過し、`unsupported_country_region_territory` を解決します -- **プロキシ経由の接続テスト** — 接続テストは構成されたプロキシを使用します (直接バイパスはありません)。 -- **SOCKS5 サポート** — アウトバウンド ルーティングに対する SOCKS5 プロキシの完全なサポート -- **TLS フィンガープリント スプーフィング** — `wreq-js` を介したブラウザーのような TLS フィンガープリントによりボット検出をバイパスします +- **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
-` prefix
-- **無料のみのコンボ** — チェーン `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = 月額 0 ドル、ダウンタイムなし
-- **NVIDIA NIM 無料クレジット** — 1000 の無料クレジットが統合されています
-- **コスト最適化戦略** — 利用可能な最も安価なプロバイダーを自動的に選択するルーティング戦略
+- **Free-Only Combos** — Chain `gc/gemini-3-flash → 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
🆓 4. 「AIを使ってコーディングしたいけどお金がない」
+🆓 4. "I want to use AI for coding but I have no money"
-誰もが AI サブスクリプションに月額 20 ～ 200 ドルを支払えるわけではありません。学生、新興国の開発者、愛好家、フリーランサーは、高品質のモデルに無料でアクセスできる必要があります。 +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. -**OmniRoute がそれを解決する方法:** +**How OmniRoute solves it:** -- **無料利用枠プロバイダーの組み込み** — 100% 無料プロバイダーのネイティブ サポート: iFlow (8 つの無制限のモデル)、Qwen (3 つの無制限のモデル)、Kiro (無料の Claude)、Gemini CLI (180K/月無料) +- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free) - **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/
-
🔒 5. 「AI ゲートウェイを不正アクセスから保護する必要があります」
+🔒 5. "I need to protect my AI gateway from unauthorized access"
-AI ゲートウェイをネットワーク (LAN、VPS、Docker) に公開すると、アドレスを持っている人は誰でも開発者のトークン/クォータを消費できます。保護がなければ、API は誤用、即時挿入、悪用に対して脆弱になります。 +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. -**OmniRoute がそれを解決する方法:** +**How OmniRoute solves it:** -- **API キー管理** — 専用の `/dashboard/api-manager` ページを使用したプロバイダーごとの生成、ローテーション、およびスコープ設定 -- **モデルレベルの権限** — すべて許可/制限の切り替えにより、API キーを特定のモデル (`openai/*`、ワイルドカード パターン) に制限します -- **API エンドポイント保護** - `/v1/models` のキーを要求し、リストから特定のプロバイダーをブロックします -- **認証ガード + CSRF 保護** — すべてのダッシュボード ルートは `withAuth` ミドルウェア + CSRF トークンで保護されています -- **レート リミッター** — 構成可能なウィンドウによる IP ごとのレート制限 -- **IP フィルタリング** — アクセス制御の許可リスト/ブロックリスト -- **プロンプト インジェクション ガード** — 悪意のあるプロンプト パターンに対するサニタイズ -- **AES-256-GCM 暗号化** — 認証情報は保存時に暗号化されます +- **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. 「プロバイダーがダウンしてコーディング フローが失われました」
+🛑 6. "My provider went down and I lost my coding flow"
-AI プロバイダーが不安定になったり、5xx エラーを返したり、一時的なレート制限に達したりする可能性があります。開発者が単一のプロバイダーに依存している場合、それらは中断されます。サーキット ブレーカーがないと、再試行を繰り返すとアプリケーションがクラッシュする可能性があります。 +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. -**OmniRoute がそれを解決する方法:** +**How OmniRoute solves it:** -- **プロバイダーごとのサーキット ブレーカー** — 設定可能なしきい値とクールダウンによる自動開閉 (クローズ/オープン/ハーフオープン) -- **指数バックオフ** — 漸進的な再試行遅延 -- **Anti-Thundering Herd** — 同時再試行の嵐に対するミューテックス + セマフォ保護 -- **コンボ フォールバック チェーン** - プライマリ プロバイダーに障害が発生した場合、介入なしで自動的にチェーンを通過します。 -- **コンボ サーキット ブレーカー** — コンボ チェーン内の障害が発生したプロバイダーを自動的に無効にします -- **ヘルス ダッシュボード** — 稼働時間モニタリング、サーキット ブレーカーの状態、ロックアウト、キャッシュ統計、p50/p95/p99 レイテンシ +- **Circuit Breaker per-model** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks +- **Exponential Backoff** — Progressive retry delays +- **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 +- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain +- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
-
🔧 7. 「各 AI ツールの設定は面倒で繰り返しが多い」
+🔧 7. "Configuring each AI tool is tedious and repetitive"
-開発者は、Cursor、Claude Code、Codex CLI、OpenClaw、Gemini CLI、Kilo Code を使用します。各ツールには異なる構成 (API エンドポイント、キー、モデル) が必要です。プロバイダーや機種変更時に再設定するのは時間の無駄です。 +Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time. -**OmniRoute がそれを解決する方法:** +**How OmniRoute solves it:** -- **CLI ツール ダッシュボード** — Claude Code、Codex CLI、OpenClaw、Kilo Code、Antigravity、Cline をワンクリックでセットアップできる専用ページ -- **GitHub Copilot Config Generator** — モデルを一括選択して VS Code の `chatLanguageModels.json` を生成します -- **オンボーディング ウィザード** - 初めてユーザー向けのガイド付き 4 ステップ セットアップ -- **1 つのエンドポイント、すべてのモデル** — `http://localhost:20128/v1` を 1 回構成すると、36 を超えるプロバイダーにアクセスできます +- **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 67+ providers
-
🔑 8. 「複数のプロバイダーからの OAuth トークンを管理するのは地獄です」
+🔑 8. "Managing OAuth tokens from multiple providers is hell"
-Claude Code、Codex、Gemini CLI、Copilot — すべては有効期限切れのトークンを持つ OAuth 2.0 を使用します。開発者は定期的に再認証し、`client_secret is missing`、`redirect_uri_mismatch`、およびリモート サーバーの障害に対処する必要があります。 LAN/VPS 上の OAuth は特に問題があります。 +Claude Code, Codex, Gemini CLI, 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. -**OmniRoute がそれを解決する方法:** +**How OmniRoute solves it:** -- **自動トークン更新** — OAuth トークンは有効期限が切れる前にバックグラウンドで更新されます。 -- **OAuth 2.0 (PKCE) ビルトイン** — Claude Code、Codex、Gemini CLI、Copilot、Kiro、Qwen、iFlow の自動フロー -- **マルチアカウント OAuth** — JWT/ID トークン抽出によるプロバイダーごとの複数のアカウント -- **OAuth LAN/リモート修正** — `redirect_uri` のプライベート IP 検出 + リモート サーバーの手動 URL モード -- **Nginx の背後にある OAuth** — リバース プロキシの互換性のために `window.location.origin` を使用します -- **リモート OAuth ガイド** — VPS/Docker での Google Cloud 認証情報のステップバイステップ ガイド +- **Auto Token Refresh** — OAuth tokens refresh in background before expiration +- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow +- **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. 「どこにいくら使っているのか分かりません」
+📊 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. -**OmniRoute がそれを解決する方法:** +**How OmniRoute solves it:** -- **コスト分析ダッシュボード** — トークンごとのコスト追跡とプロバイダーごとの予算管理 -- **階層ごとの予算制限** — 自動フォールバックをトリガーする階層ごとの支出上限 -- **モデルごとの価格構成** — モデルごとに構成可能な価格 -- **API キーごとの使用統計** — キーごとのリクエスト数と最後に使用されたタイムスタンプ -- **分析ダッシュボード** — 統計カード、モデル使用状況グラフ、成功率と遅延を含むプロバイダー表 +- **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. 「AI 呼び出しのエラーや問題を診断できません」
+🐛 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. -**OmniRoute がそれを解決する方法:** +**How OmniRoute solves it:** -- **統合ログ ダッシュボード** — 4 つのタブ: リクエスト ログ、プロキシ ログ、監査ログ、コンソール -- **コンソール ログ ビューア** — 色分けされたレベル、自動スクロール、検索、フィルターを備えたリアルタイムのターミナル スタイルのビューア -- **SQLite プロキシ ログ** — サーバーの再起動後も存続する永続的なログ -- **Translator Playground** — 4 つのデバッグ モード: プレイグラウンド (形式変換)、チャット テスター (往復)、テストベンチ (バッチ)、ライブ モニター (リアルタイム) -- **リクエスト テレメトリ** — p50/p95/p99 レイテンシ + X-Request-Id トレース -- **ローテーションを使用したファイルベースのログ** — コンソール インターセプターは、サイズベースのローテーションを使用してすべてを JSON ログにキャプチャします。 +- **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 Proxy Logs** — Persistent logs that survive server restarts +- **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 Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation +- **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. 「ゲートウェイの導入と保守は複雑です」
+🏗️ 11. "Deploying and maintaining the gateway is complex"
-さまざまな環境 (ローカル、VPS、Docker、クラウド) 間で AI プロキシをインストール、構成、維持するには、多大な労力がかかります。ハードコーディングされたパス、ディレクトリ上の `EACCES`、ポートの競合、クロスプラットフォーム ビルドなどの問題により、摩擦が増大します。 +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. -**OmniRoute がそれを解決する方法:** +**How OmniRoute solves it:** -- **npm グローバル インストール** — `npm install -g omniroute && omniroute` — 完了 -- **Docker マルチプラットフォーム** — AMD64 + ARM64 ネイティブ (Apple Silicon、AWS Graviton、Raspberry Pi) -- **Docker Compose プロファイル** — `base` (CLI ツールなし) および `cli` (Claude Code、Codex、OpenClaw あり) -- **Electron デスクトップ アプリ** — システム トレイ、自動起動、オフライン モードを備えた Windows/macOS/Linux 用ネイティブ アプリ -- **分割ポート モード** - 高度なシナリオ (リバース プロキシ、コンテナ ネットワーキング) 向けに個別のポート上の API とダッシュボード -- **Cloud Sync** — Cloudflare Workers を介したデバイス間での設定の同期 -- **DB バックアップ** — すべての設定の自動バックアップ、復元、エクスポート、インポート +- **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
-
🌍 12. 「インターフェースは英語のみで、私のチームは英語を話せません」
+🌍 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. -**OmniRoute がそれを解決する方法:** +**How OmniRoute solves it:** -- **ダッシュボード i18n — 30 言語** — アラビア語、ブルガリア語、デンマーク語、ドイツ語、スペイン語、フィンランド語、フランス語、ヘブライ語、ヒンディー語、ハンガリー語、インドネシア語、イタリア語、日本語、韓国語、マレー語、オランダ語、ノルウェー語、ポーランド語、ポルトガル語 (PT/BR)、ルーマニア語、ロシア語、スロバキア語、スウェーデン語、タイ語、ウクライナ語、ベトナム語、中国語、フィリピン語、英語 -- **RTL サポート** — アラビア語とヘブライ語の右から左へのサポート -- **多言語 README** — 30 件の完全なドキュメント翻訳 -- **言語セレクター** — リアルタイム切り替えのためのヘッダーの地球儀アイコン +- **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. 「チャット以上のものが必要です — 埋め込み、画像、音声が必要です」
+🔄 13. "I need more than chat — I need embeddings, images, audio"
-AIは単なるチャット補完ではありません。開発者は、画像の生成、音声の文字起こし、RAG の埋め込みの作成、ドキュメントの再ランク付け、およびコンテンツの管理を行う必要があります。各 API には異なるエンドポイントと形式があります。 +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. -**OmniRoute がそれを解決する方法:** +**How OmniRoute solves it:** -- **エンベディング** — 6 つのプロバイダーと 9 つ以上のモデルを備えた `/v1/embeddings` -- **画像生成** — 10 プロバイダーと 20 以上のモデルを備えた `/v1/images/generations` (OpenAI、xAI、Togetter、Fireworks、Nebius、Hyperbolic、NanoBanana、Antigravity、SD WebUI、ComfyUI) -- **Text-to-Video** — `/v1/videos/generations` — ComfyUI (AnimateDiff、SVD) および SD WebUI -- **テキストから音楽へ** — `/v1/music/generations` — ComfyUI (安定したオーディオ オープン、MusicGen) -- **音声転写** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM、HuggingFace、Qwen3 -- **テキスト読み上げ** — `/v1/audio/speech` — イレブンラボ、Nvidia NIM、HuggingFace、Coqui、Tortoise、Qwen3、+ 既存のプロバイダー -- **モデレーション** — `/v1/moderations` — コンテンツの安全性チェック -- **再ランキング** — `/v1/rerank` — ドキュメントの関連性の再ランキング -- **応答 API** — Codex の `/v1/responses` の完全サポート +- **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. 「モデル間で品質をテストして比較する方法がありません」
+🧪 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. -**OmniRoute がそれを解決する方法:** +**How OmniRoute solves it:** -- **LLM 評価** — 挨拶、数学、地理、コード生成、JSON 準拠、翻訳、マークダウン、安全性の拒否をカバーする 10 個の事前ロードされたケースによるゴールデン セット テスト -- **4 つのマッチ戦略** — `exact`、`contains`、`regex`、`custom` (JS 関数) -- **Translator Playground Test Bench** — 複数の入力と予想される出力を使用したバッチ テスト、クロスプロバイダー比較 -- **チャット テスター** — 視覚的な応答レンダリングによる完全な往復 -- **ライブ モニター** — プロキシを通過するすべてのリクエストのリアルタイム ストリーム +- **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. 「パフォーマンスを落とさずにスケールする必要がある」
+📈 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. -**OmniRoute がそれを解決する方法:** +**How OmniRoute solves it:** -- **セマンティック キャッシュ** — 2 層キャッシュ (署名 + セマンティック) によりコストと遅延が削減されます。 -- **リクエストの冪等性** — 同一のリクエストに対する重複排除ウィンドウは 5 秒です -- **レート制限検出** — プロバイダーごとの RPM、最小ギャップ、最大同時トラッキング -- **編集可能なレート制限** — [設定] → [永続性を伴う回復力] で構成可能なデフォルト -- **API キー検証キャッシュ** — 運用パフォーマンスのための 3 層キャッシュ -- **テレメトリ付きヘルス ダッシュボード** — p50/p95/p99 レイテンシ、キャッシュ統計、稼働時間 +- **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 +- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence +- **API Key Validation Cache** — 3-tier cache for production performance +- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
-
🤖 16. 「モデルの動作をグローバルに制御したい」
+🤖 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. -**OmniRoute がそれを解決する方法:** +**How OmniRoute solves it:** -- **システム プロンプト インジェクション** — すべてのリクエストに適用されるグローバル プロンプト -- **思考予算検証** — リクエストごとの推論トークン割り当て制御 (パススルー、自動、カスタム、適応) -- **6 ルーティング戦略** — リクエストの分散方法を決定するグローバル戦略 -- **ワイルドカード ルーター** - `provider/*` パターンは任意のプロバイダーに動的にルーティングします -- **コンボ有効/無効切り替え** — ダッシュボードから直接コンボを切り替えます -- **プロバイダー切り替え** — ワンクリックでプロバイダーのすべての接続を有効/無効にします。 -- **ブロックされたプロバイダー** — `/v1/models` リストから特定のプロバイダーを除外します +- **System Prompt Injection** — Global prompt applied to all requests +- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive) +- **6 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 +- **Provider Toggle** — Enable/disable all connections for a provider with one click +- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
-
🧰 17. 「一流の製品機能として MCP ツールが必要です」
+🧰 17. "I need MCP tools as first-class product capabilities"
-多くの AI ゲートウェイは、MCP を非表示の実装詳細としてのみ公開します。チームには、目に見えて管理しやすいオペレーション レイヤーが必要です。 +Many AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer. -**OmniRoute がそれを解決する方法:** +**How OmniRoute solves it:** -- MCP はダッシュボードのナビゲーションとエンドポイント プロトコル タブに表示されます -- プロセス、ツール、スコープ、監査を備えた専用の MCP 管理ページ -- `omniroute --mcp` およびクライアントのオンボーディング用の組み込みクイックスタート +- 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. 「同期 + ストリーム タスク パスを備えた A2A オーケストレーションが必要です」
+🧠 18. "I need A2A orchestration with sync + stream task paths"
-エージェント ワークフローには、直接応答と、ライフサイクル制御による長時間実行のストリーミング実行の両方が必要です。 +Agent workflows need both direct replies and long-running streamed execution with lifecycle control. -**OmniRoute がそれを解決する方法:** +**How OmniRoute solves it:** -- A2A JSON-RPC エンドポイント (`POST /a2a`) (`message/send` および `message/stream`) -- 端末状態の伝播を伴う SSE ストリーミング -- `tasks/get` および `tasks/cancel` のタスク ライフサイクル API +- 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. 「推測されたステータスではなく、実際の MCP プロセスの健全性が必要です」
+🛰️ 19. "I need real MCP process health, not guessed status"
-運用チームは、API が到達可能かどうかだけでなく、MCP が実際に生きているかどうかを知る必要があります。 +Operational teams need to know if MCP is actually alive, not just whether an API is reachable. -**OmniRoute がそれを解決する方法:** +**How OmniRoute solves it:** -- PID、タイムスタンプ、トランスポート、ツール数、およびスコープモードを含むランタイムハートビートファイル -- ハートビートと最近のアクティビティを組み合わせた MCP ステータス API -- プロセス/稼働時間/ハートビートの鮮度を示す UI ステータス カード +- 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. 「監査可能な MCP ツールの実行が必要です」
+📋 20. "I need auditable MCP tool execution"
-ツールが構成を変更したり、運用アクションをトリガーしたりする場合、チームはフォレンジックなトレーサビリティを必要とします。 +When tools mutate config or trigger ops actions, teams need forensic traceability. -**OmniRoute がそれを解決する方法:** +**How OmniRoute solves it:** -- MCP ツール呼び出しの SQLite ベースの監査ログ -- ツール、成功/失敗、API キー、ページネーションによるフィルター -- ダッシュボード監査テーブル + 自動化のための統計エンドポイント +- 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. 「統合ごとにスコープ指定された MCP 権限が必要です」
+🔐 21. "I need scoped MCP permissions per integration"
-異なるクライアントには、ツール カテゴリへの最小限の特権アクセスが必要です。 +Different clients should have least-privilege access to tool categories. -**OmniRoute がそれを解決する方法:** +**How OmniRoute solves it:** -- 制御されたツールアクセスのための 9 つの詳細な MCP スコープ -- MCP 管理 UI でのスコープの適用と可視性 -- 運用ツールの安全なデフォルト姿勢 +- 9 granular MCP scopes for controlled tool access +- Scope enforcement and visibility in MCP management UI +- Safe default posture for operational tooling
-
⚙️ 22. 「再デプロイせずに運用制御が必要です」
+⚙️ 22. "I need operational controls without redeploying"
-チームは、インシデントやコスト イベントが発生した際に、実行時の変更を迅速に行う必要があります。 +Teams need quick runtime changes during incidents or cost events. -**OmniRoute がそれを解決する方法:** +**How OmniRoute solves it:** -- MCP ダッシュボードからコンボのアクティブ化を直接切り替えます -- 事前定義されたポリシーパックから復元プロファイルを適用 -- 同じ操作パネルからサーキットブレーカーの状態をリセット - | 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format | +- Switch combo activation directly from MCP dashboard +- Apply resilience profiles from pre-defined policy packs +- Reset circuit breaker state from the same operations panel
-
🔄 23. 「ライブ A2A タスクのライフサイクルの可視化とキャンセルが必要です」
+🔄 23. "I need live A2A task lifecycle visibility and cancellation"
-ライフサイクルの可視性がなければ、タスク インシデントの優先順位付けが困難になります。 +Without lifecycle visibility, task incidents become hard to triage. -**OmniRoute がそれを解決する方法:** +**How OmniRoute solves it:** -- ページネーションを使用した状態/スキルによるタスクのリスト/フィルタリング -- タスクのメタデータ、イベント、アーティファクトのドリルダウン -- タスクキャンセルエンドポイントと確認付きの UI アクション +- 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. 「A2A ロード用のアクティブ ストリーム メトリクスが必要です」
+🌊 24. "I need active stream metrics for A2A load"
-ストリーミング ワークフローには、同時実行性とライブ接続に関する運用上の洞察が必要です。 +Streaming workflows require operational insight into concurrency and live connections. -**OmniRoute がそれを解決する方法:** +**How OmniRoute solves it:** -- アクティブ ストリーム カウンターが A2A ステータスに統合されました -- 最後のタスクのタイムスタンプと状態ごとのカウント -- リアルタイム運用監視用の A2A ダッシュボード カード +- Active stream counters integrated into A2A status +- Last task timestamp and per-state counts +- A2A dashboard cards for real-time ops monitoring
-
🪪 25. 「クライアントの標準エージェント検出が必要です」
+🪪 25. "I need standard agent discovery for clients"
-外部クライアントとオーケストレーターには、オンボーディング用の機械可読メタデータが必要です。 +External clients and orchestrators need machine-readable metadata for onboarding. -**OmniRoute がそれを解決する方法:** +**How OmniRoute solves it:** -- エージェント カードが `/.well-known/agent.json` で公開される -- 管理UIに表示される能力とスキル -- A2A ステータス API には自動化のための検出メタデータが含まれています +- Agent Card exposed at `/.well-known/agent.json` +- Capabilities and skills shown in management UI +- A2A status API includes discovery metadata for automation
-
🧭 26. 「製品 UX にプロトコルの検出機能が必要です」
+🧭 26. "I need protocol discoverability in the product UX"
-ユーザーがプロトコルの表面を発見できない場合、導入とサポートの品質が低下します。 +If users cannot discover protocol surfaces, adoption and support quality drop. -**OmniRoute がそれを解決する方法:** +**How OmniRoute solves it:** -- MCP および A2A のサイドバー エントリ -- クイックスタートとステータスを含むエンドポイント ページの [プロトコル] タブ -- 概要から専用の管理ダッシュボードへのリンク +- 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. 「実際のクライアントを使用したエンドツーエンドのプロトコル検証が必要です」
+🧪 27. "I need end-to-end protocol validation with real clients"
-模擬テストは、リリース前にプロトコルの互換性を検証するには十分ではありません。 +Mock tests are not enough to validate protocol compatibility before release. -**OmniRoute がそれを解決する方法:** +**How OmniRoute solves it:** -- アプリを起動し、実際の MCP SDK クライアント トランスポートを使用する E2E スイート -- A2A クライアントは、フローの検出、送信、ストリーミング、取得、キャンセルをテストします。 -- MCP 監査および A2A タスク API に対するアサーションのクロスチェック +- 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. 「すべてのインターフェースにわたって統合された可観測性が必要です」
+📡 28. "I need unified observability across all interfaces"
-プロトコルごとに可観測性を分割すると、盲点が生じ、MTTR が長くなります。 +Splitting observability by protocol creates blind spots and longer MTTR. -**OmniRoute がそれを解決する方法:** +**How OmniRoute solves it:** -- ダッシュボード/ログ/分析を 1 つの製品に統合 -- OpenAI、MCP、A2A レイヤーにわたるヘルス + 監査 + リクエスト テレメトリ -- ステータスと自動化のための運用 API +- Unified dashboards/logs/analytics in one product +- Health + audit + request telemetry across OpenAI, MCP, and A2A layers +- Operational APIs for status and automation
-
💼 29. 「プロキシ + ツール + エージェント オーケストレーション用のランタイムが 1 つ必要です」
+💼 29. "I need one runtime for proxy + tools + agent orchestration"
-多くの個別のサービスを実行すると、運用コストが増加し、障害モードが増加します。 +Running many separate services increases operational cost and failure modes. -**OmniRoute がそれを解決する方法:** +**How OmniRoute solves it:** -- OpenAI互換プロキシ、MCPサーバー、A2Aサーバーを1つのスタックに搭載 -- 共有認証、復元力、データストア、可観測性 -- すべての対話面にわたる一貫したポリシー モデル +- 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
-
-### プレイブックの例 (統合されたユースケース)
+### Example Playbooks (Integrated Use Cases)
-**戦略 A: 有料サブスクリプション + 安価なバックアップを最大限に活用する**
+**Playbook A: Maximize paid subscription + cheap backup**
```txt
Combo: "maximize-claude"
@@ -684,7 +694,7 @@ Monthly cost: $20 + small backup spend
Outcome: higher quality, near-zero interruption
```
-**プレイブック B: ゼロコストのコーディング スタック**
+**Playbook B: Zero-cost coding stack**
```txt
Combo: "free-forever"
@@ -696,7 +706,7 @@ Monthly cost: $0
Outcome: stable free coding workflow
```
-**プレイブック C: 24 時間年中無休の常時オンのフォールバック チェーン**
+**Playbook C: 24/7 always-on fallback chain**
```txt
Combo: "always-on"
@@ -709,65 +719,132 @@ Combo: "always-on"
Outcome: deep fallback depth for deadline-critical workloads
```
-**プレイブック D: MCP + A2A を使用したエージェントの運用**
+**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/mcp and /dashboard/a2a
-4) Control incidents with resilience profile + task cancellation
+3) Observe via /dashboard/endpoint (MCP and A2A tabs)
+4) Toggle services via inline status controls
```
---
-## ⚡ クイックスタート
+## 🆓 Start Free — Zero Configuration Cost
-**1.グローバルにインストール:**
+> 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 **iFlow** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |
+| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |
+| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |
+| 5 | `/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).
+
+## クイックスタート
+
+### 1) Install and run
```bash
npm install -g omniroute
omniroute
```
-🎉 ダッシュボードは `http://localhost:20128` に開きます
+> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:
+>
+> ```bash
+> pnpm install -g omniroute
+> pnpm approve-builds -g # Select all packages → approve
+> omniroute
+> ```
-| コマンド | 説明 |
-| ----------------------- | ----------------------------------------------- |
-| `omniroute` | サーバーを起動します (デフォルトのポート 20128) |
-| `omniroute --port 3000` | カスタムポートを使用する |
-| `omniroute --no-open` | ブラウザを自動的に開かない |
-| `omniroute --help` | ヘルプを表示 |
+Dashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.
-**2.無料のプロバイダーに接続します:**
+| 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 |
-ダッシュボード → プロバイダー → **Claude Code** または **Antigravity** に接続 → OAuth ログイン → 完了!
+Optional split-port mode:
-**3. CLI ツールで使用します:**
-
-```
-Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Settings:
- Endpoint: http://localhost:20128/v1
- API Key: [copy from dashboard]
- Model: if/kimi-k2-thinking
+```bash
+PORT=20128 DASHBOARD_PORT=20129 omniroute
+# API: http://localhost:20128/v1
+# Dashboard: http://localhost:20129
```
-**それだけです!** 無料の AI モデルを使用してコーディングを始めましょう。
+### 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
+
+```txt
+Base URL: http://localhost:20128/v1
+API Key: [copy from Endpoint page]
+Model: if/kimi-k2-thinking (or any provider/model prefix)
+```
+
+Works with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.
+
+### 4) Enable and validate protocols (v2.0)
+
+**MCP (for tool-driven operations):**
+
+```bash
+omniroute --mcp
+```
+
+Then connect your MCP client over `stdio` and test tools like:
+
+- `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 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
+PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev
```
---
-## 🐳 ドッカー
+## 🐳 Docker
-OmniRoute は、[Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute) のパブリック 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 \
@@ -778,7 +855,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**環境ファイルあり:**
+**With environment file:**
```bash
# Copy and edit .env first
@@ -793,7 +870,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Docker Compose の使用:**
+**Using Docker Compose:**
```bash
# Base profile (no CLI tools)
@@ -803,259 +880,552 @@ docker compose --profile base up -d
docker compose --profile cli up -d
```
-| 画像 | タグ | サイズ | 説明 |
-| ------------------------ | -------- | ------- | -------------------- |
-| `diegosouzapw/omniroute` | `latest` | ～250MB | 最新の安定版リリース |
-| `diegosouzapw/omniroute` | `1.0.3` | ～250MB | 現在のバージョン |
+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.
+- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.
+- 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` | `1.0.3` | ~250MB | Current version |
---
----
+## 🖥️ Desktop App — Offline & Always-On
-## 🖥️
+> 🆕 **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.
-> 🆕 **新機能！** OmniRouteが**ネイティブデスクトップアプリケーション**としてWindows、macOS、Linuxで利用可能になりました。
+Run OmniRoute as a standalone desktop app — no terminal, no browser, no internet required for local models. The Electron-based app includes:
-- 🖥️ **ネイティブウィンドウ** — システムトレイ統合付きの専用ウィンドウ
-- 🔄 **自動起動** — システムログイン時にOmniRouteを起動
-- 🔔 **ネイティブ通知** — クォータ枯渇やプロバイダー問題のアラート
-- ⚡ **ワンクリックインストール** — NSIS (Windows)、DMG (macOS)、AppImage (Linux)
-- 🌐 **オフラインモード** — 内蔵サーバーで完全オフライン動作
+- 🖥️ **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
+
+### クイックスタート
```bash
-npm run electron:dev # 開発モード
-npm run electron:build # 現在のプラットフォーム
+# 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)
+npm run electron:build:mac # macOS (.dmg) — x64 & arm64
npm run electron:build:linux # Linux (.AppImage)
```
-📖 完全なドキュメント：[`electron/README.md`](electron/README.md)
+### 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
-| 階層 | プロバイダー | コスト | クォータのリセット | 最適な用途 |
-| ------------------------- | -------------------------- | -------------------------- | ------------------- | ------------------ |
-| **💳 サブスクリプション** | クロード・コード (プロ) | $20/月 | 5 時間 + 毎週 | すでに購読済み |
-| | コーデックス (プラス/プロ) | $20-200/月 | 5 時間 + 毎週 | OpenAI ユーザー |
-| | ジェミニ CLI | **無料** | 180K/月 + 1K/日 | みんな！ |
-| | GitHub コパイロット | $10-19/月 | 月刊 | GitHub ユーザー |
-| **🔑 API キー** | NVIDIA NIM | **無料** (1000 クレジット) | ワンタイム | 無料枠のテスト |
-| | ディープシーク | 従量課金制 | なし | 最高の価格/品質 |
-| | グロク | 無料利用枠 + 有料 | レート制限 | 超高速推論 |
-| | xAI (グロック) | 従量課金制 | なし | Grok モデル |
-| | ミストラル | 無料利用枠 + 有料 | レート制限 | ヨーロッパのAI |
-| | オープンルーター | 従量課金制 | なし | 100 以上のモデル |
-| **💰安い** | GLM-4.7 | $0.6/100万 | 毎日午前 10 時 | 予算のバックアップ |
-| | ミニマックス M2.1 | $0.2/100万 | 5時間ローリング | 最も安いオプション |
-| | キミ K2 | 月額 9 ドルのフラット | 1,000 万トークン/月 | 予測可能なコスト |
-| **🆓 無料** | iFlow | $0 | 無制限 | 8 モデルは無料 |
-| | クウェン | $0 | 無制限 | 3 モデルは無料 |
-| | キロ | $0 | 無制限 | クロード・フリー |
+| 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 |
+| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |
+| | 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** | iFlow | **$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 |
-**💡 プロのヒント:** Gemini CLI (180,000 無料/月) + iFlow (無制限の無料) コンボ = コスト 0 ドルから始めましょう!
+> 🆕 **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
+iFlow (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
-| 特集 | 何をするのか |
-| ------------------------------------------- | ----------------------------------------------------------------------------------- |
-| 🎯 **スマート 4 層フォールバック** | 自動ルート: サブスクリプション → API キー → 格安 → 無料 |
-| 📊 **リアルタイムのクォータ追跡** | プロバイダーごとのライブ トークン数 + リセット カウントダウン |
-| 🔄 **フォーマット変換** | OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro シームレス + 応答サニタイズ |
-| 👥 **マルチアカウントのサポート** | インテリジェントな選択によるプロバイダーごとの複数のアカウント |
-| 🔄 **自動トークン更新** | OAuth トークンは再試行によって自動的に更新されます。 |
-| 🎨 **カスタムコンボ** | 6 つの戦略: フィルファースト、ラウンドロビン、p2c、ランダム、最小使用、コスト最適化 |
-| 🧩 **カスタムモデル** | 任意のモデル ID を任意のプロバイダーに追加する |
-| 🌐 **ワイルドカードルーター** | `provider/*` パターンを任意のプロバイダーに動的にルーティングする |
-| 🧠 **予算を考える** | 推論モデルのパススルー、自動、カスタム、および適応モード |
-| 🔀 **Model Aliases** | Auto-forward deprecated model IDs to current replacements (built-in + custom) |
-| ⚡ **Background Degradation** | Auto-route background tasks (titles, summaries) to cheaper models |
-| 💬 **システム プロンプト インジェクション** | すべてのリクエストに適用されるグローバル システム プロンプト |
-| 📄 **レスポンス API** | Codex の OpenAI Response API (`/v1/responses`) の完全なサポート |
+> 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.
-### 🎵 マルチモーダル API
+### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)
-| 特集 | 何をするのか |
-| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 🖼️ **画像生成** | `/v1/images/generations` — 4 つのプロバイダー、9 つ以上のモデル |
-| 📐 **埋め込み** | `/v1/embeddings` — 6 つのプロバイダー、9 つ以上のモデル |
-| 🎤 **音声文字起こし** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |
-| 🔊 **テキスト読み上げ** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) |
-| 🛡️ **モデレーション** | `/v1/moderations` — コンテンツの安全性チェック |
-| 🔀 **再ランキング** | `/v1/rerank` — ドキュメントの関連性の再ランキング |
+| 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 |
-### 🛡️ 復元力とセキュリティ
+### 🟢 IFLOW MODELS (Free OAuth — No Credit Card)
-| 特集 | 何をするのか |
-| -------------------------------- | ---------------------------------------------------------------------------- |
-| 🔌 **サーキットブレーカー** | 設定可能なしきい値によるプロバイダーごとの自動開閉 |
-| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |
-| 🛡️ **対雷鳴の群れ** | API キープロバイダーのミューテックス + セマフォのレート制限 |
-| 🧠 **セマンティック キャッシュ** | 2 層キャッシュ (シグネチャ + セマンティック) によりコストと遅延が削減 |
-| ⚡ **冪等性のリクエスト** | 重複リクエストに対する 5 秒の重複除去ウィンドウ |
-| 🔒 **TLS 指紋スプーフィング** | wreq-js 経由で TLS ベースのボット検出をバイパスする |
-| 🌐 **IP フィルタリング** | API アクセス制御の許可リスト/ブロックリスト |
-| 📊 **編集可能なレート制限** | システム レベルで構成可能な RPM、最小ギャップ、最大同時実行 |
-| 💾 **Rate Limit Persistence** | Learned limits survive restarts via SQLite with 60s debounce + 24h staleness |
-| 🔄 **Token Refresh Resilience** | Per-provider circuit breaker (5 fails→30min) + 30s timeout per attempt |
-| 🛡 **API エンドポイント保護** | `/models` エンドポイントの認証ゲート + プロバイダー ブロック |
-| 🔒 **プロキシの可視性** | 色分けされたバッジ: 🟢 グローバル、🟡 プロバイダー、🔵 IP 表示による接続ごと |
-| 🌐 **3 レベルのプロキシ構成** | グローバル、プロバイダーごと、または接続ごとのレベルでプロキシを構成する |
+| 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 |
-### 📊 可観測性と分析
+### 🟡 QWEN MODELS (Device Code Auth)
-| 特集 | 何をするのか |
-| -------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| 📝 **リクエストログ** | 完全なリクエスト/レスポンス ログを含むデバッグ モード |
-| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |
-| 💾 **SQLite プロキシ ログ** | 永続的なプロキシ ログはサーバーの再起動後も存続します。 |
-| 📊 **分析ダッシュボード** | Recharts を活用: 統計カード、モデル使用状況チャート、プロバイダー テーブル |
-| 📈 **進捗状況の追跡** | ストリーミング用の SSE 進行状況イベントをオプトインする |
-| 🧪 **LLM 評価** | 4 つの試合戦略によるゴールデン セット テスト |
-| 🔍 **テレメトリのリクエスト** | p50/p95/p99 レイテンシ集計 + X-Request-Id トレース |
-| 📋 **ログ ダッシュボード** | 統合された 4 つのタブ ページ: リクエスト ログ、プロキシ ログ、監査ログ、コンソール |
-| 🖥️ **コンソール ログ ビューア** | レベルフィルター、検索、自動スクロール機能を備えたリアルタイムターミナルスタイルのビューア |
-| 📑 **ファイルベースのロギング** | コンソール インターセプターは、ローテーションを使用してすべての出力を JSON ログ ファイルにキャプチャします。 |
-| 🏥 **健康ダッシュボード** | システム稼働時間、サーキット ブレーカーの状態、ロックアウト、キャッシュ統計 |
-| 💰 **コスト追跡** | 予算管理 + モデルごとの価格設定 |
+| 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) |
-### ☁️ 導入と同期
+### 🟣 GEMINI CLI (Google OAuth)
-| 特集 | 何をするのか |
-| ----------------------------------- | ----------------------------------------------------------------------------------- |
-| 💾 **クラウド同期** | Cloudflare Workers 経由でデバイス間で構成を同期する |
-| 🌐 **どこにでも展開** | Localhost、VPS、Docker、Cloudflare ワーカー |
-| 🔑 **API キー管理** | プロバイダーごとに API キーを生成、ローテーション、スコープ設定する |
-| 🧙 **オンボーディング ウィザード** | 初めてのユーザーのための 4 ステップのガイド付きセットアップ |
-| 🔧 **CLI ツール ダッシュボード** | Claude、Codex、Cline、OpenClaw、Kilo、Antigravity をワンクリックで設定 |
-| 🔄 **DB バックアップ** | すべての設定の自動バックアップ、復元、エクスポートとインポート |
-| 🌐 **国際化** | next-intl を備えた完全な i18n — 英語 + ポルトガル語 (ブラジル) のサポート |
-| 🌍 **言語セレクター** | リアルタイム言語切り替え用のヘッダーの地球儀アイコン (🇺🇸/🇧🇷) |
-| 🧹 **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 |
-| 📂 **カスタム データ ディレクトリ** | デフォルトの `~/.omniroute` ストレージ パスをオーバーライドする `DATA_DIR` 環境変数 |
+| Model | Prefix | Limit | Rate Limit |
+| ------------------------ | ------ | --------------------------- | ------------- |
+| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |
+| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |
+
+### ⚫ 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
+> iFlow (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 v2.0 is built as an operational platform, not just a relay proxy.
+
+### 🆕 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 Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |
+| 🤖 **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 (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) |
+| 🤝 **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** | 9 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 combo, apply resilience profiles, reset breakers from one control surface |
+
+### 🧠 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** | 6 balancing strategies + fallback chain control |
+| 🌐 **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) |
+| 💬 **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 |
+| ----------------------------------- | -------------------------------------------------------------------------------------- |
+| 🔌 **Circuit Breakers** | Per-model trip/recover with threshold controls |
+| 🎯 **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 |
+| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |
+| 🔑 **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 |
+
+### 📊 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 |
+| 📋 **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 |
+
+### ☁️ Deployment & Platform
+
+| Feature | What It Does |
+| ----------------------------- | --------------------------------------------------------- |
+| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |
+| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |
+| 💾 **Cloud Sync** | Configuration sync via cloud worker |
+| 🔄 **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 |
+
+### Feature Deep Dive
+
+#### Smart fallback with practical cost control
+
+```txt
+Combo: "my-coding-stack"
+ 1. cc/claude-opus-4-6
+ 2. nvidia/llama-3.3-70b
+ 3. glm/glm-4.7
+ 4. if/kimi-k2-thinking
+```
+
+When quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.
+
+#### 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)
+
+#### 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)
🚀 30. 「グルーコードのスプロールなしでエージェント ワークフローを出荷する必要がある」
+🚀 30. "I need to ship agentic workflows without glue-code sprawl"
-複数のアドホック サービスとスクリプトをつなぎ合わせると、チームの速度が低下します。 +Teams lose velocity when stitching multiple ad-hoc services and scripts. -**OmniRoute がそれを解決する方法:** +**How OmniRoute solves it:** -- クライアントとエージェント向けの統合エンドポイント戦略 -- 組み込みのプロトコル管理 UI とスモーク検証パス -- 本番環境に対応した基盤 (セキュリティ、ロギング、復元力、バックアップ) +- Unified endpoint strategy for clients and agents +- Built-in protocol management UIs and smoke validation paths +- Production-ready foundations (security, logging, resilience, backup)
-` ブロック → 思考モデル用の `reasoning_content`
-- **構造化された出力** — `json_schema` → Gemini の `responseMimeType`/`responseSchema`
-
-### 👥 マルチアカウントのサポート
-
-- プロバイダーごとに複数のアカウントを追加
-- 自動ラウンドロビンまたは優先順位ベースのルーティング
-- クォータに達した場合、次のアカウントにフォールバックします
-
-### 🔄 自動トークン更新
-
-- OAuth トークンは有効期限が切れる前に自動的に更新されます
-- 手動による再認証は必要ありません
-- すべてのプロバイダーにわたるシームレスなエクスペリエンス
-
-### 🎨 カスタムコンボ
-
-- 無制限のモデルの組み合わせを作成
-- 6 つの戦略: フィルファースト、ラウンドロビン、2 つの選択肢の累乗、ランダム、最小使用、コスト最適化
-- Cloud Sync を使用してデバイス間でコンボを共有
-
-### 🏥 健康ダッシュボード
-
-- システムステータス (稼働時間、バージョン、メモリ使用量)
-- プロバイダーごとのサーキットブレーカーの状態 (クローズ/オープン/ハーフオープン)
- | 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |
-- レート制限ステータスとアクティブなロックアウト
-- 署名キャッシュ統計
-- レイテンシ テレメトリ (p50/p95/p99) + プロンプト キャッシュ
-- ワンクリックで健康状態をリセット
-
-### 🔧 翻訳者の遊び場
-
-OmniRoute には、API 翻訳のデバッグ、テスト、監視のための **4 つのモード**を備えた強力な組み込みのトランスレータ プレイグラウンドが含まれています。
-
-| モード | 説明 |
-| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **💻遊び場** | 直接形式変換 — API リクエスト本文を貼り付けると、OmniRoute がプロバイダー形式 (OpenAI ↔ Claude ↔ Gemini ↔ Responses API) 間でそれをどのように変換するかを即座に確認できます。テンプレートの例と形式の自動検出が含まれています。 |
-| **💬 チャット テスター** | 実際のチャット リクエストを OmniRoute 経由で送信すると、入力、翻訳されたリクエスト、プロバイダーの応答、そして返される翻訳された応答という完全なラウンドトリップを確認できます。コンボ ルーティングを検証するのに非常に役立ちます。 |
-| **🧪 テストベンチ** | バッチ テスト モード - 異なる入力と予想される出力を持つ複数のテスト ケースを定義し、それらをすべて一度に実行し、プロバイダーやモデル間で結果を比較します。 |
-| **📱 ライブモニター** | リアルタイムのリクエスト監視 — 受信リクエストが OmniRoute を通過するのを監視し、ライブで行われているフォーマット変換を確認し、問題を即座に特定します。 |
-
-**アクセス:** ダッシュボード → トランスレーター (サイドバー)
-
-### 💾 クラウド同期
-
-- デバイス間でプロバイダー、コンボ、設定を同期します
-- 自動バックグラウンド同期
-- 安全な暗号化ストレージ
+- `GET /api/mcp/status`
+- `GET /api/mcp/tools`
+- `GET /api/mcp/audit`
+- `GET /api/mcp/audit/stats`
-## 🧪 評価 (Evals)
+📖 機能の詳細
+🧩 MCP Setup (Model Context Protocol)
-### 🎯 スマート 4 層フォールバック +Start MCP transport in stdio mode: -自動フォールバックを使用してコンボを作成します。 - -``` -Combo: "my-coding-stack" - 1. cc/claude-opus-4-6 (your subscription) - 2. nvidia/llama-3.3-70b (free NVIDIA API) - 3. glm/glm-4.7 (cheap backup, $0.6/1M) - 4. if/kimi-k2-thinking (free fallback) - -→ Auto switches when quota runs out or errors occur +```bash +omniroute --mcp ``` -### 📊 リアルタイムのクォータ追跡 +Recommended validation flow: -- プロバイダーごとのトークン消費量 -- リセットカウントダウン（5時間、毎日、毎週） -- 有料レベルのコストの見積もり -- 毎月の支出レポート +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: -フォーマット間でのシームレスな翻訳: - -- **OpenAI** ↔ **クロード** ↔ **ジェミニ** ↔ **OpenAI の応答** -- CLI ツールが OpenAI 形式を送信 → OmniRoute が変換 → プロバイダーがネイティブ形式を受信 -- カスタム OpenAI エンドポイントをサポートするあらゆるツールと連携 -- **レスポンスのサニタイズ** — 厳密な OpenAI SDK 互換性のために非標準フィールドを削除します -- **ロールの正規化** — 非 OpenAI の場合は `developer` → `system`。 `system` → `user` (GLM/ERNIE モデルの場合) -- **思考タグの抽出** — `
+
🤝 A2A Setup (Agent2Agent)
-OmniRoute には、ゴールデン セットに対して LLM 応答品質をテストするための評価フレームワークが組み込まれています。ダッシュボードの **Analytics → Evals** からアクセスします。 +Discover the agent: -### 内蔵ゴールデンセット +```bash +curl http://localhost:20128/.well-known/agent.json +``` -プリロードされた「OmniRoute Golden Set」には、以下をカバーする 10 のテスト ケースが含まれています。 +Send a task: -- 挨拶、数学、地理、コード生成 -- JSON形式への準拠、翻訳、マークダウン -- 安全拒否（有害なコンテンツ）、カウント、ブール論理 +```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."}]}}' +``` -### 評価戦略 +Manage lifecycle: -| 戦略 | 説明 | 例 | -| ---------- | ------------------------------------------------------------------------------------------- | ----------- | -| `exact` | 出力は正確に一致する必要があります | `"4"` | -| `contains` | 出力には部分文字列が含まれている必要があります (大文字と小文字は区別されません)。 `"Paris"` | -| `regex` | 出力は正規表現パターンと一致する必要があります | `"1.*2.*3"` | -| `custom` | カスタム JS 関数は true/false を返します。 `(output) => output.length > 10` | +- `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
-### クロード コード (Pro/Max) +Validate both protocols with real clients: + +```bash +npm run test:protocols:e2e +``` + +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) ```bash Dashboard → Providers → Connect Claude Code @@ -1068,9 +1438,9 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**プロのヒント:** 複雑なタスクには Opus を使用し、速度を求める場合は Sonnet を使用します。 OmniRoute はモデルごとの割り当てを追跡します。 +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! -### OpenAI コーデックス (プラス/プロ) +### OpenAI Codex (Plus/Pro) ```bash Dashboard → Providers → Connect Codex @@ -1082,7 +1452,24 @@ Models: cx/gpt-5.1-codex-max ``` -### Gemini CLI (月額 180,000 回無料!) +#### 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). + +### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -1094,9 +1481,9 @@ Models: gc/gemini-2.5-pro ``` -**ベストバリュー:** 膨大な無料枠!有料レベルの前にこれを使用してください。 +**Best Value:** Huge free tier! Use this before paid tiers. -### GitHub コパイロット +### GitHub Copilot ```bash Dashboard → Providers → Connect GitHub @@ -1112,87 +1499,88 @@ Models:
-
🔑 API キープロバイダー
+🔑 API Key Providers
-### NVIDIA NIM (無料 1000 クレジット!) +### NVIDIA NIM (FREE developer access — 70+ models) -1. サインアップ: [build.nvidia.com](https://build.nvidia.com) -2. 無料の API キーを取得します (1000 推論クレジットが含まれます) -3. ダッシュボード → プロバイダーの追加 → NVIDIA NIM: - - API キー: `nvapi-your-key` +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` -**モデル:** `nvidia/llama-3.3-70b-instruct`、`nvidia/mistral-7b-instruct`、および 50 以上 +**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more -**プロのヒント:** OpenAI 互換 API — OmniRoute のフォーマット変換とシームレスに連携します。 +**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation! -### ディープシーク +### DeepSeek -1. サインアップ: [platform.deepseek.com](https://platform.deepseek.com) -2. APIキーを取得する -3. ダッシュボード → プロバイダーの追加 → DeepSeek +1. Sign up: [platform.deepseek.com](https://platform.deepseek.com) +2. Get API key +3. Dashboard → Add Provider → DeepSeek -**モデル:** `deepseek/deepseek-chat`、`deepseek/deepseek-coder` +**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` -### Groq (無料利用枠あり!) +### Groq (Free Tier Available!) -1. サインアップ: [console.groq.com](https://console.groq.com) -2. API キーを取得します (無料利用枠を含む) -3. ダッシュボード → プロバイダーの追加 → Groq +1. Sign up: [console.groq.com](https://console.groq.com) +2. Get API key (free tier included) +3. Dashboard → Add Provider → Groq -**モデル:** `groq/llama-3.3-70b`、`groq/mixtral-8x7b` +**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` -**プロのヒント:** 超高速推論 — リアルタイム コーディングに最適です。 +**Pro Tip:** Ultra-fast inference — best for real-time coding! -### OpenRouter (100 以上のモデル) +### OpenRouter (100+ Models) -1. サインアップ: [openrouter.ai](https://openrouter.ai) -2. APIキーを取得する -3. ダッシュボード → プロバイダーの追加 → OpenRouter +1. Sign up: [openrouter.ai](https://openrouter.ai) +2. Get API key +3. Dashboard → Add Provider → OpenRouter -**モデル:** 単一の API キーを通じて、すべての主要プロバイダーの 100 以上のモデルにアクセスします。 +**Models:** Access 100+ models from all major providers through a single API key.
-
💰 格安プロバイダー (バックアップ)
+💰 Cheap Providers (Backup)
-### GLM-4.7 (毎日リセット、0.6 ドル/100 万ドル) +### GLM-4.7 (Daily reset, $0.6/1M) -1. サインアップ: [Zhipu AI](https://open.bigmodel.cn/) 2.コーディングプランからAPIキーを取得 -2. ダッシュボード → API キーの追加: - - プロバイダー: `glm` - - API キー: `your-key` +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` -**使用方法:** `glm/glm-4.7` +**Use:** `glm/glm-4.7` -**プロのヒント:** コーディング プランでは、1/7 のコストで 3 倍の割り当てを提供します。毎日午前 10 時にリセットされます。 +**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -### MiniMax M2.1 (5 時間リセット、$0.20/1M) +### MiniMax M2.1 (5h reset, $0.20/1M) -1. サインアップ: [MiniMax](https://www.minimax.io/) -2. APIキーを取得する -3. ダッシュボード → APIキーの追加 +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key +3. Dashboard → Add API Key -**使用方法:** `minimax/MiniMax-M2.1` +**Use:** `minimax/MiniMax-M2.1` -**プロのヒント:** 長いコンテキスト (100 万トークン) の最も安価なオプション! +**Pro Tip:** Cheapest option for long context (1M tokens)! -### キミ K2 (月額一律 $9) +### Kimi K2 ($9/month flat) -1. 購読: [Moonshot AI](https://platform.moonshot.ai/) -2. APIキーを取得する -3. ダッシュボード → APIキーの追加 +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key +3. Dashboard → Add API Key -**使用方法:** `kimi/kimi-latest` +**Use:** `kimi/kimi-latest` -**プロのヒント:** 1,000 万トークンの固定 $9/月 = 0.90 ドル/100 万の実効コスト! +**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
-
🆓 無料プロバイダー (緊急バックアップ)
+🆓 FREE Providers (Emergency Backup)
-### iFlow (8 つの無料モデル) +### iFlow (5 FREE models via OAuth) ```bash Dashboard → Connect iFlow @@ -1207,7 +1595,7 @@ Models: if/deepseek-r1 ``` -### Qwen (3 つの無料モデル) +### Qwen (4 FREE models via Device Code) ```bash Dashboard → Connect Qwen @@ -1219,7 +1607,7 @@ Models: qw/qwen3-coder-flash ``` -### キロ (クロード・フリー) +### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro @@ -1234,9 +1622,9 @@ Models:
-
🎨 コンボを作成
+🎨 Create Combos
-### 例 1: サブスクリプションを最大化 → 安価なバックアップ +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -1250,7 +1638,7 @@ Models: Use in CLI: premium-coding ``` -### 例 2: 無料のみ (コストゼロ) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -1265,9 +1653,9 @@ Cost: $0 forever!
-
---
-## 🐛 トラブルシューティング
+## トラブルシューティング
🔧 CLI 統合
+🔧 CLI Integration
-### カーソル IDE +### Cursor IDE ``` Settings → Models → Advanced: @@ -1276,11 +1664,11 @@ Settings → Models → Advanced: Model: cc/claude-opus-4-6 ``` -### クロードコード +### Claude Code -ダッシュボードの **CLI ツール** ページを使用してワンクリック構成するか、`~/.claude/settings.json` を手動で編集します。 +Use the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually. -### コーデックス CLI +### Codex CLI ```bash export OPENAI_BASE_URL="http://localhost:20128" @@ -1289,15 +1677,15 @@ export OPENAI_API_KEY="your-omniroute-api-key" codex "your prompt" ``` -### オープンクロー +### OpenClaw -**オプション 1 — ダッシュボード (推奨):** +**Option 1 — Dashboard (recommended):** ``` Dashboard → CLI Tools → OpenClaw → Select Model → Apply ``` -**オプション 2 — 手動:** `~/.openclaw/openclaw.json` を編集: +**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`: ```json { @@ -1313,9 +1701,9 @@ Dashboard → CLI Tools → OpenClaw → Select Model → Apply } ``` -> **注:** OpenClaw はローカル OmniRoute でのみ機能します。 IPv6 解決の問題を回避するには、`localhost` ではなく `127.0.0.1` を使用してください。 +> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues. -### クライン / 継続 / RooCode +### Cline / Continue / RooCode ``` Settings → API Configuration: @@ -1325,110 +1713,245 @@ Settings → API Configuration: 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. +
-
-- **ランタイム**: Node.js 18–22 LTS (⚠️ Node.js 24+ は **サポートされていません** — `better-sqlite3` ネイティブ バイナリは互換性がありません)
-- **言語**: TypeScript 5.9 — `src/` および `open-sse/` で **100% TypeScript** (v1.0.6)
-- **フレームワーク**: Next.js 16 + React 19 + Tailwind CSS 4
-- **データベース**: LowDB (JSON) + SQLite (ドメイン状態 + プロキシ ログ)
-- **ストリーミング**: サーバー送信イベント (SSE)
-- **認証**: OAuth 2.0 (PKCE) + JWT + API キー
-- **テスト**: Node.js テスト ランナー (368 以上の単体テスト)
-- **CI/CD**: GitHub アクション (自動 npm パブリッシュ + リリース時の Docker Hub)
-- **ウェブサイト**: [omniroute.online](https://omniroute.online)
-- **パッケージ**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
-- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
-- **復元力**: サーキット ブレーカー、エクスポネンシャル バックオフ、サンダーリング ハード対策、TLS スプーフィング
-
----
-
-## 📖 ドキュメント
-
-| ドキュメント | 説明 |
-| -------------------------------------------- | -------------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | プロバイダー、コンボ、CLI 統合、展開 |
-| [API Reference](docs/API_REFERENCE.md) | すべてのエンドポイントと例 |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | よくある問題と解決策 |
-| [Architecture](docs/ARCHITECTURE.md) | システム アーキテクチャと内部構造 |
-| [Contributing](CONTRIBUTING.md) | 開発セットアップとガイドライン |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 仕様 |
-| [Security Policy](SECURITY.md) | 脆弱性の報告とセキュリティの実践 |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | 完全ガイド: VM + nginx + Cloudflare セットアップ |
-| [Features Gallery](docs/FEATURES.md) | スクリーンショットを含むビジュアル ダッシュボード ツアー |
-
-### 📸 ダッシュボードのプレビュー
+## 🛠️ Tech Stack
クリックしてトラブルシューティング ガイドを展開
+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** -- サブスクリプション クォータ アウト → GLM/MiniMax へのフォールバック -- コンボを追加: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Subscription quota out → Fallback to GLM/MiniMax +- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -**OAuth トークンの有効期限が切れました** +**OAuth token expired** -- OmniRouteによる自動更新 -- 問題が解決しない場合: ダッシュボード → プロバイダー → 再接続 +- Auto-refreshed by OmniRoute +- If issues persist: Dashboard → Provider → Reconnect -**高コスト** +**High costs** -- [ダッシュボード] → [コスト] で使用状況の統計を確認します。 -- プライマリ モデルを GLM/MiniMax に切り替えます -- 重要ではないタスクには無料枠 (Gemini CLI、iFlow) を使用する +- Check usage stats in Dashboard → Costs +- Switch primary model to GLM/MiniMax +- Use free tier (Gemini CLI, iFlow) for non-critical tasks -**ダッシュボードが間違ったポートで開きます** +**Dashboard/API ports are wrong** -- `PORT=20128` および `NEXT_PUBLIC_BASE_URL=http://localhost:20128` を設定します +- `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** -- `BASE_URL` が実行中のインスタンスを指していることを確認します -- `CLOUD_URL` が予想されるクラウド エンドポイントを指していることを確認します -- `NEXT_PUBLIC_*` 値をサーバー側の値と一致させます。 +- 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** -- `.env` の `INITIAL_PASSWORD` を確認してください -- 設定されていない場合、フォールバック パスワードは `123456` です +- Check `INITIAL_PASSWORD` in `.env` +- If unset, fallback password is `123456` -**リクエストログなし** +**No request logs** -- `.env` に `ENABLE_REQUEST_LOGS=true` を設定します +- Set `ENABLE_REQUEST_LOGS=true` in `.env` -**OpenAI 互換プロバイダーの接続テストで「無効」と表示される** +**Connection test shows "Invalid" for OpenAI-compatible providers** -- 多くのプロバイダーは `/models` エンドポイントを公開していません -- OmniRoute v1.0.6+ には、チャット完了によるフォールバック検証が含まれています -- ベース URL に `/v1` サフィックスが含まれていることを確認してください +- 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 (リモート OAuth セットアップ) +### 🔐 OAuth on a Remote Server + -> **⚠️ VPS/Docker/サーバーリモートの OmniRoute に関する重要事項** +> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server** -### OAuth +#### Why does Antigravity / Gemini CLI OAuth fail on remote servers? -**反重力** と **Gemini CLI** を使用して **Google OAuth 2.0** を認証します。 O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas Google Cloud Console でアプリケーションを実行できません。 +The **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console. -認証情報として OAuth は、`localhost`\*\* の OmniRoute データベース管理機能を備えていません。 OmniRoute サーバー リモートへのアクセス (例: `https://omniroute.meuservidor.com`)、Google による認証: +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 ``` -### 解決策: OAuth の固有資格情報を構成する +#### Solution: Configure your own OAuth credentials -**OAuth 2.0 クライアント ID** では、Google Cloud Console の URI がサーバーを参照するための正確な基準が設定されています。 +You need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI. -#### パッソ ア パッソ +#### Step-by-step -**1. Google Cloud コンソールへのアクセス** +**1. Open Google Cloud Console** -アブラ: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) +Go to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) -**2.新しい OAuth 2.0 クライアント ID** +**2. Create a new OAuth 2.0 Client ID** -- Clique em **「+ 認証情報の作成」** → **「OAuth クライアント ID」** -- 応用情報: **「Web アプリケーション」** -- 名前: escolha qualquer 名前 (例: `OmniRoute Remote`) +- Click **"+ Create Credentials"** → **"OAuth client ID"** +- Application type: **"Web application"** +- Name: anything you like (e.g. `OmniRoute Remote`) -**3.承認されたリダイレクト URI としての Adicione** +**3. Add Authorized Redirect URIs** -**「承認されたリダイレクト URI」** はありません、アディシオン: +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 + +# For Gemini CLI: +GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com +GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +``` + +**6. Restart OmniRoute** + +```bash +# npm: +npm run dev + +# Docker: +docker restart omniroute +``` + +**7. Try connecting again** + +Dashboard → Providers → Antigravity (or Gemini CLI) → OAuth + +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. + +--- + +
+
---
-## 🛠️
+🇧🇷 Versão em Português
+ +#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos? + +Os provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo. + +As credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticação com: + +``` +Error 400: redirect_uri_mismatch +``` + +#### Solução: Configure suas próprias credenciais OAuth + +Você precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor. + +#### Passo a passo + +**1. Acesse o Google Cloud Console** + +Abra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) + +**2. Crie um novo OAuth 2.0 Client ID** + +- Clique em **"+ Create Credentials"** → **"OAuth client ID"** +- Tipo de aplicativo: **"Web application"** +- Nome: escolha qualquer nome (ex: `OmniRoute Remote`) + +**3. Adicione as Authorized Redirect URIs** + +No campo **"Authorized redirect URIs"**, adicione: ``` https://seu-servidor.com/callback ``` -> `seu-servidor.com` を IP サーバーとして置き換えてください (必要なポータルを含む、例: `http://45.33.32.156:20128/callback`)。 +> Substitua `seu-servidor.com` pelo domínio ou IP do seu servidor (inclua a porta se necessário, ex: `http://45.33.32.156:20128/callback`). -**4.コピーを認証情報として保存** +**4. Salve e copie as credenciais** -Google のほとんどの情報、**クライアント ID**、または **クライアント シークレット** を使用してください。 +Após criar, o Google mostrará o **Client ID** e o **Client Secret**. -**5.環境変数として設定** +**5. Configure as variáveis de ambiente** -`.env` は使用できません (Docker の環境変数を変更します): +No seu `.env` (ou nas variáveis de ambiente do Docker): ```bash # Para Antigravity: @@ -1441,7 +1964,7 @@ GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret ``` -**6.レイニシー・オ・オムニルート** +**6. Reinicie o OmniRoute** ```bash # Se usando npm: @@ -1451,148 +1974,147 @@ npm run dev docker restart omniroute ``` -**7.テンテ コネクター ノヴァメンテ** +**7. Tente conectar novamente** -ダッシュボード → プロバイダー → Antigravity (Gemini CLI) → OAuth +Dashboard → Providers → Antigravity (ou Gemini CLI) → OAuth -`https://seu-servidor.com/callback` の認証機能を Google でリダイレクトして修正します。 +Agora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará. --- -### 一時的な回避策 (資格情報を適切に設定する) +#### Workaround temporário (sem configurar credenciais próprias) -**URL のマニュアル**: +Se não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**: -1. OmniRoute は Google の自動 URL を提供します -2. `localhost` による Google の自動リダイレクト (サーバー リモートの要求) -3. **URL をコピーしてください** ブラウザを使用してブラウザを開きます (カレーグのページを表示します) -4. コール エッサ URL は、OmniRoute の接続モーダルなしです。 -5. クリーク**「接続」** +1. O OmniRoute abrirá a URL de autorização do Google +2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto) +3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue) +4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute +5. Clique em **"Connect"** -> 自動回避策の機能は URL から独立してリダイレクトされます。 +> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.
-
---
-## 🗺️
+## ドキュメント
-OmniRoute には、複数の開発フェーズにわたって **210 以上の機能が計画されています**。主要な領域は次のとおりです。
-
-| カテゴリー | 計画されている機能 | ハイライト |
-| ------------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------- |
-| 🧠 **ルーティングとインテリジェンス** | 25+ | 最低レイテンシのルーティング、タグベースのルーティング、クォータ プリフライト、P2C アカウントの選択 |
-| 🔒 **セキュリティとコンプライアンス** | 20歳以上 | SSRF の強化、資格情報のクローキング、エンドポイントごとのレート制限、管理キーのスコーピング |
-| 📊 **可観測性** | 15 歳以上 | OpenTelemetry 統合、リアルタイム クォータ監視、モデルごとのコスト追跡 |
-| 🔄 **プロバイダーの統合** | 20歳以上 | 動的モデル レジストリ、プロバイダーのクールダウン、マルチアカウント Codex、Copilot クォータ解析 |
-| ⚡ **パフォーマンス** | 15 歳以上 | デュアル キャッシュ レイヤー、プロンプト キャッシュ、応答キャッシュ、ストリーミング キープアライブ、バッチ API |
-| 🌐 **生態系** | 10+ | WebSocket API、構成ホットリロード、分散構成ストア、商用モード |
-
-### 🔜近日公開予定
-
-- 🔗 **OpenCode Integration** — OpenCode AI コーディング IDE のネイティブ プロバイダー サポート
-- 🔗 **TRAE 統合** — TRAE AI 開発フレームワークの完全サポート
-- 📦 **バッチ API** — 一括リクエストの非同期バッチ処理
-- 🎯 **タグベースのルーティング** — カスタムタグとメタデータに基づいてリクエストをルーティングします
-- 💰 **最低コスト戦略** — 利用可能な最も安価なプロバイダーを自動的に選択します
-
-> 📝 [link](docs/new-features/) で全機能の仕様が利用可能 (217 の詳細仕様)
+| Document | Description |
+| ---------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 16 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/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
+| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
-## 👥 貢献者
+## 🗺️ Roadmap
+
+OmniRoute has **210+ 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, P2C account selection |
+| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |
+| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |
+| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider 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
[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
-### 貢献方法
+### How to Contribute
-1. リポジトリをフォークする
-2. 機能ブランチを作成します (`git checkout -b feature/amazing-feature`)
-3. 変更をコミットします (`git commit -m 'Add amazing feature'`)
-4. ブランチにプッシュします (`git push origin feature/amazing-feature`)
-5. プルリクエストを開く
+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
-詳細なガイドラインについては、[CONTRIBUTING.md](CONTRIBUTING.md) を参照してください。
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
-### 新しいバージョンのリリース
+### Releasing a New Version
```bash
# Create a release — npm publish happens automatically
-gh release create v1.0.6 --title "v1.0.6" --generate-notes
+gh release create v2.0.0 --title "v2.0.0" --generate-notes
```
---
-## 📊 スターの歴史
+## 📊 Star History
## Stargazers over time
## [](https://starchart.cc/diegosouzapw/OmniRoute)
-## 🙏 謝辞
+## 🙏 Acknowledgments
-このフォークのきっかけとなった元のプロジェクトである **[decolua](https://github.com/decolua)** による **[9router](https://github.com/decolua/9router)** に感謝します。 OmniRoute は、追加機能、マルチモーダル API、完全な TypeScript の書き換えを備えた素晴らしい基盤の上に構築されています。
+Special thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.
-この JavaScript 移植のきっかけとなったオリジナルの Go 実装である **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** に感謝します。
+Special thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.
---
-## 📄 ライセンス
+## ライセンス
-MIT ライセンス - 詳細については、[LICENSE](LICENSE) を参照してください。
+MIT License - see [LICENSE](LICENSE) for details.
---
----
+クリックしてダッシュボードのスクリーンショットを表示
+Click to expand tech stack details
-| ページ | スクリーンショット | -| ------------------ | ------------------------------------------------- | -| **プロバイダー** |  | -| **コンボ** |  | -| **分析** |  | -| **健康** |  | -| **翻訳者** |  | -| **設定** |  | -| **CLI ツール** |  | -| **使用ログ** |  | -| **エンドポイント** |  | +- **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**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions) +- **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
+ Built with ❤️ for developers who code 24/7
+
+ omniroute.online +
+
diff --git a/docs/i18n/ja/docs/FEATURES.md b/docs/i18n/ja/docs/FEATURES.md
new file mode 100644
index 0000000000..9dd4c01ecf
--- /dev/null
+++ b/docs/i18n/ja/docs/FEATURES.md
@@ -0,0 +1,145 @@
+# OmniRoute — Dashboard Features Gallery (日本語)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/FEATURES.md) · 🇪🇸 [es](../../es/docs/FEATURES.md) · 🇫🇷 [fr](../../fr/docs/FEATURES.md) · 🇩🇪 [de](../../de/docs/FEATURES.md) · 🇮🇹 [it](../../it/docs/FEATURES.md) · 🇷🇺 [ru](../../ru/docs/FEATURES.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FEATURES.md) · 🇯🇵 [ja](../../ja/docs/FEATURES.md) · 🇰🇷 [ko](../../ko/docs/FEATURES.md) · 🇸🇦 [ar](../../ar/docs/FEATURES.md) · 🇮🇳 [in](../../in/docs/FEATURES.md) · 🇹🇭 [th](../../th/docs/FEATURES.md) · 🇻🇳 [vi](../../vi/docs/FEATURES.md) · 🇮🇩 [id](../../id/docs/FEATURES.md) · 🇲🇾 [ms](../../ms/docs/FEATURES.md) · 🇳🇱 [nl](../../nl/docs/FEATURES.md) · 🇵🇱 [pl](../../pl/docs/FEATURES.md) · 🇸🇪 [sv](../../sv/docs/FEATURES.md) · 🇳🇴 [no](../../no/docs/FEATURES.md) · 🇩🇰 [da](../../da/docs/FEATURES.md) · 🇫🇮 [fi](../../fi/docs/FEATURES.md) · 🇵🇹 [pt](../../pt/docs/FEATURES.md) · 🇷🇴 [ro](../../ro/docs/FEATURES.md) · 🇭🇺 [hu](../../hu/docs/FEATURES.md) · 🇧🇬 [bg](../../bg/docs/FEATURES.md) · 🇸🇰 [sk](../../sk/docs/FEATURES.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FEATURES.md) · 🇮🇱 [he](../../he/docs/FEATURES.md) · 🇵🇭 [phi](../../phi/docs/FEATURES.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FEATURES.md)
+
+---
+
+Visual guide to every section of the OmniRoute dashboard.
+
+---
+
+## 🔌 Providers
+
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
+
+
+
+---
+
+## 🎨 Combos
+
+Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
+
+
+
+---
+
+## 📊 Analytics
+
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
+
+
+
+---
+
+## 🏥 System Health
+
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+
+
+
+---
+
+## 🔧 Translator Playground
+
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
+
+
+
+---
+
+## 🎮 Model Playground _(v2.0.9+)_
+
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
+
+---
+
+## 🎨 Themes _(v2.0.5+)_
+
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
+
+## ⚙️ Settings
+
+Comprehensive settings panel with tabs:
+
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning
+- **Advanced** — Configuration overrides
+
+
+
+---
+
+## 🔧 CLI Tools
+
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
+
+
+
+---
+
+## 🤖 CLI Agents _(v2.0.11+)_
+
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
+
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
+
+---
+
+## 🖼️ Media _(v2.0.3+)_
+
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
+
+## 📝 Request Logs
+
+Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
+
+
+
+---
+
+## 🌐 API Endpoint
+
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
+
+
+
+---
+
+## 🔑 API Key Management
+
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
+
+---
+
+## 📋 Audit Log
+
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
+
+---
+
+## 🖥️ Desktop Application
+
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
+
+Key features:
+
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
+
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.
diff --git a/docs/i18n/ko/README.md b/docs/i18n/ko/README.md
index d39128dec6..b8622abcbf 100644
--- a/docs/i18n/ko/README.md
+++ b/docs/i18n/ko/README.md
@@ -1,24 +1,94 @@
-+ omniroute.online +
-
-
- # 🚀 OmniRoute — 무료 AI 게이트웨이
+# 🚀 OmniRoute — The Free AI Gateway (한국어)
-### 코딩을 멈추지 마세요. 자동 폴백을 통해 **무료 및 저가형 AI 모델**로 스마트 라우팅합니다.
-
-_범용 API 프록시 — 하나의 엔드포인트, 36개 이상의 공급자, 가동 중지 시간 없음._
-
-**채팅 완료 • 임베딩 • 이미지 생성 • 오디오 • 순위 재지정 • 100% TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 좋아하는 코딩 에이전트를 위한 무료 AI 제공업체
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_무제한 코딩을 위한 무료 API 게이트웨이인 OmniRoute를 통해 AI 기반 IDE 또는 CLI 도구를 연결하세요._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+` tags no longer leak to clients in SSE streaming responses (#585) |
+| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with per-provider/account quota enforcement, idempotency, SHA-256 storage, and optional GitHub issue reporting |
+| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG → generic fallback chain |
+| 🔄 **Model Auto-Sync** | 24h scheduler and manual UI toggle to sync model lists for built-in and custom OpenAI-compatible providers |
+| 🌐 **OpenCode Zen/Go** | Two new providers from @kang-heewon via PR #530: free tier + subscription tier via `OpencodeExecutor` |
+| 🐛 **Gemini CLI OAuth** | Actionable error when `GEMINI_OAUTH_CLIENT_SECRET` is missing in Docker (was cryptic Google error) |
+| 🐛 **OpenCode config** | `saveOpenCodeConfig()` now correctly writes TOML to `XDG_CONFIG_HOME` |
+| 🐛 **Pinned model override** | `body.model` correctly set to `pinnedModel` on context-cache protection |
+| 🐛 **Codex/Claude loop** | `tool_result` blocks now converted to text to stop infinite loops |
+| 🐛 **Login redirect** | Login no longer freezes after skipping password setup |
+| 🐛 **Windows paths** | MSYS2/Git-Bash paths (`/c/...`) normalized to `C:\...` automatically |
+
+---
+
+## 🖼️ Main Dashboard
+
+
-📡 모든 에이전트는 ` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**Stop wasting money and hitting limits:**
-### 🆕 What's New in v3.0.0
+- Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**OmniRoute solves this:**
+
+- ✅ **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
+- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool
---
-[](https://www.npmjs.com/package/omniroute)
-[](https://hub.docker.com/r/diegosouzapw/omniroute)
-[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
-[](https://omniroute.online)
-[](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
+## 📧 Support
-[🌐 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)
+> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.
-🌐 **Available in:** 🇺🇸 [English](../../README.md) | 🇧🇷 [Português (Brasil)](../pt-BR/README.md) | 🇪🇸 [Español](../es/README.md) | 🇫🇷 [Français](../fr/README.md) | 🇮🇹 [Italiano](../it/README.md) | 🇷🇺 [Русский](../ru/README.md) | 🇨🇳 [中文 (简体)](../zh-CN/README.md) | 🇩🇪 [Deutsch](../de/README.md) | 🇮🇳 [हिन्दी](../in/README.md) | 🇹🇭 [ไทย](../th/README.md) | 🇺🇦 [Українська](../uk-UA/README.md) | 🇸🇦 [العربية](../ar/README.md) | 🇯🇵 [日本語](../ja/README.md) | 🇻🇳 [Tiếng Việt](../vi/README.md) | 🇧🇬 [Български](../bg/README.md) | 🇩🇰 [Dansk](../da/README.md) | 🇫🇮 [Suomi](../fi/README.md) | 🇮🇱 [עברית](../he/README.md) | 🇭🇺 [Magyar](../hu/README.md) | 🇮🇩 [Bahasa Indonesia](../id/README.md) | 🇰🇷 [한국어](../ko/README.md) | 🇲🇾 [Bahasa Melayu](../ms/README.md) | 🇳🇱 [Nederlands](../nl/README.md) | 🇳🇴 [Norsk](../no/README.md) | 🇵🇹 [Português (Portugal)](../pt/README.md) | 🇷🇴 [Română](../ro/README.md) | 🇵🇱 [Polski](../pl/README.md) | 🇸🇰 [Slovenčina](../sk/README.md) | 🇸🇪 [Svenska](../sv/README.md) | 🇵🇭 [Filipino](../phi/README.md)
-
-
-
----
-
-## 🖼️
-
-
-
- # 🚀 OmniRoute — 무료 AI 게이트웨이
+# 🚀 OmniRoute — The Free AI Gateway (한국어)
-### 코딩을 멈추지 마세요. 자동 폴백을 통해 **무료 및 저가형 AI 모델**로 스마트 라우팅합니다.
-
-_범용 API 프록시 — 하나의 엔드포인트, 36개 이상의 공급자, 가동 중지 시간 없음._
-
-**채팅 완료 • 임베딩 • 이미지 생성 • 오디오 • 순위 재지정 • 100% TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 좋아하는 코딩 에이전트를 위한 무료 AI 제공업체
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_무제한 코딩을 위한 무료 API 게이트웨이인 OmniRoute를 통해 AI 기반 IDE 또는 CLI 도구를 연결하세요._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+
+
+[](https://www.npmjs.com/package/omniroute)
+[](https://www.npmjs.com/package/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
+[](https://omniroute.online)
+[](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)
+
+
+
+🌐 **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)
+
+---
+
+## 🆕 What's New in v3.0.0
+
+> **Upgrading from v2.9.5?** — See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes.
+
+| Area | Change |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection remediation |
+| ✅ **Route Validation** | All 176 API routes now validated with Zod schemas + `validateBody()` — CI `check:route-validation:t06` passes |
+| 🐛 **omniModel Tag Leak** | Internal `
+
+
+
+---
+
+## 📸 Dashboard Preview
+
+
+
+
+
+---
+
+### 🤖 Free AI Provider for your favorite coding agents
+
+_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._
Click to see dashboard screenshots
+ +| Page | Screenshot | +| -------------- | ------------------------------------------------- | +| **Providers** |  | +| **Combos** |  | +| **Analytics** |  | +| **Health** |  | +| **Translator** |  | +| **Settings** |  | +| **CLI Tools** |  | +| **Usage Logs** |  | +| **Endpoints** |  | + +|
-
+
OpenClaw @@ -92,113 +162,52 @@ _무제한 코딩을 위한 무료 API 게이트웨이인 OmniRoute를 통해 AI |
http://localhost:20128/v1 또는 http://cloud.omniroute.online/v1을 통해 연결됩니다. — 하나의 구성, 무제한 모델 및 할당량
+📡 All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 — one config, unlimited models and quota
---
-### 🆕 What's New in v3.0.0
+## 🤔 Why OmniRoute?
-| Area | Change |
-| ------------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal ` Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `
-
-
-
----
-
-## 📸
-
-
-
-
-
----
-
-## 🤔 왜 OmniRoute인가요?
-
-**돈을 낭비하지 말고 한도에 도달하지 마세요.**
-
-- ...
- -| # | # | -| ----- | ---------------------------------------- | -| **1** |  | -| **2** |  | -| **3** |  | -| **4** |  | -| **5** |  | -| **6** |  | -| **7** |  | -| **8** |  | -| **9** |  | - - 구독 할당량은 매달 사용하지 않은 채 만료됩니다.
-- 속도 제한으로 인해 코딩이 중단됩니다.
-- 고가의 API(공급자당 월 $20-50)
-- 공급자 간 수동 전환
-
-**OmniRoute는 이 문제를 해결합니다.**
-
-- ✅ **구독 극대화** - 할당량을 추적하고 재설정하기 전에 모든 비트를 사용하세요.
-- ✅ **자동 대체** - 구독 → API 키 → 저렴한 → 무료, 다운타임 없음
-- ✅ **다중 계정** - 공급자별 계정 간 라운드 로빈
-- ✅ **유니버설** - Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, 모든 CLI 도구와 함께 작동
-
----
-
-## 📧 지원
-
-> 💬 **커뮤니티에 가입하세요!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — 도움을 받고, 팁을 공유하고, 최신 소식을 받아보세요.
-
-- **웹사이트**: [omniroute.online](https://omniroute.online)
+- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **문제**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **원래 프로젝트**: [9router by decolua](https://github.com/decolua/9router)
+- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 작동 방식
+## 🔄 How It Works
```
┌─────────────┐
@@ -227,451 +236,453 @@ Result: Never stop coding, minimal cost
---
-## 🎯 OmniRoute가 해결하는 것 — 30가지 실제 문제점 및 사용 사례
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **AI 도구를 사용하는 모든 개발자는 매일 이러한 문제에 직면합니다.** OmniRoute는 비용 초과부터 지역적 차단, 손상된 OAuth 흐름부터 프로토콜 운영 및 기업 관찰 가능성까지 모든 문제를 해결하기 위해 구축되었습니다.
+> **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.
-
💸 1. "비싼 구독료를 지불했지만 여전히 한도 때문에 방해를 받습니다."
+💸 1. "I pay for an expensive subscription but still get interrupted by limits"
-개발자는 Claude Pro, Codex Pro 또는 GitHub Copilot에 대해 월 20~200달러를 지불합니다. 비용을 지불하더라도 할당량에는 5시간 사용량, 주간 한도 또는 분당 비율 한도 등 상한선이 있습니다. 코딩 세션이 진행되는 동안 공급자는 응답을 중단하고 개발자는 흐름과 생산성을 잃게 됩니다. +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. -**OmniRoute가 이를 해결하는 방법:** +**How OmniRoute solves it:** -- **스마트 4계층 폴백** — 구독 할당량이 소진되면 수동 개입 없이 자동으로 API 키 → 저렴함 → 무료로 리디렉션됩니다. -- **실시간 할당량 추적** — 재설정 카운트다운(5시간, 매일, 매주)을 통해 실시간으로 토큰 소비를 표시합니다. -- **다중 계정 지원** — 자동 라운드 로빈 기능을 갖춘 공급자당 여러 계정 — 하나가 소진되면 다음 계정으로 전환 -- **사용자 정의 콤보** — 6가지 균형 전략(채우기 우선, 라운드 로빈, P2C, 무작위, 최소 사용, 비용 최적화)을 갖춘 사용자 정의 가능한 폴백 체인 -- **Codex 비즈니스 할당량** — 대시보드에서 직접 비즈니스/팀 작업 공간 할당량 모니터링 +- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention +- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly) +- **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 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
-` 블록을 표준화된 `reasoning_content`로 추출합니다.
-- **Gemini용 구조화된 출력** — `json_schema` → `responseMimeType`/`responseSchema` 자동 변환
-- **`stream`의 기본값은 `false`** — OpenAI 사양에 맞춰 Python/Rust/Go SDK에서 예기치 않은 SSE를 방지합니다.
+- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 67+ 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
🔌 2. "여러 공급자를 사용해야 하는데 각각 API가 다릅니다"
+🔌 2. "I need to use multiple providers but each has a different API"
-OpenAI는 하나의 형식을 사용하고 Claude(Anthropic)는 또 다른 형식을 사용하고 Gemini는 또 다른 형식을 사용합니다. 개발자가 다른 제공업체의 모델을 테스트하거나 이들 사이에서 대체하려는 경우 SDK를 재구성하고, 엔드포인트를 변경하고, 호환되지 않는 형식을 처리해야 합니다. 사용자 지정 공급자(FriendLI, NIM)에는 비표준 모델 끝점이 있습니다. +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. -**OmniRoute가 이를 해결하는 방법:** +**How OmniRoute solves it:** -- **통합 엔드포인트** — 단일 `http://localhost:20128/v1`가 36개 이상의 모든 공급자에 대한 프록시 역할을 합니다. -- **형식 번역** — 자동 및 투명함: OpenAI ← Claude ← Gemini ← Responses API -- **응답 삭제** — OpenAI SDK v1.83+를 손상시키는 비표준 필드(`x_groq`, `usage_breakdown`, `service_tier`)를 제거합니다. -- **역할 정규화** — OpenAI가 아닌 제공업체에 대해 `developer` → `system`로 변환합니다. GLM/ERNIE의 경우 `system` → `user` -- **Think Tag Extraction** — DeepSeek R1과 같은 모델에서 `
-
🌐 3. "내 AI 공급자가 내 지역/국가를 차단합니다."
+🌐 3. "My AI provider blocks my region/country"
-OpenAI/Codex와 같은 공급자는 특정 지역의 액세스를 차단합니다. OAuth 및 API 연결 중에 사용자에게 `unsupported_country_region_territory`와 같은 오류가 발생합니다. 이는 특히 개발도상국의 개발자에게 실망스러운 일입니다. +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. -**OmniRoute가 이를 해결하는 방법:** +**How OmniRoute solves it:** -- **3레벨 프록시 구성** — 3가지 레벨로 구성 가능한 프록시: 글로벌(모든 트래픽), 공급자별(하나의 공급자만), 연결/키별 -- **색상으로 구분된 프록시 배지** — 시각적 표시기: 🟢 글로벌 프록시, 🟡 공급자 프록시, 🔵 연결 프록시, 항상 IP 표시 -- **프록시를 통한 OAuth 토큰 교환** — OAuth 흐름도 프록시를 통과하여 `unsupported_country_region_territory`를 해결합니다. -- **프록시를 통한 연결 테스트** - 연결 테스트에서는 구성된 프록시를 사용합니다(더 이상 직접 우회 없음). -- **SOCKS5 지원** — 아웃바운드 라우팅을 위한 전체 SOCKS5 프록시 지원 -- **TLS 지문 스푸핑** — `wreq-js`를 통한 브라우저와 유사한 TLS 지문으로 봇 감지 우회 +- **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
-` prefix
-- **무료 전용 콤보** — 체인 `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/월, 가동 중지 시간 없음
-- **NVIDIA NIM 무료 크레딧** — 1000개의 무료 크레딧 통합
-- **비용 최적화 전략** — 가장 저렴한 공급자를 자동으로 선택하는 라우팅 전략
+- **Free-Only Combos** — Chain `gc/gemini-3-flash → 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
🆓 4. "AI로 코딩하고 싶은데 돈이 없어요"
+🆓 4. "I want to use AI for coding but I have no money"
-모든 사람이 AI 구독 비용으로 월 20~200달러를 지불할 수 있는 것은 아닙니다. 학생, 신흥 국가의 개발자, 취미생활자, 프리랜서는 무료로 고품질 모델에 액세스해야 합니다. +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. -**OmniRoute가 이를 해결하는 방법:** +**How OmniRoute solves it:** -- **무료 계층 제공자 내장** — 100% 무료 제공자에 대한 기본 지원: iFlow(8개 무제한 모델), Qwen(3개 무제한 모델), Kiro(Claude 무료), Gemini CLI(180K/월 무료) +- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free) - **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/
-
🔒 5. "AI 게이트웨이를 무단 액세스로부터 보호해야 합니다"
+🔒 5. "I need to protect my AI gateway from unauthorized access"
-AI 게이트웨이를 네트워크(LAN, VPS, Docker)에 노출하면 주소가 있는 사람은 누구나 개발자의 토큰/할당량을 사용할 수 있습니다. 보호하지 않으면 API는 오용, 즉각적인 주입, 남용에 취약해집니다. +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. -**OmniRoute가 이를 해결하는 방법:** +**How OmniRoute solves it:** -- **API 키 관리** — 전용 `/dashboard/api-manager` 페이지를 사용하여 공급자별 생성, 순환 및 범위 지정 -- **모델 수준 권한** — 모두 허용/제한 토글을 사용하여 API 키를 특정 모델(`openai/*`, 와일드카드 패턴)로 제한합니다. -- **API 엔드포인트 보호** — `/v1/models`에 대한 키가 필요하며 목록에서 특정 공급자를 차단합니다. -- **Auth Guard + CSRF 보호** — `withAuth` 미들웨어 + CSRF 토큰으로 보호되는 모든 대시보드 경로 -- **속도 제한기** — 구성 가능한 창으로 IP당 속도 제한 -- **IP 필터링** — 액세스 제어를 위한 허용 목록/차단 목록 -- **프롬프트 주입 가드** — 악성 프롬프트 패턴 제거 -- **AES-256-GCM 암호화** — 저장된 자격 증명은 암호화됩니다. +- **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. "공급업체가 다운되어 코딩 흐름이 손실되었습니다."
+🛑 6. "My provider went down and I lost my coding flow"
-AI 제공자는 불안정해지거나, 5xx 오류를 반환하거나, 임시 속도 제한에 도달할 수 있습니다. 개발자가 단일 공급자에 의존하는 경우 중단됩니다. 회로 차단기가 없으면 반복적으로 재시도하면 애플리케이션이 중단될 수 있습니다. +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. -**OmniRoute가 이를 해결하는 방법:** +**How OmniRoute solves it:** -- **공급업체별 회로 차단기** — 구성 가능한 임계값 및 쿨다운을 통한 자동 열기/닫기(닫힘/열림/반열림) -- **지수 백오프** — 점진적인 재시도 지연 -- **Anti-Thundering Herd** — 동시 재시도 폭풍에 대한 뮤텍스 + 세마포어 보호 -- **콤보 폴백 체인** — 기본 공급자가 실패하면 개입 없이 자동으로 체인을 통과합니다. -- **콤보 회로 차단기** — 콤보 체인 내에서 실패한 공급자를 자동으로 비활성화합니다. -- **상태 대시보드** — 가동 시간 모니터링, 회로 차단기 상태, 잠금, 캐시 통계, p50/p95/p99 대기 시간 +- **Circuit Breaker per-model** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks +- **Exponential Backoff** — Progressive retry delays +- **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 +- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain +- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
-
🔧 7. "각 AI 도구를 구성하는 것은 지루하고 반복적입니다."
+🔧 7. "Configuring each AI tool is tedious and repetitive"
-개발자는 Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code 등을 사용합니다. 각 도구에는 서로 다른 구성(API 엔드포인트, 키, 모델)이 필요합니다. 공급자나 모델을 전환할 때 재구성하는 것은 시간 낭비입니다. +Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time. -**OmniRoute가 이를 해결하는 방법:** +**How OmniRoute solves it:** -- **CLI 도구 대시보드** — Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline을 원클릭으로 설정할 수 있는 전용 페이지 -- **GitHub Copilot Config Generator** — 대량 모델 선택을 통해 VS Code용 `chatLanguageModels.json`를 생성합니다. -- **온보딩 마법사** — 처음 사용자를 위한 4단계 설정 안내 -- **하나의 엔드포인트, 모든 모델** — `http://localhost:20128/v1`를 한 번 구성하면 36개 이상의 공급자에 액세스할 수 있습니다. +- **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 67+ providers
-
🔑 8. "여러 공급자의 OAuth 토큰 관리는 지옥입니다"
+🔑 8. "Managing OAuth tokens from multiple providers is hell"
-Claude Code, Codex, Gemini CLI, Copilot — 모두 만료되는 토큰과 함께 OAuth 2.0을 사용합니다. 개발자는 지속적으로 재인증을 수행하고 `client_secret is missing`, `redirect_uri_mismatch` 및 원격 서버의 오류를 처리해야 합니다. LAN/VPS의 OAuth는 특히 문제가 됩니다. +Claude Code, Codex, Gemini CLI, 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. -**OmniRoute가 이를 해결하는 방법:** +**How OmniRoute solves it:** -- **자동 토큰 새로 고침** — OAuth 토큰이 만료되기 전에 백그라운드에서 새로 고쳐집니다. -- **OAuth 2.0(PKCE) 내장** — Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow에 대한 자동 흐름 -- **다중 계정 OAuth** — JWT/ID 토큰 추출을 통해 공급자당 여러 계정 -- **OAuth LAN/원격 수정** — `redirect_uri`에 대한 개인 IP 감지 + 원격 서버에 대한 수동 URL 모드 -- **Nginx 뒤의 OAuth** — 역방향 프록시 호환성을 위해 `window.location.origin`를 사용합니다. -- **원격 OAuth 가이드** — VPS/Docker의 Google Cloud 자격 증명에 대한 단계별 가이드 +- **Auto Token Refresh** — OAuth tokens refresh in background before expiration +- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow +- **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. "얼마나 쓰고 있는지, 어디에 쓰는지 모르겠어요"
+📊 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. -**OmniRoute가 이를 해결하는 방법:** +**How OmniRoute solves it:** -- **비용 분석 대시보드** — 토큰별 비용 추적 및 공급자별 예산 관리 -- **계층당 예산 한도** — 자동 폴백을 트리거하는 계층당 지출 한도 -- **모델별 가격 구성** — 모델당 가격 구성 가능 -- **API 키당 사용 통계** — 키당 요청 수 및 마지막으로 사용된 타임스탬프 -- **분석 대시보드** — 통계 카드, 모델 사용 차트, 성공률 및 대기 시간이 포함된 공급자 테이블 +- **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. "AI 호출 오류 및 문제 진단이 안 돼요"
+🐛 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. -**OmniRoute가 이를 해결하는 방법:** +**How OmniRoute solves it:** -- **통합 로그 대시보드** — 탭 4개: 요청 로그, 프록시 로그, 감사 로그, 콘솔 -- **콘솔 로그 뷰어** — 색상으로 구분된 레벨, 자동 스크롤, 검색, 필터 기능을 갖춘 실시간 터미널 스타일 뷰어 -- **SQLite 프록시 로그** — 서버를 다시 시작해도 지속되는 영구 로그 -- **번역기 플레이그라운드** — 4가지 디버깅 모드: 플레이그라운드(형식 번역), 채팅 테스터(왕복), 테스트 벤치(일괄), 라이브 모니터(실시간) -- **원격 측정 요청** — p50/p95/p99 대기 시간 + X-요청-ID 추적 -- **회전을 통한 파일 기반 로깅** — 콘솔 인터셉터는 크기 기반 회전을 통해 모든 것을 JSON 로그에 캡처합니다. +- **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 Proxy Logs** — Persistent logs that survive server restarts +- **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 Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation +- **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. "게이트웨이 배포 및 유지 관리가 복잡합니다."
+🏗️ 11. "Deploying and maintaining the gateway is complex"
-다양한 환경(로컬, VPS, Docker, 클라우드)에서 AI 프록시를 설치, 구성 및 유지 관리하는 것은 노동 집약적입니다. 하드코딩된 경로, 디렉터리의 `EACCES`, 포트 충돌, 크로스 플랫폼 빌드와 같은 문제로 인해 마찰이 가중됩니다. +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. -**OmniRoute가 이를 해결하는 방법:** +**How OmniRoute solves it:** -- **npm 전역 설치** — `npm install -g omniroute && omniroute` — 완료 -- **Docker 다중 플랫폼** — AMD64 + ARM64 기본(Apple Silicon, AWS Graviton, Raspberry Pi) -- **Docker Compose 프로필** — `base`(CLI 도구 없음) 및 `cli`(Claude Code, Codex, OpenClaw 포함) -- **Electron 데스크탑 앱** — 시스템 트레이, 자동 시작, 오프라인 모드를 갖춘 Windows/macOS/Linux용 기본 앱 -- **분할 포트 모드** — 고급 시나리오(역방향 프록시, 컨테이너 네트워킹)를 위한 별도의 포트에 있는 API 및 대시보드 -- **클라우드 동기화** — Cloudflare Workers를 통해 장치 간 구성 동기화 -- **DB 백업** — 모든 설정의 자동 백업, 복원, 내보내기 및 가져오기 +- **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
-
🌍 12. "인터페이스는 영어로만 제공되며 우리 팀은 영어를 구사하지 않습니다."
+🌍 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. -**OmniRoute가 이를 해결하는 방법:** +**How OmniRoute solves it:** -- **대시보드 i18n — 30개 언어** — 한국어, 아랍어, 불가리아어, 덴마크어, 독일어, 스페인어, 핀란드어, 프랑스어, 히브리어, 힌디어, 헝가리어, 인도네시아어, 이탈리아어, 일본어, 말레이어, 네덜란드어, 노르웨이어, 폴란드어, 포르투갈어(PT/BR), 루마니아어, 러시아어, 슬로바키아어, 스웨덴어, 태국어, 우크라이나어, 베트남어, 중국어, 필리핀어, 영어를 포함한 500개 이상의 키 번역됨 -- **RTL 지원** — 아랍어 및 히브리어에 대해 오른쪽에서 왼쪽으로 지원 -- **다국어 README** — 30개의 완전한 문서 번역 -- **언어 선택기** — 실시간 전환을 위한 헤더의 지구본 아이콘 +- **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. "채팅 이상의 것이 필요합니다. 임베딩, 이미지, 오디오가 필요합니다."
+🔄 13. "I need more than chat — I need embeddings, images, audio"
-AI는 단순한 채팅 완성이 아닙니다. 개발자는 이미지를 생성하고, 오디오를 기록하고, RAG용 임베딩을 만들고, 문서 순위를 다시 지정하고, 콘텐츠를 조정해야 합니다. 각 API에는 서로 다른 엔드포인트와 형식이 있습니다. +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. -**OmniRoute가 이를 해결하는 방법:** +**How OmniRoute solves it:** -- **임베딩** — 6개 공급자와 9개 이상의 모델이 포함된 `/v1/embeddings` -- **이미지 생성** — 10개 공급자와 20개 이상의 모델(OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)을 갖춘 `/v1/images/generations` -- **텍스트-비디오** — `/v1/videos/generations` — ComfyUI(AnimateDiff, SVD) 및 SD WebUI -- **텍스트-음악** — `/v1/music/generations` — ComfyUI(안정적인 오디오 개방형, MusicGen) -- **오디오 녹음** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3 -- **텍스트 음성 변환** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, Inworld, Cartesia, PlayHT, + 기존 제공업체 -- **조정** — `/v1/moderations` — 콘텐츠 안전 확인 -- **재순위** — `/v1/rerank` — 문서 관련성 재지정 -- **응답 API** — Codex에 대한 전체 `/v1/responses` 지원 +- **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. "모델별 품질을 테스트하고 비교할 방법이 없어요"
+🧪 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. -**OmniRoute가 이를 해결하는 방법:** +**How OmniRoute solves it:** -- **LLM 평가** — 인사말, 수학, 지리, 코드 생성, JSON 준수, 번역, 마크다운, 안전 거부를 다루는 사전 로드된 10가지 사례를 사용한 골든 세트 테스트 -- **4가지 일치 전략** — `exact`, `contains`, `regex`, `custom`(JS 함수) -- **번역기 플레이그라운드 테스트 벤치** — 여러 입력 및 예상 출력을 사용한 일괄 테스트, 공급업체 간 비교 -- **채팅 테스터** — 시각적 응답 렌더링을 포함한 전체 왕복 -- **라이브 모니터** — 프록시를 통해 흐르는 모든 요청의 실시간 스트림 +- **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. "성능 저하 없이 확장해야 합니다"
+📈 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. -**OmniRoute가 이를 해결하는 방법:** +**How OmniRoute solves it:** -- **의미 체계 캐시** — 2계층 캐시(서명 + 의미 체계)로 비용과 대기 시간 감소 -- **멱등성 요청** — 동일한 요청에 대한 중복 제거 기간은 5초입니다. -- **속도 제한 감지** — 제공업체별 RPM, 최소 간격 및 최대 동시 추적 -- **편집 가능한 속도 제한** — 설정 → 지속성을 통한 복원력에서 구성 가능한 기본값 -- **API 키 검증 캐시** — 프로덕션 성능을 위한 3계층 캐시 -- **원격 측정 기능을 갖춘 상태 대시보드** — p50/p95/p99 대기 시간, 캐시 통계, 가동 시간 +- **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 +- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence +- **API Key Validation Cache** — 3-tier cache for production performance +- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
-
🤖 16. "모델 동작을 전체적으로 제어하고 싶습니다"
+🤖 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. -**OmniRoute가 이를 해결하는 방법:** +**How OmniRoute solves it:** -- **시스템 프롬프트 삽입** — 모든 요청에 전역 프롬프트 적용 -- **생각 예산 검증** — 요청별 토큰 할당 제어 추론(패스스루, 자동, 사용자 정의, 적응형) -- **6가지 라우팅 전략** — 요청 배포 방법을 결정하는 글로벌 전략 -- **와일드카드 라우터** — `provider/*` 패턴은 모든 공급자에게 동적으로 라우팅됩니다. -- **콤보 활성화/비활성화 토글** — 대시보드에서 직접 콤보를 토글합니다. -- **공급자 토글** — 한 번의 클릭으로 공급자에 대한 모든 연결을 활성화/비활성화합니다. -- **차단된 제공자** — `/v1/models` 목록에서 특정 제공자를 제외합니다. +- **System Prompt Injection** — Global prompt applied to all requests +- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive) +- **6 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 +- **Provider Toggle** — Enable/disable all connections for a provider with one click +- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
-
🧰 17. "일류 제품 기능으로 MCP 도구가 필요합니다"
+🧰 17. "I need MCP tools as first-class product capabilities"
-많은 AI 게이트웨이는 MCP를 숨겨진 구현 세부 사항으로만 노출합니다. 팀에는 가시적이고 관리 가능한 운영 레이어가 필요합니다. +Many AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer. -**OmniRoute가 이를 해결하는 방법:** +**How OmniRoute solves it:** -- 대시보드 탐색 및 엔드포인트 프로토콜 탭에 MCP가 나타납니다. -- 프로세스, 도구, 범위 및 감사가 포함된 전용 MCP 관리 페이지 -- `omniroute --mcp` 및 클라이언트 온보딩을 위한 빠른 시작 내장 +- 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. "동기화 + 스트림 작업 경로를 갖춘 A2A 오케스트레이션이 필요합니다"
+🧠 18. "I need A2A orchestration with sync + stream task paths"
-에이전트 워크플로에는 수명 주기 제어를 통해 직접 응답과 장기 실행 스트리밍 실행이 모두 필요합니다. +Agent workflows need both direct replies and long-running streamed execution with lifecycle control. -**OmniRoute가 이를 해결하는 방법:** +**How OmniRoute solves it:** -- `message/send` 및 `message/stream`가 포함된 A2A JSON-RPC 엔드포인트(`POST /a2a`) -- 터미널 상태 전파를 통한 SSE 스트리밍 -- `tasks/get` 및 `tasks/cancel`용 작업 수명 주기 API +- 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. "추측된 상태가 아닌 실제 MCP 프로세스 상태가 필요합니다"
+🛰️ 19. "I need real MCP process health, not guessed status"
-운영팀은 API에 접근할 수 있는지 여부뿐만 아니라 MCP가 실제로 활성화되어 있는지 알아야 합니다. +Operational teams need to know if MCP is actually alive, not just whether an API is reachable. -**OmniRoute가 이를 해결하는 방법:** +**How OmniRoute solves it:** -- PID, 타임스탬프, 전송, 도구 개수 및 범위 모드가 포함된 런타임 하트비트 파일 -- 하트비트 + 최근 활동을 결합한 MCP 상태 API -- 프로세스/가동 시간/하트비트 최신성을 위한 UI 상태 카드 +- 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. "감사 가능한 MCP 도구 실행이 필요합니다"
+📋 20. "I need auditable MCP tool execution"
-도구가 구성을 변경하거나 운영 작업을 트리거하는 경우 팀에는 법의학적 추적성이 필요합니다. +When tools mutate config or trigger ops actions, teams need forensic traceability. -**OmniRoute가 이를 해결하는 방법:** +**How OmniRoute solves it:** -- MCP 도구 호출에 대한 SQLite 지원 감사 로깅 -- 도구, 성공/실패, API 키, 페이지 매김 기준으로 필터링 -- 자동화를 위한 대시보드 감사 테이블 + 통계 엔드포인트 +- 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. "통합당 범위가 지정된 MCP 권한이 필요합니다."
+🔐 21. "I need scoped MCP permissions per integration"
-다양한 클라이언트에는 도구 범주에 대한 최소 권한 액세스 권한이 있어야 합니다. +Different clients should have least-privilege access to tool categories. -**OmniRoute가 이를 해결하는 방법:** +**How OmniRoute solves it:** -- 제어된 도구 액세스를 위한 9개의 세분화된 MCP 범위 -- MCP 관리 UI의 범위 적용 및 가시성 -- 운영 툴링을 위한 안전한 기본 자세 +- 9 granular MCP scopes for controlled tool access +- Scope enforcement and visibility in MCP management UI +- Safe default posture for operational tooling
-
⚙️ 22. "재배치 없이 작전 통제가 필요해요"
+⚙️ 22. "I need operational controls without redeploying"
-팀은 사고 또는 비용 이벤트 중에 빠른 런타임 변경이 필요합니다. +Teams need quick runtime changes during incidents or cost events. -**OmniRoute가 이를 해결하는 방법:** +**How OmniRoute solves it:** -- MCP 대시보드에서 직접 콤보 활성화 전환 -- 사전 정의된 정책 팩의 복원력 프로필 적용 -- 동일한 운영 패널에서 회로 차단기 상태 재설정 +- Switch combo activation directly from MCP dashboard +- Apply resilience profiles from pre-defined policy packs +- Reset circuit breaker state from the same operations panel
-
🔄 23. "실시간 A2A 작업 수명주기 가시성 및 취소가 필요합니다"
+🔄 23. "I need live A2A task lifecycle visibility and cancellation"
-수명주기 가시성이 없으면 작업 사고를 분류하기가 어려워집니다. +Without lifecycle visibility, task incidents become hard to triage. -**OmniRoute가 이를 해결하는 방법:** +**How OmniRoute solves it:** -- 페이지 매김을 통한 상태/기술별 작업 목록/필터링 -- 작업 메타데이터, 이벤트 및 아티팩트에 대한 드릴다운 -- 작업 취소 끝점 및 확인이 포함된 UI 작업 +- 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. "A2A 로드를 위한 활성 스트림 메트릭이 필요합니다"
+🌊 24. "I need active stream metrics for A2A load"
-스트리밍 워크플로에는 동시성 및 라이브 연결에 대한 운영 통찰력이 필요합니다. +Streaming workflows require operational insight into concurrency and live connections. -**OmniRoute가 이를 해결하는 방법:** +**How OmniRoute solves it:** -- A2A 상태에 통합된 활성 스트림 카운터 -- 마지막 작업 타임스탬프 및 상태별 개수 -- 실시간 운영 모니터링을 위한 A2A 대시보드 카드 +- Active stream counters integrated into A2A status +- Last task timestamp and per-state counts +- A2A dashboard cards for real-time ops monitoring
-
🪪 25. "클라이언트를 위한 표준 에이전트 검색이 필요합니다"
+🪪 25. "I need standard agent discovery for clients"
-외부 클라이언트 및 오케스트레이터에는 온보딩을 위해 컴퓨터에서 읽을 수 있는 메타데이터가 필요합니다. +External clients and orchestrators need machine-readable metadata for onboarding. -**OmniRoute가 이를 해결하는 방법:** +**How OmniRoute solves it:** -- `/.well-known/agent.json`에 노출된 에이전트 카드 -- 관리 UI에 표시되는 능력과 기술 -- A2A 상태 API에는 자동화를 위한 검색 메타데이터가 포함되어 있습니다. +- Agent Card exposed at `/.well-known/agent.json` +- Capabilities and skills shown in management UI +- A2A status API includes discovery metadata for automation
-
🧭 26. "제품 UX에서 프로토콜 검색 기능이 필요합니다"
+🧭 26. "I need protocol discoverability in the product UX"
-사용자가 프로토콜 표면을 발견할 수 없는 경우 채택 및 지원 품질이 저하됩니다. +If users cannot discover protocol surfaces, adoption and support quality drop. -**OmniRoute가 이를 해결하는 방법:** +**How OmniRoute solves it:** -- MCP 및 A2A용 사이드바 항목 -- 빠른 시작 및 상태가 포함된 엔드포인트 페이지 프로토콜 탭 -- 개요에서 전용 관리 대시보드로의 링크 +- 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. "실제 클라이언트와의 엔드투엔드 프로토콜 검증이 필요합니다"
+🧪 27. "I need end-to-end protocol validation with real clients"
-모의 테스트는 출시 전에 프로토콜 호환성을 검증하기에 충분하지 않습니다. +Mock tests are not enough to validate protocol compatibility before release. -**OmniRoute가 이를 해결하는 방법:** +**How OmniRoute solves it:** -- 앱을 부팅하고 실제 MCP SDK 클라이언트 전송을 사용하는 E2E 제품군 -- 흐름 검색, 전송, 스트리밍, 가져오기 및 취소에 대한 A2A 클라이언트 테스트 -- MCP 감사 및 A2A 작업 API에 대한 교차 확인 주장 +- 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. "모든 인터페이스에 걸쳐 통합된 관찰 가능성이 필요합니다"
+📡 28. "I need unified observability across all interfaces"
-프로토콜별로 관찰 가능성을 분할하면 사각지대가 발생하고 MTTR이 길어집니다. +Splitting observability by protocol creates blind spots and longer MTTR. -**OmniRoute가 이를 해결하는 방법:** +**How OmniRoute solves it:** -- 대시보드/로그/분석을 하나의 제품으로 통합 -- OpenAI, MCP 및 A2A 계층 전반에 걸쳐 상태 + 감사 + 원격 측정 요청 -- 상태 및 자동화를 위한 운영 API +- Unified dashboards/logs/analytics in one product +- Health + audit + request telemetry across OpenAI, MCP, and A2A layers +- Operational APIs for status and automation
-
💼 29. "프록시 + 도구 + 에이전트 오케스트레이션을 위해 하나의 런타임이 필요합니다."
+💼 29. "I need one runtime for proxy + tools + agent orchestration"
-여러 개별 서비스를 실행하면 운영 비용과 오류 모드가 증가합니다. +Running many separate services increases operational cost and failure modes. -**OmniRoute가 이를 해결하는 방법:** +**How OmniRoute solves it:** -- OpenAI 호환 프록시, MCP 서버, A2A 서버가 하나의 스택에 있음 -- 공유 인증, 복원력, 데이터 저장소 및 관찰 가능성 -- 모든 상호 작용 표면에 걸쳐 일관된 정책 모델 +- 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
-
-### 플레이북 예시(통합 사용 사례)
+### Example Playbooks (Integrated Use Cases)
-**플레이북 A: 유료 구독 극대화 + 저렴한 백업**
+**Playbook A: Maximize paid subscription + cheap backup**
```txt
Combo: "maximize-claude"
@@ -683,7 +694,7 @@ Monthly cost: $20 + small backup spend
Outcome: higher quality, near-zero interruption
```
-**플레이북 B: 비용이 전혀 들지 않는 코딩 스택**
+**Playbook B: Zero-cost coding stack**
```txt
Combo: "free-forever"
@@ -695,7 +706,7 @@ Monthly cost: $0
Outcome: stable free coding workflow
```
-**플레이북 C: 연중무휴 상시 가동 폴백 체인**
+**Playbook C: 24/7 always-on fallback chain**
```txt
Combo: "always-on"
@@ -708,65 +719,132 @@ Combo: "always-on"
Outcome: deep fallback depth for deadline-critical workloads
```
-**플레이북 D: MCP + A2A를 사용한 에이전트 작업**
+**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/mcp and /dashboard/a2a
-4) Control incidents with resilience profile + task cancellation
+3) Observe via /dashboard/endpoint (MCP and A2A tabs)
+4) Toggle services via inline status controls
```
---
-## ⚡ 빠른 시작
+## 🆓 Start Free — Zero Configuration Cost
-**1. 전역적으로 설치:**
+> 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 **iFlow** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |
+| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |
+| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |
+| 5 | `/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).
+
+## 빠른 시작
+
+### 1) Install and run
```bash
npm install -g omniroute
omniroute
```
-🎉 대시보드는 `http://localhost:20128`에서 열립니다.
+> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:
+>
+> ```bash
+> pnpm install -g omniroute
+> pnpm approve-builds -g # Select all packages → approve
+> omniroute
+> ```
-| 명령 | 설명 |
-| ----------------------- | ----------------------------- |
-| `omniroute` | 서버 시작(기본 포트 20128) |
-| `omniroute --port 3000` | 사용자 정의 포트 사용 |
-| `omniroute --no-open` | 브라우저를 자동으로 열지 않음 |
-| `omniroute --help` | 도움말 표시 |
+Dashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.
-**2. 무료 공급자 연결:**
+| 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 |
-대시보드 → 공급자 → **Claude Code** 또는 **Antigravity** 연결 → OAuth 로그인 → 완료!
+Optional split-port mode:
-**3. CLI 도구에서 사용:**
-
-```
-Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Settings:
- Endpoint: http://localhost:20128/v1
- API Key: [copy from dashboard]
- Model: if/kimi-k2-thinking
+```bash
+PORT=20128 DASHBOARD_PORT=20129 omniroute
+# API: http://localhost:20128/v1
+# Dashboard: http://localhost:20129
```
-**그렇습니다!** 무료 AI 모델로 코딩을 시작해 보세요.
+### 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
+
+```txt
+Base URL: http://localhost:20128/v1
+API Key: [copy from Endpoint page]
+Model: if/kimi-k2-thinking (or any provider/model prefix)
+```
+
+Works with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.
+
+### 4) Enable and validate protocols (v2.0)
+
+**MCP (for tool-driven operations):**
+
+```bash
+omniroute --mcp
+```
+
+Then connect your MCP client over `stdio` and test tools like:
+
+- `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 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
+PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev
```
---
-## 🐳 도커
+## 🐳 Docker
-OmniRoute는 [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute)에서 공개 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 \
@@ -777,7 +855,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**환경 파일 포함:**
+**With environment file:**
```bash
# Copy and edit .env first
@@ -792,7 +870,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Docker Compose 사용:**
+**Using Docker Compose:**
```bash
# Base profile (no CLI tools)
@@ -802,257 +880,552 @@ docker compose --profile base up -d
docker compose --profile cli up -d
```
-| 이미지 | 태그 | 사이즈 | 설명 |
-| ------------------------ | -------- | ------ | ---------------- |
-| `diegosouzapw/omniroute` | `latest` | ~250MB | 최신 안정 릴리스 |
-| `diegosouzapw/omniroute` | `1.0.3` | ~250MB | 현재 버전 |
+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.
+- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.
+- 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` | `1.0.3` | ~250MB | Current version |
---
----
+## 🖥️ Desktop App — Offline & Always-On
-## 🖥️
+> 🆕 **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.
-> 🆕 **새 기능!** OmniRoute가 Windows, macOS, Linux용 **네이티브 데스크톱 앱**으로 출시되었습니다.
+Run OmniRoute as a standalone desktop app — no terminal, no browser, no internet required for local models. The Electron-based app includes:
-- 🖥️ **네이티브 윈도우** — 시스템 트레이 통합 전용 창
-- 🔄 **자동 시작** — 시스템 로그인 시 OmniRoute 실행
-- 🔔 **네이티브 알림** — 할당량 소진 또는 공급자 문제 알림
-- ⚡ **원클릭 설치** — NSIS (Windows), DMG (macOS), AppImage (Linux)
-- 🌐 **오프라인 모드** — 내장 서버로 완전 오프라인 작동
+- 🖥️ **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
+
+### 빠른 시작
```bash
-npm run electron:dev # 개발 모드
-npm run electron:build # 현재 플랫폼
+# 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)
+npm run electron:build:mac # macOS (.dmg) — x64 & arm64
npm run electron:build:linux # Linux (.AppImage)
```
-📖 전체 문서: [`electron/README.md`](electron/README.md)
+### 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
-| 계층 | 공급자 | 비용 | 할당량 재설정 | 최고의 대상 |
-| ------------- | ------------------- | --------------------- | --------------- | ----------------- |
-| **💳 구독** | 클로드 코드 (Pro) | $20/월 | 5시간 + 매주 | 이미 구독 중 |
-| | 코덱스(플러스/프로) | $20-200/월 | 5시간 + 매주 | OpenAI 사용자 |
-| | 제미니 CLI | **무료** | 180K/월 + 1K/일 | 모든 사람! |
-| | GitHub 부조종사 | $10-19/월 | 월간 | GitHub 사용자 |
-| **🔑 API 키** | 엔비디아 NIM | **무료** (1000크레딧) | 일회성 | 무료 등급 테스트 |
-| | 딥시크 | 종량제 | 없음 | 최고의 가격/품질 |
-| | 그로크 | 무료 등급 + 유료 | 요금 제한 | 초고속 추론 |
-| | xAI(그록) | 종량제 | 없음 | 그록 모델 |
-| | 미스트랄 | 무료 등급 + 유료 | 요금 제한 | 유럽의 AI |
-| | 오픈라우터 | 종량제 | 없음 | 100개 이상의 모델 |
-| **💰 저렴한** | GLM-4.7 | $0.6/1M | 매일 오전 10시 | 예산 백업 |
-| | 미니맥스 M2.1 | $0.2/1M | 5시간 롤링 | 가장 저렴한 옵션 |
-| | 키미 K2 | $9/월 정액 | 1000만 토큰/월 | 예측 가능한 비용 |
-| **🆓 무료** | 아이플로우 | $0 | 무제한 | 8개 모델 무료 |
-| | 퀀 | $0 | 무제한 | 3개 모델 무료 |
-| | 키로 | $0 | 무제한 | 클로드 프리 |
+| 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 |
+| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |
+| | 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** | iFlow | **$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 |
-**💡 전문가 팁:** Gemini CLI(월 180K 무료) + iFlow(무제한 무료) 콤보 = 비용 $0로 시작하세요!
+> 🆕 **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
+iFlow (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
-| 기능 | 그것이 하는 일 |
-| ----------------------------- | ----------------------------------------------------------------------------- |
-| 🎯 **스마트 4계층 폴백** | 자동 경로: 구독 → API 키 → 저렴한 → 무료 |
-| 📊 **실시간 할당량 추적** | 라이브 토큰 수 + 공급자별 카운트다운 재설정 |
-| 🔄 **형식 번역** | OpenAI ⇔ Claude ⇔ Gemini ⇔ Cursor ⇔ Kiro 심리스 + 반응위생 |
-| 👥 **다중 계정 지원** | 지능적인 선택을 통해 공급자당 여러 계정 |
-| 🔄 **자동 토큰 새로고침** | 재시도 시 OAuth 토큰이 자동으로 새로 고쳐집니다. |
-| 🎨 **맞춤형 콤보** | 6가지 전략: 채우기 우선, 라운드 로빈, p2c, 무작위, 최소 사용, 비용 최적화 |
-| 🧩 **맞춤형 모델** | 모든 공급자에 모델 ID 추가 |
-| 🌐 **와일드카드 라우터** | `provider/*` 패턴을 모든 공급자에게 동적으로 라우팅 |
-| 🧠 **예산 고려** | 추론 모델을 위한 패스스루, 자동, 사용자 정의 및 적응형 모드 |
-| 🔀 **Model Aliases** | Auto-forward deprecated model IDs to current replacements (built-in + custom) |
-| ⚡ **Background Degradation** | Auto-route background tasks (titles, summaries) to cheaper models |
-| 💬 **시스템 프롬프트 삽입** | 모든 요청에 전역 시스템 프롬프트 적용 |
-| 📄 **응답 API** | Codex에 대한 전체 OpenAI 응답 API(`/v1/responses`) 지원 |
+> 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.
-### 🎵 다중 모드 API
+### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)
-| 기능 | 그것이 하는 일 |
-| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 🖼️ **이미지 생성** | `/v1/images/generations` — 4개 공급자, 9개 이상의 모델 |
-| 📐 **임베딩** | `/v1/embeddings` — 6개 공급자, 9개 이상의 모델 |
-| 🎤 **오디오 전사** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |
-| 🔊 **텍스트 음성 변환** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) |
-| 🛡️ **조정** | `/v1/moderations` — 콘텐츠 안전 확인 |
-| 🔀 **재순위** | `/v1/rerank` — 문서 관련성 재순위 |
+| 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 |
-### 🛡️ 복원력 및 보안
+### 🟢 IFLOW MODELS (Free OAuth — No Credit Card)
-| 기능 | 그것이 하는 일 |
-| ------------------------------- | ---------------------------------------------------------------------------- |
-| 🔌 **회로 차단기** | 구성 가능한 임계값을 사용하여 공급자별 자동 열기/닫기 |
-| 🛡️ **천둥 방지 무리** | API 키 공급자에 대한 뮤텍스 + 세마포 속도 제한 |
-| 🧠 **의미론적 캐시** | 2계층 캐시(서명 + 의미 체계)로 비용 및 대기 시간 감소 |
-| ⚡ **멱등성 요청** | 중복 요청에 대한 5초 중복 제거 기간 |
-| 🔒 **TLS 지문 스푸핑** | wreq-js를 통해 TLS 기반 봇 감지 우회 |
-| 🌐 **IP 필터링** | API 액세스 제어를 위한 허용 목록/차단 목록 |
-| 📊 **편집 가능한 속도 제한** | 시스템 수준에서 구성 가능한 RPM, 최소 간격 및 최대 동시 |
-| 💾 **Rate Limit Persistence** | Learned limits survive restarts via SQLite with 60s debounce + 24h staleness |
-| 🔄 **Token Refresh Resilience** | Per-provider circuit breaker (5 fails→30min) + 30s timeout per attempt |
-| 🛡 **API 엔드포인트 보호** | `/models` 엔드포인트에 대한 인증 게이팅 + 공급자 차단 |
-| 🔒 **프록시 가시성** | 색상으로 구분된 배지: 🟢 글로벌, 🟡 공급자, 🔵 IP 디스플레이를 통한 연결별 |
-| 🌐 **3단계 프록시 구성** | 글로벌, 공급자별 또는 연결별 수준에서 프록시 구성 |
+| 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 |
-### 📊 관찰 가능성 및 분석
+### 🟡 QWEN MODELS (Device Code Auth)
-| 기능 | 그것이 하는 일 |
-| -------------------------------- | -------------------------------------------------------------------- |
-| 📝 **로깅 요청** | 전체 요청/응답 로그가 포함된 디버그 모드 |
-| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |
-| 💾 **SQLite 프록시 로그** | 영구 프록시 로그는 서버를 다시 시작해도 유지됩니다. |
-| 📊 **분석 대시보드** | Recharts 기반: 통계 카드, 모델 사용 차트, 공급자 테이블 |
-| 📈 **진행 상황 추적** | 스트리밍을 위한 옵트인 SSE 진행 이벤트 |
-| 🧪 **LLM 평가** | 4가지 매치 전략을 사용한 골든 세트 테스트 |
-| 🔍 **원격 측정 요청** | p50/p95/p99 대기 시간 집계 + X-요청-ID 추적 |
-| 📋 **로그 대시보드** | 통합된 4개 탭 페이지: 요청 로그, 프록시 로그, 감사 로그, 콘솔 |
-| 🖥️ **콘솔 로그 뷰어** | 레벨 필터, 검색, 자동 스크롤 기능을 갖춘 실시간 터미널 스타일 뷰어 |
-| 📑 **파일 기반 로깅** | 콘솔 인터셉터는 회전을 통해 모든 출력을 JSON 로그 파일로 캡처합니다. |
-| 🏥 **건강 대시보드** | 시스템 가동 시간, 회로 차단기 상태, 잠금, 캐시 통계 |
-| 💰 **비용 추적** | 예산 관리 + 모델별 가격 구성 |
+| 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) |
-### ☁️ 배포 및 동기화
+### 🟣 GEMINI CLI (Google OAuth)
-| 기능 | 그것이 하는 일 |
-| ---------------------------------- | ----------------------------------------------------------------- |
-| 💾 **클라우드 동기화** | Cloudflare Workers를 통해 장치 간 구성 동기화 |
-| 🌐 **어디서나 배포** | 로컬호스트, VPS, Docker, Cloudflare 작업자 |
-| 🔑 **API 키 관리** | 공급자별 API 키 생성, 회전 및 범위 지정 |
-| 🧙 **온보딩 마법사** | 처음 사용자를 위한 4단계 안내 설정 |
-| 🔧 **CLI 도구 대시보드** | 원클릭 구성 Claude, Codex, Cline, OpenClaw, Kilo, Antigravity |
-| 🔄 **DB 백업** | 모든 설정에 대한 자동 백업, 복원, 내보내기 및 가져오기 |
-| 🌐 **국제화** | next-intl이 포함된 전체 i18n — 영어 + 포르투갈어(브라질) 지원 |
-| 🌍 **언어 선택기** | 실시간 언어 전환을 위한 헤더의 지구본 아이콘(🇺🇸/🇧🇷) |
-| 🧹 **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 |
-| 📂 **사용자 정의 데이터 디렉터리** | `DATA_DIR` env var는 기본 `~/.omniroute` 저장 경로를 재정의합니다 |
+| Model | Prefix | Limit | Rate Limit |
+| ------------------------ | ------ | --------------------------- | ------------- |
+| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |
+| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |
+
+### ⚫ 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
+> iFlow (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 v2.0 is built as an operational platform, not just a relay proxy.
+
+### 🆕 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 Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |
+| 🤖 **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 (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) |
+| 🤝 **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** | 9 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 combo, apply resilience profiles, reset breakers from one control surface |
+
+### 🧠 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** | 6 balancing strategies + fallback chain control |
+| 🌐 **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) |
+| 💬 **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 |
+| ----------------------------------- | -------------------------------------------------------------------------------------- |
+| 🔌 **Circuit Breakers** | Per-model trip/recover with threshold controls |
+| 🎯 **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 |
+| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |
+| 🔑 **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 |
+
+### 📊 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 |
+| 📋 **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 |
+
+### ☁️ Deployment & Platform
+
+| Feature | What It Does |
+| ----------------------------- | --------------------------------------------------------- |
+| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |
+| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |
+| 💾 **Cloud Sync** | Configuration sync via cloud worker |
+| 🔄 **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 |
+
+### Feature Deep Dive
+
+#### Smart fallback with practical cost control
+
+```txt
+Combo: "my-coding-stack"
+ 1. cc/claude-opus-4-6
+ 2. nvidia/llama-3.3-70b
+ 3. glm/glm-4.7
+ 4. if/kimi-k2-thinking
+```
+
+When quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.
+
+#### 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)
+
+#### 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)
🚀 30. "글루 코드 확장 없이 에이전트 워크플로를 제공해야 합니다."
+🚀 30. "I need to ship agentic workflows without glue-code sprawl"
-여러 임시 서비스와 스크립트를 결합할 때 팀의 속도가 느려집니다. +Teams lose velocity when stitching multiple ad-hoc services and scripts. -**OmniRoute가 이를 해결하는 방법:** +**How OmniRoute solves it:** -- 클라이언트와 에이전트를 위한 통합 엔드포인트 전략 -- 내장된 프로토콜 관리 UI 및 연기 검증 경로 -- 프로덕션 준비 기반(보안, 로깅, 탄력성, 백업) +- Unified endpoint strategy for clients and agents +- Built-in protocol management UIs and smoke validation paths +- Production-ready foundations (security, logging, resilience, backup)
-` 블록 → `reasoning_content`
-- **구조화된 출력** — `json_schema` → Gemini의 `responseMimeType`/`responseSchema`
-
-### 👥 다중 계정 지원
-
-- 공급자당 여러 계정 추가
-- 자동 라운드 로빈 또는 우선순위 기반 라우팅
-- 한 계정이 할당량에 도달하면 다음 계정으로 대체
-
-### 🔄 자동 토큰 새로고침
-
-- OAuth 토큰은 만료되기 전에 자동으로 새로 고쳐집니다.
-- 수동 재인증이 필요하지 않습니다.
-- 모든 제공업체에 걸친 원활한 경험
-
-### 🎨 맞춤 콤보
-
-- 무제한 모델 조합 생성
-- 6가지 전략: 채우기 우선, 라운드 로빈, 두 가지 선택의 힘, 무작위, 최소 사용, 비용 최적화
-- Cloud Sync를 통해 여러 기기에서 콤보를 공유하세요
-
-### 🏥 건강 대시보드
-
-- 시스템 상태(가동 시간, 버전, 메모리 사용량)
-- 공급자별 회로 차단기 상태(Closed/Open/Half-Open)
-- 속도 제한 상태 및 활성 잠금
-- 서명 캐시 통계
-- 대기 시간 원격 측정(p50/p95/p99) + 프롬프트 캐시
-- 한 번의 클릭으로 건강 상태 재설정
-
-### 🔧 번역기 놀이터
-
-OmniRoute에는 API 번역 디버깅, 테스트 및 모니터링을 위한 **4가지 모드**를 갖춘 강력한 내장 번역기 플레이그라운드가 포함되어 있습니다.
-
-| 모드 | 설명 |
-| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **💻 놀이터** | 직접 형식 변환 — API 요청 본문을 붙여넣고 OmniRoute가 공급자 형식(OpenAI ← Claude ← Gemini ← Responses API) 간에 이를 어떻게 변환하는지 즉시 확인하세요. 예제 템플릿과 형식 자동 감지가 포함되어 있습니다. |
-| **💬 채팅 테스터** | OmniRoute를 통해 실제 채팅 요청을 보내고 전체 왕복(입력, 번역된 요청, 공급자 응답, 번역된 응답)을 확인하세요. 콤보 라우팅을 검증하는 데 매우 중요합니다. |
-| **🧪 테스트 벤치** | 배치 테스트 모드 — 서로 다른 입력과 예상 출력으로 여러 테스트 케이스를 정의하고, 이를 모두 한 번에 실행하고, 공급자와 모델 간에 결과를 비교합니다. |
-| **📱 라이브 모니터** | 실시간 요청 모니터링 — OmniRoute를 통해 들어오는 요청을 감시하고, 실시간으로 발생하는 형식 변환을 확인하고, 문제를 즉시 식별합니다. |
-
-**액세스:** 대시보드 → 번역기(사이드바)
-
-### 💾 클라우드 동기화
-
-- 여러 장치에서 공급자, 콤보 및 설정을 동기화합니다.
-- 자동 백그라운드 동기화
-- 안전한 암호화 저장
+- `GET /api/mcp/status`
+- `GET /api/mcp/tools`
+- `GET /api/mcp/audit`
+- `GET /api/mcp/audit/stats`
-## 🧪 평가(Evals)
+📖 기능 세부정보
+🧩 MCP Setup (Model Context Protocol)
-### 🎯 스마트 4계층 폴백 +Start MCP transport in stdio mode: -자동 대체 기능을 사용하여 콤보 만들기: - -``` -Combo: "my-coding-stack" - 1. cc/claude-opus-4-6 (your subscription) - 2. nvidia/llama-3.3-70b (free NVIDIA API) - 3. glm/glm-4.7 (cheap backup, $0.6/1M) - 4. if/kimi-k2-thinking (free fallback) - -→ Auto switches when quota runs out or errors occur +```bash +omniroute --mcp ``` -### 📊 실시간 할당량 추적 +Recommended validation flow: -- 제공자별 토큰 소비 -- 카운트다운 재설정(5시간, 매일, 매주) -- 유료 계층에 대한 비용 추정 -- 월별 지출 보고서 +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: -형식 간 원활한 번역: - -- **OpenAI** ← **Claude** ← **Gemini** ← **OpenAI 응답** -- CLI 도구가 OpenAI 형식 전송 → OmniRoute 변환 → 공급자가 기본 형식 수신 -- 맞춤형 OpenAI 엔드포인트를 지원하는 모든 도구와 함께 작동 -- **응답 삭제** — 엄격한 OpenAI SDK 호환성을 위해 비표준 필드를 제거합니다. -- **역할 정규화** — OpenAI가 아닌 경우 `developer` → `system`; `system` → GLM/ERNIE 모델의 경우 `user` -- **사고 태그 추출** — 사고 모델의 경우 `
+
🤝 A2A Setup (Agent2Agent)
-OmniRoute에는 골든 세트에 대해 LLM 응답 품질을 테스트하기 위한 내장 평가 프레임워크가 포함되어 있습니다. 대시보드의 **분석 → 평가**를 통해 액세스하세요. +Discover the agent: -### 내장 골든 세트 +```bash +curl http://localhost:20128/.well-known/agent.json +``` -사전 로드된 "OmniRoute Golden Set"에는 다음을 다루는 10개의 테스트 사례가 포함되어 있습니다. +Send a task: -- 인사말, 수학, 지리, 코드 생성 -- JSON 형식 준수, 번역, 마크다운 -- 안전 거부(유해 콘텐츠), 카운팅, 부울 논리 +```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."}]}}' +``` -### 평가 전략 +Manage lifecycle: -| 전략 | 설명 | 예 | -| ---------- | -------------------------------------------------------------- | -------------------------------- | -| `exact` | 출력은 정확히 일치해야 합니다 | `"4"` | -| `contains` | 출력에는 하위 문자열(대소문자 구분 안 함)이 포함되어야 합니다. | `"Paris"` | -| `regex` | 출력은 정규식 패턴과 일치해야 합니다 | `"1.*2.*3"` | -| `custom` | 사용자 정의 JS 함수가 true/false를 반환합니다. | `(output) => output.length > 10` | +- `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
-### 클로드 코드(Pro/Max) +Validate both protocols with real clients: + +```bash +npm run test:protocols:e2e +``` + +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) ```bash Dashboard → Providers → Connect Claude Code @@ -1065,9 +1438,9 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**프로 팁:** 복잡한 작업에는 Opus를 사용하고, 속도를 높이려면 Sonnet을 사용하세요. OmniRoute는 모델당 할당량을 추적합니다! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! -### OpenAI 코덱스(Plus/Pro) +### OpenAI Codex (Plus/Pro) ```bash Dashboard → Providers → Connect Codex @@ -1079,7 +1452,24 @@ Models: cx/gpt-5.1-codex-max ``` -### Gemini CLI(월 180,000 무료!) +#### 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). + +### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -1091,9 +1481,9 @@ Models: gc/gemini-2.5-pro ``` -**최고의 가치:** 엄청난 무료 등급! 유료 등급 이전에 사용하세요. +**Best Value:** Huge free tier! Use this before paid tiers. -### GitHub 코파일럿 +### GitHub Copilot ```bash Dashboard → Providers → Connect GitHub @@ -1109,88 +1499,88 @@ Models:
-
🔑 API 키 제공자
+🔑 API Key Providers
-### NVIDIA NIM(무료 1000 크레딧!) +### NVIDIA NIM (FREE developer access — 70+ models) -1. 가입: [build.nvidia.com](https://build.nvidia.com) -2. 무료 API 키 받기(1000 추론 크레딧 포함) -3. 대시보드 → 공급자 추가 → NVIDIA NIM: - - API 키: `nvapi-your-key` +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` -**모델:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct` 외 50개 이상 +**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more -**프로 팁:** OpenAI 호환 API — OmniRoute의 형식 변환과 원활하게 작동합니다! +**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation! -### 딥시크 +### DeepSeek -1. 가입: [platform.deepseek.com](https://platform.deepseek.com) -2. API 키 받기 -3. 대시보드 → 공급자 추가 → DeepSeek +1. Sign up: [platform.deepseek.com](https://platform.deepseek.com) +2. Get API key +3. Dashboard → Add Provider → DeepSeek -**모델:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` +**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` -### Groq(무료 등급 사용 가능!) +### Groq (Free Tier Available!) -1. 가입: [console.groq.com](https://console.groq.com) -2. API 키 받기(무료 등급 포함) -3. 대시보드 → 공급자 추가 → Groq +1. Sign up: [console.groq.com](https://console.groq.com) +2. Get API key (free tier included) +3. Dashboard → Add Provider → Groq -**모델:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` +**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` -**프로 팁:** 초고속 추론 — 실시간 코딩에 가장 적합합니다! +**Pro Tip:** Ultra-fast inference — best for real-time coding! -### OpenRouter(100개 이상의 모델) +### OpenRouter (100+ Models) -1. 가입: [openrouter.ai](https://openrouter.ai) -2. API 키 받기 -3. 대시보드 → 공급자 추가 → OpenRouter +1. Sign up: [openrouter.ai](https://openrouter.ai) +2. Get API key +3. Dashboard → Add Provider → OpenRouter -**모델:** 단일 API 키를 통해 모든 주요 제공업체의 100개 이상의 모델에 액세스할 수 있습니다. +**Models:** Access 100+ models from all major providers through a single API key.
-
💰 저렴한 공급자(백업)
+💰 Cheap Providers (Backup)
-### GLM-4.7 (일일 재설정, $0.6/1M) +### GLM-4.7 (Daily reset, $0.6/1M) -1. 가입: [Zhipu AI](https://open.bigmodel.cn/) -2. Coding Plan에서 API Key 받기 -3. 대시보드 → API 키 추가: - - 제공자: `glm` - - API 키: `your-key` +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` -**사용:** `glm/glm-4.7` +**Use:** `glm/glm-4.7` -**프로 팁:** 코딩 계획은 1/7 비용으로 3배 할당량을 제공합니다! 매일 오전 10시에 초기화됩니다. +**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -### MiniMax M2.1(5시간 재설정, $0.20/1M) +### MiniMax M2.1 (5h reset, $0.20/1M) -1. 가입: [MiniMax](https://www.minimax.io/) -2. API 키 받기 -3. 대시보드 → API Key 추가 +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key +3. Dashboard → Add API Key -**사용:** `minimax/MiniMax-M2.1` +**Use:** `minimax/MiniMax-M2.1` -**프로 팁:** 긴 컨텍스트(100만 토큰)를 위한 가장 저렴한 옵션입니다! +**Pro Tip:** Cheapest option for long context (1M tokens)! -### Kimi K2($9/월 정액) +### Kimi K2 ($9/month flat) -1. 구독: [Moonshot AI](https://platform.moonshot.ai/) -2. API 키 받기 -3. 대시보드 → API Key 추가 +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key +3. Dashboard → Add API Key -**사용:** `kimi/kimi-latest` +**Use:** `kimi/kimi-latest` -**프로 팁:** 1,000만 토큰에 대해 고정 $9/월 = $0.90/1M 유효 비용! +**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
-
🆓 무료 제공업체(긴급 백업)
+🆓 FREE Providers (Emergency Backup)
-### iFlow(8개 무료 모델) +### iFlow (5 FREE models via OAuth) ```bash Dashboard → Connect iFlow @@ -1205,7 +1595,7 @@ Models: if/deepseek-r1 ``` -### Qwen(3개 무료 모델) +### Qwen (4 FREE models via Device Code) ```bash Dashboard → Connect Qwen @@ -1217,7 +1607,7 @@ Models: qw/qwen3-coder-flash ``` -### 키로(클로드 프리) +### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro @@ -1232,9 +1622,9 @@ Models:
-
🎨 콤보 만들기
+🎨 Create Combos
-### 예시 1: 구독 최대화 → 저렴한 백업 +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -1248,7 +1638,7 @@ Models: Use in CLI: premium-coding ``` -### 예시 2: 무료 전용(비용 없음) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -1263,9 +1653,9 @@ Cost: $0 forever!
-
---
-## 🐛 문제 해결
+## 문제 해결
🔧 CLI 통합
+🔧 CLI Integration
-### 커서 IDE +### Cursor IDE ``` Settings → Models → Advanced: @@ -1274,11 +1664,11 @@ Settings → Models → Advanced: Model: cc/claude-opus-4-6 ``` -### 클로드 코드 +### Claude Code -원클릭 구성을 위해 대시보드의 **CLI 도구** 페이지를 사용하거나 `~/.claude/settings.json`을 수동으로 편집하세요. +Use the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually. -### 코덱스 CLI +### Codex CLI ```bash export OPENAI_BASE_URL="http://localhost:20128" @@ -1287,15 +1677,15 @@ export OPENAI_API_KEY="your-omniroute-api-key" codex "your prompt" ``` -### 오픈클로 +### OpenClaw -**옵션 1 - 대시보드(권장):** +**Option 1 — Dashboard (recommended):** ``` Dashboard → CLI Tools → OpenClaw → Select Model → Apply ``` -**옵션 2 — 수동:** `~/.openclaw/openclaw.json` 편집: +**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`: ```json { @@ -1311,9 +1701,9 @@ Dashboard → CLI Tools → OpenClaw → Select Model → Apply } ``` -> **참고:** OpenClaw는 로컬 OmniRoute에서만 작동합니다. IPv6 확인 문제를 방지하려면 `localhost` 대신 `127.0.0.1`을 사용하세요. +> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues. -### 클라인 / 계속 / RooCode +### Cline / Continue / RooCode ``` Settings → API Configuration: @@ -1323,110 +1713,245 @@ Settings → API Configuration: 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. +
-
-- **런타임**: Node.js 18–22 LTS(⚠️ Node.js 24+는 **지원되지 않습니다** — `better-sqlite3` 네이티브 바이너리는 호환되지 않습니다)
-- **언어**: TypeScript 5.9 — `src/` 및 `open-sse/`에서 **100% TypeScript**(v1.0.6)
-- **프레임워크**: Next.js 16 + React 19 + Tailwind CSS 4
-- **데이터베이스**: LowDB(JSON) + SQLite(도메인 상태 + 프록시 로그)
-- **스트리밍**: 서버에서 보낸 이벤트(SSE)
-- **인증**: OAuth 2.0(PKCE) + JWT + API 키
-- **테스트**: Node.js 테스트 실행기(368개 이상의 단위 테스트)
-- **CI/CD**: GitHub Actions(자동 npm 게시 + 출시 시 Docker Hub)
-- **웹사이트**: [omniroute.online](https://omniroute.online)
-- **패키지**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
-- **도커**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
-- **복원력**: 회로 차단기, 지수 백오프, 천둥 방지 무리, TLS 스푸핑
-
----
-
-## 📖 문서
-
-| 문서 | 설명 |
-| -------------------------------------------- | ------------------------------------------ |
-| [User Guide](docs/USER_GUIDE.md) | 공급자, 콤보, CLI 통합, 배포 |
-| [API Reference](docs/API_REFERENCE.md) | 예제가 포함된 모든 엔드포인트 |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | 일반적인 문제 및 해결 방법 |
-| [Architecture](docs/ARCHITECTURE.md) | 시스템 아키텍처 및 내부 |
-| [Contributing](CONTRIBUTING.md) | 개발 설정 및 지침 |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 사양 |
-| [Security Policy](SECURITY.md) | 취약점 보고 및 보안 관행 |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | 전체 가이드: VM + nginx + Cloudflare 설정 |
-| [Features Gallery](docs/FEATURES.md) | 스크린샷을 포함한 시각적 대시보드 둘러보기 |
-
-### 📸 대시보드 미리보기
+## 🛠️ Tech Stack
문제 해결 가이드를 확장하려면 클릭하세요
+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** -- 구독 할당량 초과 → GLM/MiniMax로 대체 -- 콤보 추가: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Subscription quota out → Fallback to GLM/MiniMax +- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -**OAuth 토큰이 만료되었습니다** +**OAuth token expired** -- OmniRoute에 의해 자동 새로고침 -- 문제가 지속되는 경우: Dashboard → Provider → Reconnect +- Auto-refreshed by OmniRoute +- If issues persist: Dashboard → Provider → Reconnect -**높은 비용** +**High costs** -- 대시보드 → 비용에서 사용 통계를 확인하세요. -- 기본 모델을 GLM/MiniMax로 전환 -- 중요하지 않은 작업에는 무료 계층(Gemini CLI, iFlow)을 사용합니다. +- Check usage stats in Dashboard → Costs +- Switch primary model to GLM/MiniMax +- Use free tier (Gemini CLI, iFlow) for non-critical tasks -**대시보드가 잘못된 포트에서 열립니다** +**Dashboard/API ports are wrong** -- `PORT=20128` 및 `NEXT_PUBLIC_BASE_URL=http://localhost:20128` 설정 +- `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** -- `BASE_URL`이 실행 중인 인스턴스를 가리키는지 확인합니다. -- `CLOUD_URL`이 예상 클라우드 엔드포인트를 가리키는지 확인하세요. -- `NEXT_PUBLIC_*` 값을 서버측 값과 일치하도록 유지합니다. +- 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** -- `.env`에서 `INITIAL_PASSWORD`을 확인하세요. -- 설정되지 않은 경우 대체 비밀번호는 `123456`입니다. +- Check `INITIAL_PASSWORD` in `.env` +- If unset, fallback password is `123456` -**요청 로그 없음** +**No request logs** -- `.env`에 `ENABLE_REQUEST_LOGS=true`을 설정합니다. +- Set `ENABLE_REQUEST_LOGS=true` in `.env` -**OpenAI 호환 공급자에 대한 연결 테스트에서 "잘못됨"이 표시됩니다** +**Connection test shows "Invalid" for OpenAI-compatible providers** -- 많은 공급자가 `/models` 엔드포인트를 노출하지 않습니다. -- OmniRoute v1.0.6+에는 채팅 완료를 통한 대체 검증이 포함되어 있습니다. -- 기본 URL에 `/v1` 접미사가 포함되어 있는지 확인하세요. +- 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 +### 🔐 OAuth on a Remote Server + -> **⚠️ VPS/Docker/remotor의 OmniRoute를 사용하는 경우 중요** +> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server** -### OAuth +#### Why does Antigravity / Gemini CLI OAuth fail on remote servers? -Os는 **반중력** 및 **Gemini CLI**를 인증하기 위해 **Google OAuth 2.0**을 입증했습니다. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pre-cadastradas no Google Cloud Console do aplicativo. +The **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console. -OAuth는 OmniRoute에 대한 신용 정보를 포함하지 않으므로 **`localhost`**에 대한 액세스 권한을 갖습니다. Quando você acessa o OmniRoute em um servidor remoto (예: `https://omniroute.meuservidor.com`), o Google rejeita autenticação com: +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 ``` -### 해결책: 개인 정보 보호 OAuth 구성 +#### 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 + +# For Gemini CLI: +GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com +GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +``` + +**6. Restart OmniRoute** + +```bash +# npm: +npm run dev + +# Docker: +docker restart omniroute +``` + +**7. Try connecting again** + +Dashboard → Providers → Antigravity (or Gemini CLI) → OAuth + +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. + +--- + +
+
---
-## 🛠️
+🇧🇷 Versão em Português
+ +#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos? + +Os provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo. + +As credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticação com: + +``` +Error 400: redirect_uri_mismatch +``` + +#### Solução: Configure suas próprias credenciais OAuth Você precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor. -#### 파쏘 아 파소 +#### Passo a passo -**1. Google Cloud Console에 액세스** +**1. Acesse o Google Cloud Console** -아브라: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) +Abra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) -**2. Crie um novo OAuth 2.0 클라이언트 ID** +**2. Crie um novo OAuth 2.0 Client ID** -- em 클릭 **"+ 자격 증명 만들기"** → **"OAuth 클라이언트 ID"** -- 적용 분야: **"웹 애플리케이션"** -- 이름: escolha qualquer nome (예: `OmniRoute Remote`) +- Clique em **"+ Create Credentials"** → **"OAuth client ID"** +- Tipo de aplicativo: **"Web application"** +- Nome: escolha qualquer nome (ex: `OmniRoute Remote`) -**3. 승인된 리디렉션 URI로서의 Adicione** +**3. Adicione as Authorized Redirect URIs** -아니요 **"승인된 리디렉션 URI"**, 추가: +No campo **"Authorized redirect URIs"**, adicione: ``` https://seu-servidor.com/callback ``` -> `seu-servidor.com` pelo domínio 또는 IP do seu servidor로 대체합니다(필요한 포트 포함, 예: `http://45.33.32.156:20128/callback`). +> Substitua `seu-servidor.com` pelo domínio ou IP do seu servidor (inclua a porta se necessário, ex: `http://45.33.32.156:20128/callback`). -**4. 사본을 자격 증명으로 저장** +**4. Salve e copie as credenciais** -Após criar, o Google morerá o **클라이언트 ID** e o **클라이언트 비밀번호**. +Após criar, o Google mostrará o **Client ID** e o **Client Secret**. -**5. 다양한 주변 환경으로 구성** +**5. Configure as variáveis de ambiente** -`.env`(Docker의 주변 환경에 따라 다름)이 없습니다. +No seu `.env` (ou nas variáveis de ambiente do Docker): ```bash # Para Antigravity: @@ -1439,7 +1964,7 @@ GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret ``` -**6. Reinicie 또는 OmniRoute** +**6. Reinicie o OmniRoute** ```bash # Se usando npm: @@ -1451,151 +1976,145 @@ docker restart omniroute **7. Tente conectar novamente** -대시보드 → 공급자 → Antigravity(또는 Gemini CLI) → OAuth +Dashboard → Providers → Antigravity (ou Gemini CLI) → OAuth -Agora는 `https://seu-servidor.com/callback` 및 자동 기능에 대한 Google 리디렉션을 수정합니다. +Agora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará. --- -### 임시 해결 방법(sem configurar credenciais próprias) +#### Workaround temporário (sem configurar credenciais próprias) Se não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**: -1. OmniRoute는 Google 자동 생성 URL을 확인합니다. -2. Após você autorizar, o Google tentará redirectionar para `localhost` (que falha no servidor remoto) -3. **URL 복사 완료** da barra de endereço do seu browser (mesmo que a página não carregue) +1. O OmniRoute abrirá a URL de autorização do Google +2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto) +3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue) 4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute -5. Clique em **"연결"** +5. Clique em **"Connect"** -> 이 해결 방법은 URL을 통해 자동으로 코드를 확인하거나 독립적으로 리디렉션할 수 있도록 하는 것입니다. +> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.
-
---
-## 🗺️
+## 문서
-OmniRoute에는 여러 개발 단계에 걸쳐 **210개 이상의 기능이 계획되어 있습니다**. 주요 영역은 다음과 같습니다.
-
-| 카테고리 | 계획된 기능 | 하이라이트 |
-| ---------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------ |
-| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |
-| 🧠 **라우팅 및 인텔리전스** | 25세 이상 | 최저 대기 시간 라우팅, 태그 기반 라우팅, 실행 전 할당량, P2C 계정 선택 |
-| 🔒 **보안 및 규정 준수** | 20세 이상 | SSRF 강화, 자격 증명 클로킹, 엔드포인트당 속도 제한, 관리 키 범위 지정 |
-| 📊 **관측성** | 15세 이상 | OpenTelemetry 통합, 실시간 할당량 모니터링, 모델별 비용 추적 |
-| 🔄 **공급자 통합** | 20세 이상 | 동적 모델 레지스트리, 공급자 쿨다운, 다중 계정 Codex, Copilot 할당량 구문 분석 |
-| ⚡ **성능** | 15세 이상 | 듀얼 캐시 레이어, 프롬프트 캐시, 응답 캐시, 스트리밍 Keepalive, 배치 API |
-| 🌐 **생태계** | 10세 이상 | WebSocket API, 구성 핫 리로드, 분산 구성 저장소, 상용 모드 |
-
-### 🔜 출시 예정
-
-- 🔗 **OpenCode 통합** — OpenCode AI 코딩 IDE에 대한 기본 공급자 지원
-- 🔗 **TRAE 통합** — TRAE AI 개발 프레임워크를 완벽하게 지원
-- 📦 **Batch API** — 대량 요청에 대한 비동기식 일괄 처리
-- 🎯 **태그 기반 라우팅** — 사용자 정의 태그 및 메타데이터를 기반으로 요청 라우팅
-- 💰 **최저 비용 전략** — 가장 저렴한 제공업체를 자동으로 선택합니다.
-
-> 📝 [link](docs/new-features/)에서 사용 가능한 전체 기능 사양(217개 세부 사양)
+| Document | Description |
+| ---------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 16 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/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
+| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
-## 👥 기여자
+## 🗺️ Roadmap
+
+OmniRoute has **210+ 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, P2C account selection |
+| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |
+| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |
+| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider 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
[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
-### 기여 방법
+### How to Contribute
-1. 저장소 포크
-2. 기능 분기 생성(`git checkout -b feature/amazing-feature`)
-3. 변경 사항을 커밋합니다(`git commit -m 'Add amazing feature'`).
-4. 브랜치(`git push origin feature/amazing-feature`)로 푸시
-5. 풀 리퀘스트 열기
+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
-자세한 지침은 [CONTRIBUTING.md](CONTRIBUTING.md)을 참조하세요.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
-### 새 버전 출시
+### Releasing a New Version
```bash
# Create a release — npm publish happens automatically
-gh release create v1.0.6 --title "v1.0.6" --generate-notes
+gh release create v2.0.0 --title "v2.0.0" --generate-notes
```
---
-## 📊 스타 히스토리
+## 📊 Star History
## Stargazers over time
## [](https://starchart.cc/diegosouzapw/OmniRoute)
-## 🙏 감사의 말씀
+## 🙏 Acknowledgments
-이 포크에 영감을 준 원본 프로젝트인 **[decolua](https://github.com/decolua)**의 **[9router](https://github.com/decolua/9router)**에게 특별히 감사드립니다. OmniRoute는 추가 기능, 다중 모드 API 및 전체 TypeScript 재작성을 통해 놀라운 기반을 구축합니다.
+Special thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.
-이 JavaScript 포트에 영감을 준 최초의 Go 구현인 **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)**에게 특별히 감사드립니다.
+Special thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.
---
-## 📄 라이센스
+## 라이선스
-MIT 라이선스 - 자세한 내용은 [LICENSE](LICENSE)을 참조하세요.
+MIT License - see [LICENSE](LICENSE) for details.
---
대시보드 스크린샷을 보려면 클릭하세요.
+Click to expand tech stack details
-| 페이지 | 스크린샷 | -| -------------- | ------------------------------------------------- | -| **공급자** |  | -| **콤보** |  | -| **분석** |  | -| **건강** |  | -| **번역가** |  | -| **설정** |  | -| **CLI 도구** |  | -| **사용 로그** |  | -| **엔드포인트** |  | +- **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**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions) +- **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
- 연중무휴을 코딩하는 개발자를 위해 ❤️으로 구축됨
+ Built with ❤️ for developers who code 24/7
omniroute.online
+
diff --git a/docs/i18n/ko/docs/FEATURES.md b/docs/i18n/ko/docs/FEATURES.md
new file mode 100644
index 0000000000..f94da700bb
--- /dev/null
+++ b/docs/i18n/ko/docs/FEATURES.md
@@ -0,0 +1,145 @@
+# OmniRoute — Dashboard Features Gallery (한국어)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/FEATURES.md) · 🇪🇸 [es](../../es/docs/FEATURES.md) · 🇫🇷 [fr](../../fr/docs/FEATURES.md) · 🇩🇪 [de](../../de/docs/FEATURES.md) · 🇮🇹 [it](../../it/docs/FEATURES.md) · 🇷🇺 [ru](../../ru/docs/FEATURES.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FEATURES.md) · 🇯🇵 [ja](../../ja/docs/FEATURES.md) · 🇰🇷 [ko](../../ko/docs/FEATURES.md) · 🇸🇦 [ar](../../ar/docs/FEATURES.md) · 🇮🇳 [in](../../in/docs/FEATURES.md) · 🇹🇭 [th](../../th/docs/FEATURES.md) · 🇻🇳 [vi](../../vi/docs/FEATURES.md) · 🇮🇩 [id](../../id/docs/FEATURES.md) · 🇲🇾 [ms](../../ms/docs/FEATURES.md) · 🇳🇱 [nl](../../nl/docs/FEATURES.md) · 🇵🇱 [pl](../../pl/docs/FEATURES.md) · 🇸🇪 [sv](../../sv/docs/FEATURES.md) · 🇳🇴 [no](../../no/docs/FEATURES.md) · 🇩🇰 [da](../../da/docs/FEATURES.md) · 🇫🇮 [fi](../../fi/docs/FEATURES.md) · 🇵🇹 [pt](../../pt/docs/FEATURES.md) · 🇷🇴 [ro](../../ro/docs/FEATURES.md) · 🇭🇺 [hu](../../hu/docs/FEATURES.md) · 🇧🇬 [bg](../../bg/docs/FEATURES.md) · 🇸🇰 [sk](../../sk/docs/FEATURES.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FEATURES.md) · 🇮🇱 [he](../../he/docs/FEATURES.md) · 🇵🇭 [phi](../../phi/docs/FEATURES.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FEATURES.md)
+
+---
+
+Visual guide to every section of the OmniRoute dashboard.
+
+---
+
+## 🔌 Providers
+
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
+
+
+
+---
+
+## 🎨 Combos
+
+Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
+
+
+
+---
+
+## 📊 Analytics
+
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
+
+
+
+---
+
+## 🏥 System Health
+
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+
+
+
+---
+
+## 🔧 Translator Playground
+
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
+
+
+
+---
+
+## 🎮 Model Playground _(v2.0.9+)_
+
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
+
+---
+
+## 🎨 Themes _(v2.0.5+)_
+
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
+
+## ⚙️ Settings
+
+Comprehensive settings panel with tabs:
+
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning
+- **Advanced** — Configuration overrides
+
+
+
+---
+
+## 🔧 CLI Tools
+
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
+
+
+
+---
+
+## 🤖 CLI Agents _(v2.0.11+)_
+
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
+
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
+
+---
+
+## 🖼️ Media _(v2.0.3+)_
+
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
+
+## 📝 Request Logs
+
+Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
+
+
+
+---
+
+## 🌐 API Endpoint
+
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
+
+
+
+---
+
+## 🔑 API Key Management
+
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
+
+---
+
+## 📋 Audit Log
+
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
+
+---
+
+## 🖥️ Desktop Application
+
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
+
+Key features:
+
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
+
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.
diff --git a/docs/i18n/ms/README.md b/docs/i18n/ms/README.md
index b2c0fcee52..54e079f452 100644
--- a/docs/i18n/ms/README.md
+++ b/docs/i18n/ms/README.md
@@ -1,24 +1,94 @@
-omniroute.online
-
-
- # 🚀 OmniRoute — Gerbang AI Percuma
+# 🚀 OmniRoute — The Free AI Gateway (Bahasa Melayu)
-### Jangan sekali-kali berhenti mengekod. Penghalaan pintar ke **model AI PERCUMA & kos rendah** dengan sandaran automatik.
-
-_Proksi API universal anda — satu titik akhir, 36+ pembekal, masa henti sifar._
-
-**Penyelesaian Sembang • Pembenaman • Penjanaan Imej • Audio • Kedudukan Semula • 100% TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Pembekal AI percuma untuk ejen pengekodan kegemaran anda
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Sambungkan mana-mana alat IDE atau CLI berkuasa AI melalui OmniRoute — get laluan API percuma untuk pengekodan tanpa had._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+` tags no longer leak to clients in SSE streaming responses (#585) |
+| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with per-provider/account quota enforcement, idempotency, SHA-256 storage, and optional GitHub issue reporting |
+| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG → generic fallback chain |
+| 🔄 **Model Auto-Sync** | 24h scheduler and manual UI toggle to sync model lists for built-in and custom OpenAI-compatible providers |
+| 🌐 **OpenCode Zen/Go** | Two new providers from @kang-heewon via PR #530: free tier + subscription tier via `OpencodeExecutor` |
+| 🐛 **Gemini CLI OAuth** | Actionable error when `GEMINI_OAUTH_CLIENT_SECRET` is missing in Docker (was cryptic Google error) |
+| 🐛 **OpenCode config** | `saveOpenCodeConfig()` now correctly writes TOML to `XDG_CONFIG_HOME` |
+| 🐛 **Pinned model override** | `body.model` correctly set to `pinnedModel` on context-cache protection |
+| 🐛 **Codex/Claude loop** | `tool_result` blocks now converted to text to stop infinite loops |
+| 🐛 **Login redirect** | Login no longer freezes after skipping password setup |
+| 🐛 **Windows paths** | MSYS2/Git-Bash paths (`/c/...`) normalized to `C:\...` automatically |
+
+---
+
+## 🖼️ Main Dashboard
+
+
-📡 Semua ejen menyambung melalui ` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**Stop wasting money and hitting limits:**
-### 🆕 What's New in v3.0.0
+- Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**OmniRoute solves this:**
+
+- ✅ **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
+- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool
---
-[](https://www.npmjs.com/package/omniroute)
-[](https://hub.docker.com/r/diegosouzapw/omniroute)
-[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
-[](https://omniroute.online)
-[](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
+## 📧 Support
-[🌐 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)
+> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.
-🌐 **Available in:** 🇺🇸 [English](../../README.md) | 🇧🇷 [Português (Brasil)](../pt-BR/README.md) | 🇪🇸 [Español](../es/README.md) | 🇫🇷 [Français](../fr/README.md) | 🇮🇹 [Italiano](../it/README.md) | 🇷🇺 [Русский](../ru/README.md) | 🇨🇳 [中文 (简体)](../zh-CN/README.md) | 🇩🇪 [Deutsch](../de/README.md) | 🇮🇳 [हिन्दी](../in/README.md) | 🇹🇭 [ไทย](../th/README.md) | 🇺🇦 [Українська](../uk-UA/README.md) | 🇸🇦 [العربية](../ar/README.md) | 🇯🇵 [日本語](../ja/README.md) | 🇻🇳 [Tiếng Việt](../vi/README.md) | 🇧🇬 [Български](../bg/README.md) | 🇩🇰 [Dansk](../da/README.md) | 🇫🇮 [Suomi](../fi/README.md) | 🇮🇱 [עברית](../he/README.md) | 🇭🇺 [Magyar](../hu/README.md) | 🇮🇩 [Bahasa Indonesia](../id/README.md) | 🇰🇷 [한국어](../ko/README.md) | 🇲🇾 [Bahasa Melayu](../ms/README.md) | 🇳🇱 [Nederlands](../nl/README.md) | 🇳🇴 [Norsk](../no/README.md) | 🇵🇹 [Português (Portugal)](../pt/README.md) | 🇷🇴 [Română](../ro/README.md) | 🇵🇱 [Polski](../pl/README.md) | 🇸🇰 [Slovenčina](../sk/README.md) | 🇸🇪 [Svenska](../sv/README.md) | 🇵🇭 [Filipino](../phi/README.md)
-
-
-
----
-
-## 🖼️
-
-
-
- # 🚀 OmniRoute — Gerbang AI Percuma
+# 🚀 OmniRoute — The Free AI Gateway (Bahasa Melayu)
-### Jangan sekali-kali berhenti mengekod. Penghalaan pintar ke **model AI PERCUMA & kos rendah** dengan sandaran automatik.
-
-_Proksi API universal anda — satu titik akhir, 36+ pembekal, masa henti sifar._
-
-**Penyelesaian Sembang • Pembenaman • Penjanaan Imej • Audio • Kedudukan Semula • 100% TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Pembekal AI percuma untuk ejen pengekodan kegemaran anda
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Sambungkan mana-mana alat IDE atau CLI berkuasa AI melalui OmniRoute — get laluan API percuma untuk pengekodan tanpa had._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+
+
+[](https://www.npmjs.com/package/omniroute)
+[](https://www.npmjs.com/package/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
+[](https://omniroute.online)
+[](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)
+
+
+
+🌐 **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)
+
+---
+
+## 🆕 What's New in v3.0.0
+
+> **Upgrading from v2.9.5?** — See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes.
+
+| Area | Change |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection remediation |
+| ✅ **Route Validation** | All 176 API routes now validated with Zod schemas + `validateBody()` — CI `check:route-validation:t06` passes |
+| 🐛 **omniModel Tag Leak** | Internal `
+
+
+
+---
+
+## 📸 Dashboard Preview
+
+
+
+
+
+---
+
+### 🤖 Free AI Provider for your favorite coding agents
+
+_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._
Click to see dashboard screenshots
+ +| Page | Screenshot | +| -------------- | ------------------------------------------------- | +| **Providers** |  | +| **Combos** |  | +| **Analytics** |  | +| **Health** |  | +| **Translator** |  | +| **Settings** |  | +| **CLI Tools** |  | +| **Usage Logs** |  | +| **Endpoints** |  | + +|
-
+
OpenClaw @@ -92,113 +162,52 @@ _Sambungkan mana-mana alat IDE atau CLI berkuasa AI melalui OmniRoute — get la |
http://localhost:20128/v1 atau http://cloud.omniroute.online/v1 atau model http://cloud.omniroute.online/v1 —i_24_TOKEN dan satu —i_konfigurasi kuota
+📡 All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 — one config, unlimited models and quota
---
-### 🆕 What's New in v3.0.0
+## 🤔 Why OmniRoute?
-| Area | Change |
-| ------------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal ` Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `
-
-
-
----
-
-## 📸
-
-
-
-
-
----
-
-## 🤔 Mengapa OmniRoute?
-
-**Berhenti membazir wang dan mencapai had:**
-
-- ...
- -| # | # | -| ----- | ---------------------------------------- | -| **1** |  | -| **2** |  | -| **3** |  | -| **4** |  | -| **5** |  | -| **6** |  | -| **7** |  | -| **8** |  | -| **9** |  | - - Kuota langganan tamat tempoh tidak digunakan setiap bulan
-- Had kadar menghalang anda pertengahan pengekodan
-- API Mahal ($20-50/bulan bagi setiap pembekal)
-- Pertukaran manual antara pembekal
-
-**OmniRoute menyelesaikan ini:**
-
-- ✅ **Maksimumkan langganan** - Jejaki kuota, gunakan setiap bit sebelum ditetapkan semula
-- ✅ **Auto sandaran** - Langganan → Kunci API → Murah → Percuma, masa henti sifar
-- ✅ **Berbilang akaun** - Round-robin antara akaun bagi setiap pembekal
-- ✅ **Universal** - Berfungsi dengan Kod Claude, Codex, Gemini CLI, Kursor, Cline, OpenClaw, sebarang alat CLI
-
----
-
-## 📧 Sokongan
-
-> 💬 **Sertai komuniti kami!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Dapatkan bantuan, kongsi petua dan kekal kemas kini.
-
-- **Laman web**: [omniroute.online](https://omniroute.online)
+- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Isu**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Projek Asal**: [9router by decolua](https://github.com/decolua/9router)
+- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 Cara Ia Berfungsi
+## 🔄 How It Works
```
┌─────────────┐
@@ -227,451 +236,453 @@ Result: Never stop coding, minimal cost
---
-## 🎯 Perkara yang Selesaikan OmniRoute — 30 Titik Sakit Nyata & Kes Penggunaan
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **Setiap pembangun yang menggunakan alatan AI menghadapi masalah ini setiap hari.** OmniRoute dibina untuk menyelesaikan kesemuanya — daripada lebihan kos kepada blok serantau, daripada aliran OAuth yang rosak kepada operasi protokol dan kebolehmerhatian perusahaan.
+> **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.
-
💸 1. "Saya membayar untuk langganan yang mahal tetapi masih terganggu oleh had"
+💸 1. "I pay for an expensive subscription but still get interrupted by limits"
-Pembangun membayar $20–200/bulan untuk Claude Pro, Codex Pro atau GitHub Copilot. Walaupun membayar, kuota mempunyai siling — 5j penggunaan, had mingguan atau had kadar seminit. Sesi pertengahan pengekodan, pembekal berhenti bertindak balas dan pembangun kehilangan aliran dan produktiviti. +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. -**Cara OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- **Smart 4-Tier Fallback** — Jika kuota langganan habis, diubah hala secara automatik ke API Key → Murah → Percuma tanpa campur tangan manual -- **Penjejakan Kuota Masa Nyata** — Menunjukkan penggunaan token dalam masa nyata dengan kira detik tetapan semula (5j, harian, mingguan) -- **Sokongan Berbilang Akaun** — Berbilang akaun bagi setiap pembekal dengan auto round-robin — apabila satu kehabisan, beralih kepada yang seterusnya -- **Kombo Tersuai** — Rantaian sandaran yang boleh disesuaikan dengan 6 strategi pengimbangan (isi dahulu, round-robin, P2C, rawak, paling kurang digunakan, dioptimumkan kos) -- **Kuota Perniagaan Codex** — Pemantauan kuota ruang kerja Perniagaan/Pasukan terus dalam papan pemuka +- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention +- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly) +- **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 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
-` daripada model seperti DeepSeek R1 ke dalam `reasoning_content` standard
-- **Output Berstruktur untuk Gemini** — `json_schema` → `responseMimeType`/`responseSchema` penukaran automatik
-- **`stream` lalai kepada `false`** — Menjajarkan dengan spesifikasi OpenAI, mengelakkan SSE yang tidak dijangka dalam Python/Rust/Go SDK
+- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 67+ 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
🔌 2. "Saya perlu menggunakan berbilang penyedia tetapi setiap satu mempunyai API yang berbeza"
+🔌 2. "I need to use multiple providers but each has a different API"
-OpenAI menggunakan satu format, Claude (Anthropic) menggunakan satu lagi, Gemini satu lagi. Jika pembangun ingin menguji model daripada pembekal yang berbeza atau sandaran antara mereka, mereka perlu mengkonfigurasi semula SDK, menukar titik akhir, menangani format yang tidak serasi. Pembekal tersuai (FriendLI, NIM) mempunyai titik akhir model bukan standard. +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. -**Cara OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- **Titik Akhir Disatukan** — Satu `http://localhost:20128/v1` berfungsi sebagai proksi untuk kesemua 36+ pembekal -- **Format Terjemahan** — Automatik dan telus: OpenAI ↔ Claude ↔ Gemini ↔ Responses API -- **Pembersihan Tindak Balas** — Mengosongkan medan bukan standard (`x_groq`, `usage_breakdown`, `service_tier`) yang memecahkan OpenAI SDK v1.83+ -- **Penormalan Peranan** — Menukar `developer` → `system` untuk penyedia bukan OpenAI; `system` → `user` untuk GLM/ERNIE -- **Think Tag Extraction** — Mengekstrak blok `
-
🌐 3. "Pembekal AI saya menyekat wilayah/negara saya"
+🌐 3. "My AI provider blocks my region/country"
-Penyedia seperti OpenAI/Codex menyekat akses daripada kawasan geografi tertentu. Pengguna mendapat ralat seperti `unsupported_country_region_territory` semasa sambungan OAuth dan API. Ini amat mengecewakan bagi pemaju dari negara membangun. +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. -**Cara OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- **Konfigurasi Proksi 3 Tahap** — Proksi boleh dikonfigurasikan pada 3 peringkat: global (semua trafik), setiap pembekal (satu pembekal sahaja) dan setiap sambungan/kunci -- **Lencana Proksi Berkod Warna** — Penunjuk visual: 🟢 proksi global, 🟡 proksi pembekal, 🔵 proksi sambungan, sentiasa menunjukkan IP -- **Pertukaran Token OAuth Melalui Proksi** — Aliran OAuth juga melalui proksi, menyelesaikan `unsupported_country_region_territory` -- **Ujian Sambungan melalui Proksi** — Ujian sambungan menggunakan proksi yang dikonfigurasikan (tiada lagi pintasan langsung) -- **Sokongan SOCKS5** — Sokongan proksi SOCKS5 penuh untuk penghalaan keluar -- **TLS Fingerprint Spoofing** — Cap jari TLS seperti pelayar melalui `wreq-js` untuk memintas pengesanan bot +- **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
-` prefix
-- **Kombo Percuma Sahaja** — Rantaian `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/bulan dengan masa henti sifar
-- **Kredit Percuma NVIDIA NIM** — 1000 kredit percuma disepadukan
-- **Strategi Dioptimumkan Kos** — Strategi penghalaan yang secara automatik memilih pembekal yang tersedia paling murah
+- **Free-Only Combos** — Chain `gc/gemini-3-flash → 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
🆓 4. "Saya mahu menggunakan AI untuk pengekodan tetapi saya tidak mempunyai wang"
+🆓 4. "I want to use AI for coding but I have no money"
-Tidak semua orang boleh membayar $20–200/bulan untuk langganan AI. Pelajar, pembangun dari negara baru muncul, penggemar dan pekerja bebas memerlukan akses kepada model berkualiti pada kos sifar. +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. -**Cara OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- **Pembekal Peringkat Percuma Terbina dalam** — Sokongan asli untuk 100% pembekal percuma: iFlow (8 model tanpa had), Qwen (3 model tanpa had), Kiro (Claude secara percuma), Gemini CLI (180K/bulan percuma) +- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free) - **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/
-
🔒 5. "Saya perlu melindungi gerbang AI saya daripada akses tanpa kebenaran"
+🔒 5. "I need to protect my AI gateway from unauthorized access"
-Apabila mendedahkan get laluan AI kepada rangkaian (LAN, VPS, Docker), sesiapa sahaja yang mempunyai alamat boleh menggunakan token/kuota pembangun. Tanpa perlindungan, API terdedah kepada penyalahgunaan, suntikan segera dan penyalahgunaan. +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. -**Cara OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- **Pengurusan Kunci API** — Penjanaan, penggiliran dan skop setiap pembekal dengan halaman `/dashboard/api-manager` khusus -- **Kebenaran Tahap Model** — Hadkan kunci API kepada model tertentu (`openai/*`, corak kad bebas), dengan Togol Benarkan Semua/Sekat -- **Perlindungan Titik Akhir API** — Memerlukan kunci untuk `/v1/models` dan menyekat penyedia tertentu daripada penyenaraian -- **Auth Guard + CSRF Protection** — Semua laluan papan pemuka dilindungi dengan `withAuth` middleware + token CSRF -- **Penghad Kadar** — Pengehadan kadar Per-IP dengan tetingkap boleh dikonfigurasikan -- **Penapisan IP** — Senarai Benar/senarai sekat untuk kawalan akses -- **Pengawal Suntikan Segera** — Pensanitasi terhadap corak segera yang berniat jahat -- **Penyulitan AES-256-GCM** — Bukti kelayakan disulitkan semasa rehat +- **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. "Pembekal saya gagal dan saya kehilangan aliran pengekodan saya"
+🛑 6. "My provider went down and I lost my coding flow"
-Pembekal AI boleh menjadi tidak stabil, mengembalikan ralat 5xx atau mencapai had kadar sementara. Jika pembangun bergantung pada penyedia tunggal, mereka akan terganggu. Tanpa pemutus litar, percubaan semula berulang boleh ranap aplikasi. +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. -**Cara OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- **Pemutus Litar bagi setiap pembekal** — Auto buka/tutup dengan ambang boleh dikonfigurasikan dan cooldown (Ditutup/Buka/Separuh Terbuka) -- **Penyingkiran Eksponen** — Kelewatan percubaan semula progresif -- **Kawanan Anti Gemuruh** — Mutex + perlindungan semafor terhadap ribut percubaan semula serentak -- **Kombo Rantai Sandar** — Jika pembekal utama gagal, secara automatik jatuh melalui rantaian tanpa campur tangan -- **Pemutus Litar Kombo** — Lumpuhkan automatik pembekal yang gagal dalam rantaian kombo -- **Papan Pemuka Kesihatan** — Pemantauan masa aktif, keadaan pemutus litar, penguncian, statistik cache, kependaman p50/p95/p99 +- **Circuit Breaker per-model** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks +- **Exponential Backoff** — Progressive retry delays +- **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 +- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain +- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
-
🔧 7. "Mengkonfigurasi setiap alat AI adalah membosankan dan berulang"
+🔧 7. "Configuring each AI tool is tedious and repetitive"
-Pembangun menggunakan Kursor, Kod Claude, Codex CLI, OpenClaw, Gemini CLI, Kod Kilo... Setiap alat memerlukan konfigurasi yang berbeza (titik akhir API, kunci, model). Mengkonfigurasi semula apabila menukar pembekal atau model adalah membuang masa. +Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time. -**Cara OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- **Papan Pemuka Alat CLI** — Halaman khusus dengan persediaan satu klik untuk Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline -- **GitHub Copilot Config Generator** — Menghasilkan `chatLanguageModels.json` untuk Kod VS dengan pemilihan model pukal -- **Onboarding Wizard** — Persediaan 4 langkah berpandu untuk pengguna kali pertama -- **Satu titik akhir, semua model** — Konfigurasikan `http://localhost:20128/v1` sekali, akses 36+ pembekal +- **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 67+ providers
-
🔑 8. "Menguruskan token OAuth daripada berbilang penyedia adalah neraka"
+🔑 8. "Managing OAuth tokens from multiple providers is hell"
-Kod Claude, Codex, Gemini CLI, Copilot — semuanya menggunakan OAuth 2.0 dengan token tamat tempoh. Pembangun perlu sentiasa mengesahkan semula, menangani `client_secret is missing`, `redirect_uri_mismatch` dan kegagalan pada pelayan jauh. OAuth pada LAN/VPS amat bermasalah. +Claude Code, Codex, Gemini CLI, 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. -**Cara OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- **Muat Semula Token Auto** — Token OAuth dimuat semula di latar belakang sebelum tamat tempoh -- **OAuth 2.0 (PKCE) Terbina dalam** — Aliran automatik untuk Kod Claude, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow -- **OAuth Berbilang Akaun** — Berbilang akaun bagi setiap pembekal melalui pengekstrakan token JWT/ID -- **OAuth LAN/Remote Fix** — Pengesanan IP peribadi untuk `redirect_uri` + mod URL manual untuk pelayan jauh -- **OAuth Behind Nginx** — Menggunakan `window.location.origin` untuk keserasian proksi terbalik -- **Panduan OAuth Jauh** — Panduan langkah demi langkah untuk kelayakan Google Cloud pada VPS/Docker +- **Auto Token Refresh** — OAuth tokens refresh in background before expiration +- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow +- **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. "Saya tidak tahu berapa banyak yang saya belanjakan atau di mana"
+📊 9. "I don't know how much I'm spending or where"
-Pembangun menggunakan berbilang penyedia berbayar tetapi tidak mempunyai pandangan bersatu tentang perbelanjaan. Setiap pembekal mempunyai papan pemuka pengebilan sendiri, tetapi tiada paparan disatukan. Kos yang tidak dijangka boleh bertimbun. +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. -**Cara OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- **Papan Pemuka Analitis Kos** — Penjejakan kos per-token dan pengurusan belanjawan bagi setiap pembekal -- **Had Belanjawan setiap Peringkat** — Siling perbelanjaan setiap peringkat yang mencetuskan sandaran automatik -- **Konfigurasi Harga Per-Model** — Harga boleh dikonfigurasikan bagi setiap model -- **Statistik Penggunaan Setiap Kunci API** — Kiraan permintaan dan cap masa yang terakhir digunakan setiap kunci -- **Papan Pemuka Analitik** — Kad statistik, carta penggunaan model, jadual pembekal dengan kadar kejayaan dan kependaman +- **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. "Saya tidak dapat mendiagnosis ralat dan masalah dalam panggilan AI"
+🐛 10. "I can't diagnose errors and problems in AI calls"
-Apabila panggilan gagal, pembangun tidak tahu sama ada ia adalah had kadar, token tamat tempoh, format yang salah atau ralat pembekal. Log berpecah-belah merentasi terminal yang berbeza. Tanpa pemerhatian, penyahpepijatan adalah percubaan-dan-ralat. +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. -**Cara OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- **Papan Pemuka Log Bersatu** — 4 tab: Log Permintaan, Log Proksi, Log Audit, Konsol -- **Pemapar Log Konsol** — Pemapar gaya terminal masa nyata dengan tahap berkod warna, tatal automatik, carian, penapis -- **Log Proksi SQLite** — Log berterusan yang bertahan dimulakan semula -- **Taman Permainan Penterjemah** — 4 mod nyahpepijat: Taman Permainan (terjemahan format), Penguji Sembang (perjalanan pergi balik), Bangku Ujian (batch), Monitor Langsung (masa nyata) -- **Permintaan Telemetri** — kependaman p50/p95/p99 + pengesanan X-Request-Id -- **Pengelogan Berasaskan Fail dengan Putaran** — Pemintas konsol menangkap segala-galanya ke log JSON dengan putaran berasaskan saiz +- **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 Proxy Logs** — Persistent logs that survive server restarts +- **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 Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation +- **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. "Menyedia dan menyelenggara gerbang adalah rumit"
+🏗️ 11. "Deploying and maintaining the gateway is complex"
-Memasang, mengkonfigurasi dan menyelenggara proksi AI merentas persekitaran yang berbeza (tempatan, VPS, Docker, awan) adalah intensif buruh. Masalah seperti laluan berkod keras, `EACCES` pada direktori, konflik port dan binaan merentas platform menambah geseran. +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. -**Cara OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- **pemasangan global npm** — `npm install -g omniroute && omniroute` — selesai -- **Docker Multi-Platform** — AMD64 + ARM64 asli (Apple Silicon, AWS Graviton, Raspberry Pi) -- **Profil Karang Docker** — `base` (tiada alat CLI) dan `cli` (dengan Kod Claude, Codex, OpenClaw) -- **Apl Desktop Elektron** — Apl asli untuk Windows/macOS/Linux dengan dulang sistem, auto mula, mod luar talian -- **Mod Split-Port** — API dan Papan Pemuka pada port berasingan untuk senario lanjutan (proksi terbalik, rangkaian kontena) -- **Cloud Sync** — Konfigurasikan penyegerakan merentas peranti melalui Cloudflare Workers -- **Sandaran DB** — Sandaran automatik, pulihkan, eksport dan import semua tetapan +- **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
-
🌍 12. "Antara muka adalah bahasa Inggeris sahaja dan pasukan saya tidak berbahasa Inggeris"
+🌍 12. "The interface is English-only and my team doesn't speak English"
-Pasukan di negara bukan berbahasa Inggeris, terutamanya di Amerika Latin, Asia dan Eropah, bergelut dengan antara muka bahasa Inggeris sahaja. Halangan bahasa mengurangkan penggunaan dan meningkatkan ralat konfigurasi. +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. -**Cara OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- **Papan pemuka i18n — 30 Bahasa** — Semua 500+ kunci diterjemahkan termasuk bahasa Arab, Bulgaria, Denmark, Jerman, Sepanyol, Finland, Perancis, Ibrani, Hindi, Hungary, Indonesia, Itali, Jepun, Korea, Melayu, Belanda, Norway, Poland, Portugis (PT/BR), Romania, Rusia, Slovak, Sweden, Thai, Ukraine, Vietnam, Cina -- **Sokongan RTL** — Sokongan kanan ke kiri untuk bahasa Arab dan Ibrani -- **README Berbilang Bahasa** — 30 terjemahan dokumentasi lengkap -- **Pemilih Bahasa** — Ikon Glob dalam pengepala untuk penukaran masa nyata +- **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. "Saya perlukan lebih daripada sembang — saya perlukan benam, imej, audio"
+🔄 13. "I need more than chat — I need embeddings, images, audio"
-AI bukan sekadar penyelesaian sembang. Pembangun perlu menjana imej, menyalin audio, membuat pembenaman untuk RAG, menyusun semula dokumen dan kandungan sederhana. Setiap API mempunyai titik akhir dan format yang berbeza. +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. -**Cara OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- **Pembenaman** — `/v1/embeddings` dengan 6 pembekal dan 9+ model -- **Penjanaan Imej** — `/v1/images/generations` dengan 10 pembekal dan 20+ model (OpenAI, xAI, Together, Bunga Api, Nebius, Hiperbolik, NanoBanana, Antigraviti, SD WebUI, ComfyUI) -- **Teks-ke-Video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) dan SD WebUI -- **Teks-ke-Muzik** — `/v1/music/generations` — ComfyUI (Audio Terbuka, MusicGen) -- **Transkripsi Audio** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3 -- **Teks-ke-Ucapan** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, Inworld, Cartesia, PlayHT, + pembekal sedia ada -- **Moderasi** — `/v1/moderations` — Pemeriksaan keselamatan kandungan -- **Penyusunan semula** — `/v1/rerank` — Penyusunan semula perkaitan dokumen -- **Respons API** — Sokongan penuh `/v1/responses` untuk Codex +- **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. "Saya tiada cara untuk menguji dan membandingkan kualiti merentas model"
+🧪 14. "I have no way to test and compare quality across models"
-Pembangun ingin mengetahui model mana yang terbaik untuk kes penggunaan mereka — kod, terjemahan, penaakulan — tetapi membandingkan secara manual adalah perlahan. Tiada alat eval bersepadu wujud. +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. -**Cara OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- **LLM Evaluations** — Ujian set emas dengan 10 kes pra-muat meliputi salam, matematik, geografi, penjanaan kod, pematuhan JSON, terjemahan, penurunan harga, penolakan keselamatan -- **4 Strategi Padanan** — `exact`, `contains`, `regex`, `custom` (fungsi JS) -- **Bangku Ujian Taman Permainan Penterjemah** — Ujian kelompok dengan berbilang input dan output yang dijangka, perbandingan merentas pembekal -- **Penguji Sembang** — Perjalanan pergi balik penuh dengan pemaparan respons visual -- **Pantau Langsung** — Strim masa nyata semua permintaan yang mengalir melalui proksi +- **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. "Saya perlu skala tanpa kehilangan prestasi"
+📈 15. "I need to scale without losing performance"
-Apabila volum permintaan bertambah, tanpa menyimpan cache soalan yang sama menjana kos pendua. Tanpa idempotensi, pendua meminta pemprosesan sisa. Had kadar setiap pembekal mesti dipatuhi. +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. -**Cara OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- **Cache Semantik** — Cache dua peringkat (tandatangan + semantik) mengurangkan kos dan kependaman -- **Request Idempotency** — tetingkap penyahduplikasi 5s untuk permintaan yang sama -- **Pengesanan Had Kadar** — RPM setiap pembekal, jurang min dan penjejakan serentak maks -- **Had Kadar Boleh Diedit** — Lalai boleh dikonfigurasikan dalam Tetapan → Ketahanan dengan kegigihan -- **Cache Pengesahan Kunci API** — Cache 3 peringkat untuk prestasi pengeluaran -- **Papan Pemuka Kesihatan dengan Telemetri** — kependaman p50/p95/p99, statistik cache, masa beroperasi +- **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 +- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence +- **API Key Validation Cache** — 3-tier cache for production performance +- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
-
🤖 16. "Saya mahu mengawal tingkah laku model secara global"
+🤖 16. "I want to control model behavior globally"
-Pembangun yang mahukan semua respons dalam bahasa tertentu, dengan nada tertentu atau ingin mengehadkan token penaakulan. Mengkonfigurasi ini dalam setiap alat/permintaan adalah tidak praktikal. +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. -**Cara OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- **System Prompt Injection** — Gesaan global digunakan untuk semua permintaan -- **Pengesahan Belanjawan Berfikir** — Kawalan peruntukan token penaakulan setiap permintaan (laluan, auto, tersuai, adaptif) -- **6 Strategi Penghalaan** — Strategi global yang menentukan cara permintaan diedarkan -- **Penghala Wildcard** — Corak `provider/*` halakan secara dinamik kepada mana-mana pembekal -- **Kombo Dayakan/Lumpuhkan Togol** — Togol kombo terus dari papan pemuka -- **Togol Pembekal** — Dayakan/lumpuhkan semua sambungan untuk pembekal dengan satu klik -- **Pembekal Disekat** — Kecualikan pembekal khusus daripada penyenaraian `/v1/models` +- **System Prompt Injection** — Global prompt applied to all requests +- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive) +- **6 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 +- **Provider Toggle** — Enable/disable all connections for a provider with one click +- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
-
🧰 17. "Saya memerlukan alatan MCP sebagai keupayaan produk kelas pertama"
+🧰 17. "I need MCP tools as first-class product capabilities"
-Banyak get laluan AI mendedahkan MCP hanya sebagai butiran pelaksanaan tersembunyi. Pasukan memerlukan lapisan operasi yang boleh dilihat dan boleh diurus. +Many AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer. -**Cara OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- MCP muncul dalam navigasi papan pemuka dan tab protokol titik akhir -- Halaman pengurusan MCP khusus dengan proses, alatan, skop dan audit -- Permulaan pantas terbina dalam untuk `omniroute --mcp` dan onboarding pelanggan +- 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. "Saya memerlukan orkestrasi A2A dengan laluan tugas penyegerakan + aliran"
+🧠 18. "I need A2A orchestration with sync + stream task paths"
-Aliran kerja ejen memerlukan balasan langsung dan pelaksanaan strim jangka panjang dengan kawalan kitaran hayat. +Agent workflows need both direct replies and long-running streamed execution with lifecycle control. -**Cara OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- Titik akhir A2A JSON-RPC (`POST /a2a`) dengan `message/send` dan `message/stream` -- Penstriman SSE dengan penyebaran keadaan terminal -- API kitaran hayat tugas untuk `tasks/get` dan `tasks/cancel` +- 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. "Saya memerlukan kesihatan proses MCP sebenar, bukan status yang diduga"
+🛰️ 19. "I need real MCP process health, not guessed status"
-Pasukan operasi perlu mengetahui sama ada MCP sebenarnya masih hidup, bukan hanya sama ada API boleh dicapai. +Operational teams need to know if MCP is actually alive, not just whether an API is reachable. -**Cara OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- Fail degupan jantung masa jalan dengan PID, cap masa, pengangkutan, kiraan alat dan mod skop -- API status MCP yang menggabungkan degupan jantung + aktiviti terkini -- Kad status UI untuk kesegaran proses/masa hidup/degupan jantung +- 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. "Saya memerlukan pelaksanaan alat MCP yang boleh diaudit"
+📋 20. "I need auditable MCP tool execution"
-Apabila alat mengubah konfigurasi atau mencetuskan tindakan ops, pasukan memerlukan kebolehkesanan forensik. +When tools mutate config or trigger ops actions, teams need forensic traceability. -**Cara OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- Pengelogan audit yang disokong SQLite untuk panggilan alat MCP -- Tapis mengikut alat, kejayaan/kegagalan, kunci API dan penomboran -- Jadual audit papan pemuka + titik akhir statistik untuk automasi +- 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. "Saya memerlukan keizinan MCP berskop bagi setiap penyepaduan"
+🔐 21. "I need scoped MCP permissions per integration"
-Pelanggan yang berbeza harus mempunyai akses paling tidak istimewa kepada kategori alat. +Different clients should have least-privilege access to tool categories. -**Cara OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- 9 skop MCP berbutir untuk akses alat terkawal -- Penguatkuasaan skop dan keterlihatan dalam UI pengurusan MCP -- Postur lalai yang selamat untuk perkakas operasi +- 9 granular MCP scopes for controlled tool access +- Scope enforcement and visibility in MCP management UI +- Safe default posture for operational tooling
-
⚙️ 22. "Saya memerlukan kawalan operasi tanpa mengatur semula"
+⚙️ 22. "I need operational controls without redeploying"
-Pasukan memerlukan perubahan masa jalan yang cepat semasa insiden atau peristiwa kos. +Teams need quick runtime changes during incidents or cost events. -**Cara OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- Tukar pengaktifan kombo terus dari papan pemuka MCP -- Gunakan profil daya tahan daripada pek dasar yang telah ditetapkan -- Tetapkan semula keadaan pemutus litar daripada panel operasi yang sama +- Switch combo activation directly from MCP dashboard +- Apply resilience profiles from pre-defined policy packs +- Reset circuit breaker state from the same operations panel
-
🔄 23. "Saya memerlukan keterlihatan dan pembatalan kitaran hayat tugas A2A secara langsung"
+🔄 23. "I need live A2A task lifecycle visibility and cancellation"
-Tanpa keterlihatan kitaran hayat, insiden tugasan menjadi sukar untuk dicuba. +Without lifecycle visibility, task incidents become hard to triage. -**Cara OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- Penyenaraian tugas/penapisan mengikut keadaan/kemahiran dengan penomboran -- Latih tubi tentang metadata tugas, peristiwa dan artifak -- Titik akhir pembatalan tugas dan tindakan UI dengan pengesahan +- 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. "Saya memerlukan metrik strim aktif untuk beban A2A"
+🌊 24. "I need active stream metrics for A2A load"
-Aliran kerja penstriman memerlukan cerapan operasi tentang konkurensi dan sambungan langsung. +Streaming workflows require operational insight into concurrency and live connections. -**Cara OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- Kaunter aliran aktif disepadukan ke dalam status A2A -- Cap masa tugas terakhir dan kiraan setiap negeri -- Kad papan pemuka A2A untuk pemantauan operasi masa nyata +- Active stream counters integrated into A2A status +- Last task timestamp and per-state counts +- A2A dashboard cards for real-time ops monitoring
-
🪪 25. "Saya memerlukan penemuan ejen standard untuk pelanggan"
+🪪 25. "I need standard agent discovery for clients"
-Pelanggan dan orkestra luar memerlukan metadata yang boleh dibaca mesin untuk onboarding. +External clients and orchestrators need machine-readable metadata for onboarding. -**Cara OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- Kad Agen terdedah pada `/.well-known/agent.json` -- Keupayaan dan kemahiran ditunjukkan dalam UI pengurusan -- API status A2A termasuk metadata penemuan untuk automasi +- Agent Card exposed at `/.well-known/agent.json` +- Capabilities and skills shown in management UI +- A2A status API includes discovery metadata for automation
-
🧭 26. "Saya memerlukan kebolehtemuan protokol dalam produk UX"
+🧭 26. "I need protocol discoverability in the product UX"
-Jika pengguna tidak dapat menemui permukaan protokol, penggunaan dan kualiti sokongan akan menurun. +If users cannot discover protocol surfaces, adoption and support quality drop. -**Cara OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- Entri bar sisi untuk MCP dan A2A -- Tab Protokol halaman titik akhir dengan permulaan pantas dan status -- Pautan dari gambaran keseluruhan ke papan pemuka pengurusan khusus +- 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. "Saya memerlukan pengesahan protokol hujung ke hujung dengan pelanggan sebenar"
+🧪 27. "I need end-to-end protocol validation with real clients"
-Ujian olok-olok tidak mencukupi untuk mengesahkan keserasian protokol sebelum dikeluarkan. +Mock tests are not enough to validate protocol compatibility before release. -**Cara OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- Suite E2E yang but apl dan menggunakan pengangkutan pelanggan MCP SDK sebenar -- Ujian pelanggan A2A untuk penemuan, menghantar, menstrim, mendapatkan dan membatalkan aliran -- Periksa silang dakwaan terhadap audit MCP dan API tugasan A2A +- 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. "Saya memerlukan pemerhatian bersatu merentas semua antara muka"
+📡 28. "I need unified observability across all interfaces"
-Memisahkan kebolehmerhatian mengikut protokol mewujudkan titik buta dan MTTR yang lebih panjang. +Splitting observability by protocol creates blind spots and longer MTTR. -**Cara OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- Papan pemuka/log/analisis bersatu dalam satu produk -- Kesihatan + audit + telemetri permintaan merentas lapisan OpenAI, MCP dan A2A -- API Operasi untuk status dan automasi +- Unified dashboards/logs/analytics in one product +- Health + audit + request telemetry across OpenAI, MCP, and A2A layers +- Operational APIs for status and automation
-
💼 29. "Saya memerlukan satu masa jalan untuk proksi + alatan + orkestrasi ejen"
+💼 29. "I need one runtime for proxy + tools + agent orchestration"
-Menjalankan banyak perkhidmatan berasingan meningkatkan kos operasi dan mod kegagalan. +Running many separate services increases operational cost and failure modes. -**Cara OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- Proksi serasi OpenAI, pelayan MCP dan pelayan A2A dalam satu tindanan -- Kebenaran dikongsi, daya tahan, stor data dan kebolehmerhatian -- Model dasar yang konsisten merentas semua permukaan interaksi +- 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
-
-### Contoh Buku Main (Kes Penggunaan Bersepadu)
+### Example Playbooks (Integrated Use Cases)
-**Playbook A: Maksimumkan langganan berbayar + sandaran murah**
+**Playbook A: Maximize paid subscription + cheap backup**
```txt
Combo: "maximize-claude"
@@ -683,7 +694,7 @@ Monthly cost: $20 + small backup spend
Outcome: higher quality, near-zero interruption
```
-**Playbook B: Timbunan pengekodan kos sifar**
+**Playbook B: Zero-cost coding stack**
```txt
Combo: "free-forever"
@@ -695,7 +706,7 @@ Monthly cost: $0
Outcome: stable free coding workflow
```
-**Playbook C: 24/7 rantai sandaran sentiasa hidup**
+**Playbook C: 24/7 always-on fallback chain**
```txt
Combo: "always-on"
@@ -708,65 +719,132 @@ Combo: "always-on"
Outcome: deep fallback depth for deadline-critical workloads
```
-**Playbook D: Operasi ejen dengan MCP + A2A**
+**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/mcp and /dashboard/a2a
-4) Control incidents with resilience profile + task cancellation
+3) Observe via /dashboard/endpoint (MCP and A2A tabs)
+4) Toggle services via inline status controls
```
---
-## ⚡ Mula Pantas
+## 🆓 Start Free — Zero Configuration Cost
-**1. Pasang secara global:**
+> 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 **iFlow** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |
+| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |
+| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |
+| 5 | `/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).
+
+## Mula Pantas
+
+### 1) Install and run
```bash
npm install -g omniroute
omniroute
```
-🎉 Papan pemuka dibuka pada `http://localhost:20128`
+> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:
+>
+> ```bash
+> pnpm install -g omniroute
+> pnpm approve-builds -g # Select all packages → approve
+> omniroute
+> ```
-| Perintah | Penerangan |
-| ----------------------- | ---------------------------------- |
-| `omniroute` | Mulakan pelayan (port lalai 20128) |
-| `omniroute --port 3000` | Gunakan port tersuai |
-| `omniroute --no-open` | Jangan auto buka penyemak imbas |
-| `omniroute --help` | Tunjukkan bantuan |
+Dashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.
-**2. Sambungkan pembekal PERCUMA:**
+| 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 |
-Papan pemuka → Pembekal → Sambung **Kod Claude** atau **Antigraviti** → Log masuk OAuth → Selesai!
+Optional split-port mode:
-**3. Gunakan dalam alat CLI anda:**
-
-```
-Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Settings:
- Endpoint: http://localhost:20128/v1
- API Key: [copy from dashboard]
- Model: if/kimi-k2-thinking
+```bash
+PORT=20128 DASHBOARD_PORT=20129 omniroute
+# API: http://localhost:20128/v1
+# Dashboard: http://localhost:20129
```
-**Itu sahaja!** Mulakan pengekodan dengan model AI PERCUMA.
+### 2) Connect providers and create your API key
-**Alternatif — dijalankan dari sumber:**
+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
+
+```txt
+Base URL: http://localhost:20128/v1
+API Key: [copy from Endpoint page]
+Model: if/kimi-k2-thinking (or any provider/model prefix)
+```
+
+Works with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.
+
+### 4) Enable and validate protocols (v2.0)
+
+**MCP (for tool-driven operations):**
+
+```bash
+omniroute --mcp
+```
+
+Then connect your MCP client over `stdio` and test tools like:
+
+- `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 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
+PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev
```
---
## 🐳 Docker
-OmniRoute tersedia sebagai imej Docker awam pada [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
+OmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
-**Larian pantas:**
+**Quick run:**
```bash
docker run -d \
@@ -777,7 +855,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Dengan fail persekitaran:**
+**With environment file:**
```bash
# Copy and edit .env first
@@ -792,7 +870,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Menggunakan Docker Compose:**
+**Using Docker Compose:**
```bash
# Base profile (no CLI tools)
@@ -802,258 +880,552 @@ docker compose --profile base up -d
docker compose --profile cli up -d
```
-| Imej | Tag | Saiz | Penerangan |
-| ------------------------ | -------- | ------ | ----------------------- |
-| `diegosouzapw/omniroute` | `latest` | ~250MB | Keluaran stabil terkini |
-| `diegosouzapw/omniroute` | `1.0.3` | ~250MB | Versi semasa |
+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.
+- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.
+- 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` | `1.0.3` | ~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
+### Mula Pantas
+
```bash
-npm run electron:dev # Development mode
+# 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)
+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)
---
-## 💰 Sekilas Pandang Harga
+## 💰 Pricing at a Glance
-| Peringkat | Pembekal | Kos | Set Semula Kuota | Terbaik Untuk |
-| ---------------- | ---------------- | ---------------------------- | ------------------ | ----------------------- |
-| **💳 LANGGANAN** | Kod Claude (Pro) | $20/bln | 5j + mingguan | Sudah melanggan |
-| | Codex (Plus/Pro) | $20-200/bln | 5j + mingguan | Pengguna OpenAI |
-| | Gemini CLI | **PERCUMA** | 180K/bln + 1K/hari | Semua orang! |
-| | GitHub Copilot | $10-19/bln | Bulanan | Pengguna GitHub |
-| **🔑 KUNCI API** | NVIDIA NIM | **PERCUMA** (1000 kredit) | Satu kali | Ujian peringkat percuma |
-| | DeepSeek | Bayar setiap penggunaan | Tiada | Harga/kualiti terbaik |
-| | Groq | Peringkat percuma + berbayar | Kadar terhad | Inferens sangat pantas |
-| | xAI (Grok) | Bayar setiap penggunaan | Tiada | Model Grok |
-| | Mistral | Peringkat percuma + berbayar | Kadar terhad | AI Eropah |
-| | OpenRouter | Bayar setiap penggunaan | Tiada | 100+ model |
-| **💰 MURAH** | GLM-4.7 | $0.6/1J | Setiap hari 10AM | Sandaran belanjawan |
-| | MiniMax M2.1 | $0.2/1J | 5 jam bergolek | Pilihan termurah |
-| | Kimi K2 | $9/bln flat | 10 juta token/bln | Kos yang boleh diramal |
-| **🆓 PERCUMA** | iFlow | $0 | tanpa had | 8 model percuma |
-| | Qwen | $0 | tanpa had | 3 model percuma |
-| | Kiro | $0 | tanpa had | Claude percuma |
+| 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 |
+| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |
+| | 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** | iFlow | **$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 |
-**💡 Petua Pro:** Mulakan dengan Gemini CLI (180K percuma/bulan) + iFlow (percuma tanpa had) kombo = $0 kos!
+> 🆕 **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
+iFlow (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.
---
-## 💡 Ciri Utama
+---
-### 🧠 Penghalaan Teras & Kepintaran
+## 🆓 Free Models — What You Actually Get
-| Ciri | Apa yang Dilakukan |
-| ---------------------------------- | --------------------------------------------------------------------------------------------- |
-| 🎯 **Smart 4-Tier Fallback** | Laluan automatik: Langganan → Kunci API → Murah → Percuma |
-| 📊 **Penjejakan Kuota Masa Nyata** | Kiraan token langsung + tetapan semula kira detik setiap pembekal |
-| 🔄 **Terjemahan Format** | OpenAI ↔ Claude ↔ Gemini ↔ Kursor ↔ Kiro lancar + pembersihan tindak balas |
-| 👥 **Sokongan Berbilang Akaun** | Berbilang akaun bagi setiap pembekal dengan pemilihan pintar |
-| 🔄 **Muat Semula Token Auto** | Token OAuth dimuat semula secara automatik dengan cuba semula |
-| 🎨 **Kombo Tersuai** | 6 strategi: isikan dahulu, round-robin, p2c, rawak, paling kurang digunakan, dioptimumkan kos |
-| 🧩 **Model Tersuai** | Tambahkan sebarang ID model pada mana-mana pembekal |
-| 🌐 **Penghala Wildcard** | Halakan corak `provider/*` kepada mana-mana pembekal secara dinamik |
-| 🧠 **Anggaran Berfikir** | Mod laluan, auto, tersuai dan adaptif untuk model penaakulan |
-| 🔀 **Model Aliases** | Auto-forward deprecated model IDs to current replacements (built-in + custom) |
-| ⚡ **Background Degradation** | Auto-route background tasks (titles, summaries) to cheaper models |
-| 💬 **System Prompt Suntikan** | Gesaan sistem global digunakan merentas semua permintaan |
-| 📄 **API Respons** | Sokongan OpenAI Responses API (`/v1/responses`) penuh untuk Codex |
+> 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.
-### 🎵 API Berbilang Modal
+### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)
-| Ciri | Apa yang Dilakukan |
-| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 🖼️ **Penjanaan Imej** | `/v1/images/generations` — 4 pembekal, 9+ model |
-| 📐 **Pembenaman** | `/v1/embeddings` — 6 pembekal, 9+ model |
-| 🎤 **Transkripsi Audio** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |
-| 🔊 **Teks-ke-Ucapan** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) |
-| 🛡️ **Kesederhanaan** | `/v1/moderations` — Pemeriksaan keselamatan kandungan |
-| 🔀 **Penyusunan semula** | `/v1/rerank` — Penarafan semula perkaitan dokumen |
+| 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 |
-### 🛡️ Ketahanan & Keselamatan
+### 🟢 IFLOW MODELS (Free OAuth — No Credit Card)
-| Ciri | Apa yang Dilakukan |
+| 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 |
+
+### 🟡 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) |
+
+### 🟣 GEMINI CLI (Google OAuth)
+
+| Model | Prefix | Limit | Rate Limit |
+| ------------------------ | ------ | --------------------------- | ------------- |
+| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |
+| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |
+
+### ⚫ 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
+> iFlow (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 v2.0 is built as an operational platform, not just a relay proxy.
+
+### 🆕 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 Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |
+| 🤖 **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 (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) |
+| 🤝 **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** | 9 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 combo, apply resilience profiles, reset breakers from one control surface |
+
+### 🧠 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** | 6 balancing strategies + fallback chain control |
+| 🌐 **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) |
+| 💬 **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 |
| ----------------------------------- | -------------------------------------------------------------------------------------- |
-| 🔌 **Pemutus Litar** | Auto buka/tutup setiap pembekal dengan ambang boleh dikonfigurasikan |
-| 🛡️ **Kawanan Anti Guruh** | Had kadar Mutex + semaphore untuk pembekal kunci API |
-| 🧠 **Cache Semantik** | Cache dua peringkat (tandatangan + semantik) mengurangkan kos & kependaman |
-| ⚡ **Minta Idepotency** | Tetingkap pendua 5s untuk permintaan pendua |
-| 🔒 **TLS Fingerprint Spoofing** | Pintas pengesanan bot berasaskan TLS melalui wreq-js |
+| 🔌 **Circuit Breakers** | Per-model trip/recover with threshold controls |
+| 🎯 **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** |
-| 🌐 **Penapisan IP** | Senarai kebenaran/senarai sekat untuk kawalan akses API |
-| 📊 **Had Kadar Boleh Diedit** | RPM boleh dikonfigurasikan, jurang min dan serentak maksimum pada tahap sistem |
-| 💾 **Rate Limit Persistence** | Learned limits survive restarts via SQLite with 60s debounce + 24h staleness |
-| 🔄 **Token Refresh Resilience** | Per-provider circuit breaker (5 fails→30min) + 30s timeout per attempt |
-| 🛡 **Perlindungan Titik Akhir API** | Gating pengesahan + penyekatan penyedia untuk titik akhir `/models` |
-| 🔒 **Keterlihatan Proksi** | Lencana berkod warna: 🟢 global, 🟡 pembekal, 🔵 setiap sambungan dengan paparan IP |
-| 🌐 **Konfigurasi Proksi 3 Tahap** | Konfigurasikan proksi pada peringkat global, setiap pembekal atau setiap sambungan |
+| 🌐 **IP Filtering** | Allowlist/blocklist control for exposed deployments |
+| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |
+| 🔑 **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 |
-### 📊 Kebolehlihatan & Analitis
+### 📊 Observability & Analytics
-| Ciri | Apa yang Dilakukan |
-| --------------------------------- | ------------------------------------------------------------------------------ |
-| 📝 **Minta Pembalakan** | Mod nyahpepijat dengan log permintaan/tindak balas penuh |
-| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |
-| 💾 **Log Proksi SQLite** | Log proksi berterusan bertahan dimulakan semula pelayan |
-| 📊 **Papan Pemuka Analitik** | Dikuasakan semula: kad statistik, carta penggunaan model, jadual pembekal |
-| 📈 **Penjejakan Kemajuan** | Ikut serta acara kemajuan SSE untuk penstriman |
-| 🧪 **Penilaian LLM** | Ujian set emas dengan 4 strategi perlawanan |
-| 🔍 **Minta Telemetri** | p50/p95/p99 pengagregatan kependaman + pengesanan X-Request-Id |
-| 📋 **Papan Pemuka Log** | Halaman 4 tab bersatu: Log Permintaan, Log Proksi, Log Audit, Konsol |
-| 🖥️ **Pemapar Log Konsol** | Pemapar gaya terminal masa nyata dengan penapis tahap, carian, tatal automatik |
-| 📑 **Pengelogan Berasaskan Fail** | Pemintas konsol menangkap semua output ke fail log JSON dengan putaran |
-| 🏥 **Papan Pemuka Kesihatan** | Masa beroperasi sistem, keadaan pemutus litar, sekatan keluar, statistik cache |
-| 💰 **Penjejakan Kos** | Pengurusan belanjawan + konfigurasi harga setiap model |
+| Feature | What It Does |
+| -------------------------------- | ----------------------------------------------------- |
+| 📝 **Request + Proxy Logging** | Full request/response and proxy logging |
+| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |
+| 📋 **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 |
-### ☁️ Penyerahan & Penyegerakan
+### ☁️ Deployment & Platform
-| Ciri | Apa yang Dilakukan |
-| ----------------------------- | ----------------------------------------------------------------------- |
-| 💾 **Penyegerakan Awan** | Segerakkan konfigurasi merentas peranti melalui Cloudflare Workers |
-| 🌐 **Kerahkan Di Mana-mana** | Localhost, VPS, Docker, Pekerja Cloudflare |
-| 🔑 **Pengurusan Kunci API** | Jana, putar dan skop kunci API bagi setiap pembekal |
-| 🧙 **Onboarding Wizard** | Persediaan berpandu 4 langkah untuk pengguna kali pertama |
-| 🔧 **Papan Pemuka Alat CLI** | Konfigurasi satu klik Claude, Codex, Cline, OpenClaw, Kilo, Antigravity |
-| 🔄 **Sandaran DB** | Sandaran automatik, pulihkan, eksport & import untuk semua tetapan |
-| 🌐 **Pengantarabangsaan** | i18n penuh dengan next-intl — sokongan Inggeris + Portugis (Brazil) |
-| 🌍 **Pemilih Bahasa** | Ikon glob dalam pengepala untuk penukaran bahasa masa nyata (🇺🇸/🇧🇷) |
-| 🧹 **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 |
-| 📂 **Direktori Data Tersuai** | `DATA_DIR` env var untuk mengatasi laluan storan lalai `~/.omniroute` |
+| Feature | What It Does |
+| ----------------------------- | --------------------------------------------------------- |
+| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |
+| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |
+| 💾 **Cloud Sync** | Configuration sync via cloud worker |
+| 🔄 **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 |
+
+### Feature Deep Dive
+
+#### Smart fallback with practical cost control
+
+```txt
+Combo: "my-coding-stack"
+ 1. cc/claude-opus-4-6
+ 2. nvidia/llama-3.3-70b
+ 3. glm/glm-4.7
+ 4. if/kimi-k2-thinking
+```
+
+When quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.
+
+#### 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)
+
+#### 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)
🚀 30. "Saya perlu menghantar aliran kerja ejentik tanpa sebaran kod gam"
+🚀 30. "I need to ship agentic workflows without glue-code sprawl"
-Pasukan kehilangan halaju apabila mencantumkan berbilang perkhidmatan dan skrip ad-hoc. +Teams lose velocity when stitching multiple ad-hoc services and scripts. -**Cara OmniRoute menyelesaikannya:** +**How OmniRoute solves it:** -- Strategi titik akhir bersatu untuk pelanggan dan ejen -- UI pengurusan protokol terbina dalam dan laluan pengesahan asap -- Asas sedia pengeluaran (keselamatan, pembalakan, daya tahan, sandaran) +- Unified endpoint strategy for clients and agents +- Built-in protocol management UIs and smoke validation paths +- Production-ready foundations (security, logging, resilience, backup)
-` blok → `reasoning_content` untuk model pemikiran
-- **Output berstruktur** — `json_schema` → Gemini's `responseMimeType`/`responseSchema`
-
-### 👥 Sokongan Berbilang Akaun
-
-- Tambah berbilang akaun bagi setiap pembekal
-- Auto round-robin atau penghalaan berasaskan keutamaan
-- Berundur ke akaun seterusnya apabila seseorang mencapai kuota
-
-### 🔄 Muat Semula Token Auto
-
-- Token OAuth dimuat semula secara automatik sebelum tamat tempoh
-- Tiada pengesahan semula manual diperlukan
-- Pengalaman lancar merentas semua pembekal
-
-### 🎨 Kombo Tersuai
-
-- Buat kombinasi model tanpa had
-- 6 strategi: isikan dahulu, round-robin, kuasa dua pilihan, rawak, paling kurang digunakan, dioptimumkan kos
-- Kongsi gabungan merentas peranti dengan Cloud Sync
-
-### 🏥 Papan Pemuka Kesihatan
-
-- Status sistem (masa hidup, versi, penggunaan memori)
-- Keadaan pemutus litar bagi setiap pembekal (Tertutup/Terbuka/Separuh Terbuka)
-- Status had kadar dan sekatan aktif
-- Statistik cache tandatangan
-- Telemetri kependaman (p50/p95/p99) + cache segera
-- Tetapkan semula status kesihatan dengan satu klik
-
-### 🔧 Taman Permainan Penterjemah
-
-OmniRoute termasuk Taman Permainan Penterjemah terbina dalam yang berkuasa dengan **4 mod** untuk penyahpepijatan, ujian dan pemantauan terjemahan API:
-
-| Mod | Penerangan |
-| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **💻 Taman permainan** | Terjemahan format langsung — tampal mana-mana badan permintaan API dan lihat serta-merta cara OmniRoute menterjemahkannya antara format pembekal (OpenAI ↔ Claude ↔ Gemini ↔ Responses API). Termasuk templat contoh dan pengesanan automatik format. |
-| **💬 Penguji Sembang** | Hantar permintaan sembang sebenar melalui OmniRoute dan lihat perjalanan pergi balik penuh: input anda, permintaan yang diterjemahkan, respons pembekal dan balasan yang diterjemahkan kembali. Tidak ternilai untuk mengesahkan penghalaan kombo. |
-| **🧪 Bangku Ujian** | Mod ujian kelompok — tentukan berbilang kes ujian dengan input dan output yang dijangkakan berbeza, jalankan semuanya sekali gus dan bandingkan hasil merentas pembekal dan model. |
-| **📱 Pemantau Langsung** | Pemantauan permintaan masa nyata — tonton permintaan masuk semasa ia mengalir melalui OmniRoute, lihat terjemahan format berlaku secara langsung dan kenal pasti isu serta-merta. |
-
-**Akses:** Papan Pemuka → Penterjemah (bar sisi)
-
-### 💾 Penyegerakan Awan
-
-- Penyegerakan penyedia, gabungan dan tetapan merentas peranti
-- Penyegerakan latar belakang automatik
-- Storan yang disulitkan selamat
+- `GET /api/mcp/status`
+- `GET /api/mcp/tools`
+- `GET /api/mcp/audit`
+- `GET /api/mcp/audit/stats`
-## 🧪 Penilaian (Evals)
+📖 Butiran Ciri
+🧩 MCP Setup (Model Context Protocol)
-### 🎯 Kemunduran 4 Peringkat Pintar +Start MCP transport in stdio mode: -Cipta gabungan dengan sandaran automatik: - -``` -Combo: "my-coding-stack" - 1. cc/claude-opus-4-6 (your subscription) - 2. nvidia/llama-3.3-70b (free NVIDIA API) - 3. glm/glm-4.7 (cheap backup, $0.6/1M) - 4. if/kimi-k2-thinking (free fallback) - -→ Auto switches when quota runs out or errors occur +```bash +omniroute --mcp ``` -### 📊 Penjejakan Kuota Masa Nyata +Recommended validation flow: -- Penggunaan token setiap pembekal -- Tetapkan semula kira detik (5 jam, harian, mingguan) -- Anggaran kos untuk peringkat berbayar -- Laporan perbelanjaan bulanan +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. -### 🔄 Terjemahan Format +Useful APIs for automation: -Terjemahan lancar antara format: - -- **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **Respons OpenAI** -- Alat CLI anda menghantar format OpenAI → OmniRoute menterjemah → Pembekal menerima format asli -- Berfungsi dengan mana-mana alat yang menyokong titik akhir OpenAI tersuai -- **Pembersihan tindak balas** — Menghapuskan medan bukan standard untuk keserasian OpenAI SDK yang ketat -- **Penormalan peranan** — `developer` → `system` untuk bukan OpenAI; `system` → `user` untuk model GLM/ERNIE -- **Pengekstrakan teg Think** — `
+
🤝 A2A Setup (Agent2Agent)
-OmniRoute termasuk rangka kerja penilaian terbina dalam untuk menguji kualiti tindak balas LLM terhadap set emas. Aksesnya melalui **Analytics → Evals** dalam papan pemuka. +Discover the agent: -### Set Emas Terbina dalam +```bash +curl http://localhost:20128/.well-known/agent.json +``` -"Set Emas OmniRoute" pra-muat mengandungi 10 kes ujian yang meliputi: +Send a task: -- Salam, matematik, geografi, penjanaan kod -- Pematuhan format JSON, terjemahan, penurunan harga -- Penolakan keselamatan (kandungan berbahaya), pengiraan, logik boolean +```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."}]}}' +``` -### Strategi Penilaian +Manage lifecycle: -| Strategi | Penerangan | Contoh | -| ---------- | --------------------------------------------------------------------- | -------------------------------- | -| `exact` | Output mesti sepadan dengan tepat | `"4"` | -| `contains` | Output mesti mengandungi subrentetan (tidak peka huruf besar-besaran) | `"Paris"` | -| `regex` | Output mesti sepadan dengan corak regex | `"1.*2.*3"` | -| `custom` | Fungsi JS tersuai mengembalikan benar/salah | `(output) => output.length > 10` | +- `GET /api/a2a/status` +- `GET /api/a2a/tasks` +- `GET /api/a2a/tasks/:id` +- `POST /api/a2a/tasks/:id/cancel` ---- +Operational UI: -## 📖 Panduan Persediaan +- `/dashboard/a2a` for task/state/stream observability and smoke actions + +
-
+
+💳 Pembekal Langganan
+🧪 End-to-end protocol validation
-### Kod Claude (Pro/Max) +Validate both protocols with real clients: + +```bash +npm run test:protocols:e2e +``` + +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) ```bash Dashboard → Providers → Connect Claude Code @@ -1066,7 +1438,7 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Petua Pro:** Gunakan Opus untuk tugas yang rumit, Sonnet untuk kelajuan. OmniRoute menjejaki kuota setiap model! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! ### OpenAI Codex (Plus/Pro) @@ -1080,7 +1452,24 @@ Models: cx/gpt-5.1-codex-max ``` -### Gemini CLI (PERCUMA 180K/bulan!) +#### 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). + +### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -1092,9 +1481,9 @@ Models: gc/gemini-2.5-pro ``` -**Nilai Terbaik:** Peringkat percuma yang besar! Gunakan ini sebelum peringkat berbayar. +**Best Value:** Huge free tier! Use this before paid tiers. -### Copilot GitHub +### GitHub Copilot ```bash Dashboard → Providers → Connect GitHub @@ -1110,88 +1499,88 @@ Models:
-
🔑 Pembekal Kunci API
+🔑 API Key Providers
-### NVIDIA NIM (PERCUMA 1000 kredit!) +### NVIDIA NIM (FREE developer access — 70+ models) -1. Daftar: [build.nvidia.com](https://build.nvidia.com) -2. Dapatkan kunci API percuma (1000 kredit inferens disertakan) -3. Papan Pemuka → Tambah Pembekal → NVIDIA NIM: - - Kunci API: `nvapi-your-key` +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` -**Model:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct` dan 50+ lagi +**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more -**Petua Pro:** API serasi OpenAI — berfungsi dengan lancar dengan terjemahan format OmniRoute! +**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation! ### DeepSeek -1. Daftar: [platform.deepseek.com](https://platform.deepseek.com) -2. Dapatkan kunci API -3. Papan Pemuka → Tambah Pembekal → DeepSeek +1. Sign up: [platform.deepseek.com](https://platform.deepseek.com) +2. Get API key +3. Dashboard → Add Provider → DeepSeek -**Model:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` +**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` -### Groq (Tier Percuma Tersedia!) +### Groq (Free Tier Available!) -1. Daftar: [console.groq.com](https://console.groq.com) -2. Dapatkan kunci API (termasuk peringkat percuma) -3. Papan Pemuka → Tambah Pembekal → Groq +1. Sign up: [console.groq.com](https://console.groq.com) +2. Get API key (free tier included) +3. Dashboard → Add Provider → Groq -**Model:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` +**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` -**Petua Pro:** Inferens sangat pantas — terbaik untuk pengekodan masa nyata! +**Pro Tip:** Ultra-fast inference — best for real-time coding! -### OpenRouter (100+ Model) +### OpenRouter (100+ Models) -1. Daftar: [openrouter.ai](https://openrouter.ai) -2. Dapatkan kunci API -3. Papan Pemuka → Tambah Pembekal → OpenRouter +1. Sign up: [openrouter.ai](https://openrouter.ai) +2. Get API key +3. Dashboard → Add Provider → OpenRouter -**Model:** Akses 100+ model daripada semua pembekal utama melalui kunci API tunggal. +**Models:** Access 100+ models from all major providers through a single API key.
-
💰 Penyedia Murah (Sandaran)
+💰 Cheap Providers (Backup)
-### GLM-4.7 (Tetapan semula harian, $0.6/1J) +### GLM-4.7 (Daily reset, $0.6/1M) -1. Daftar: [Zhipu AI](https://open.bigmodel.cn/) -2. Dapatkan kunci API daripada Pelan Pengekodan -3. Papan Pemuka → Tambah Kunci API: - - Pembekal: `glm` - - Kunci API: `your-key` +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` -**Gunakan:** `glm/glm-4.7` +**Use:** `glm/glm-4.7` -**Petua Pro:** Pelan Pengekodan menawarkan kuota 3× pada kos 1/7! Tetapkan semula setiap hari 10:00 AM. +**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -### MiniMax M2.1 (tetapan semula 5j, $0.20/1J) +### MiniMax M2.1 (5h reset, $0.20/1M) -1. Daftar: [MiniMax](https://www.minimax.io/) -2. Dapatkan kunci API -3. Papan Pemuka → Tambah Kunci API +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key +3. Dashboard → Add API Key -**Gunakan:** `minimax/MiniMax-M2.1` +**Use:** `minimax/MiniMax-M2.1` -**Petua Pro:** Pilihan termurah untuk konteks panjang (token 1M)! +**Pro Tip:** Cheapest option for long context (1M tokens)! -### Kimi K2 ($9/bulan rata) +### Kimi K2 ($9/month flat) -1. Langgan: [Moonshot AI](https://platform.moonshot.ai/) -2. Dapatkan kunci API -3. Papan Pemuka → Tambah Kunci API +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key +3. Dashboard → Add API Key -**Gunakan:** `kimi/kimi-latest` +**Use:** `kimi/kimi-latest` -**Petua Pro:** Tetap $9/bulan untuk 10J token = $0.90/1J kos efektif! +**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
-
🆓 Pembekal PERCUMA (Sandaran Kecemasan)
+🆓 FREE Providers (Emergency Backup)
-### iFlow (8 model PERCUMA) +### iFlow (5 FREE models via OAuth) ```bash Dashboard → Connect iFlow @@ -1206,7 +1595,7 @@ Models: if/deepseek-r1 ``` -### Qwen (3 model PERCUMA) +### Qwen (4 FREE models via Device Code) ```bash Dashboard → Connect Qwen @@ -1218,7 +1607,7 @@ Models: qw/qwen3-coder-flash ``` -### Kiro (Claude PERCUMA) +### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro @@ -1233,9 +1622,9 @@ Models:
-
🎨 Cipta Kombo
+🎨 Create Combos
-### Contoh 1: Maksimumkan Langganan → Sandaran Murah +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -1249,7 +1638,7 @@ Models: Use in CLI: premium-coding ``` -### Contoh 2: Percuma-Sahaja (Kos Sifar) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -1264,9 +1653,9 @@ Cost: $0 forever!
-
---
-## 🐛 Menyelesaikan masalah
+## Penyelesaian Masalah
🔧 CLI Integrasi
+🔧 CLI Integration
-### IDE Kursor +### Cursor IDE ``` Settings → Models → Advanced: @@ -1275,9 +1664,9 @@ Settings → Models → Advanced: Model: cc/claude-opus-4-6 ``` -### Kod Claude +### Claude Code -Gunakan halaman **Alat CLI** dalam papan pemuka untuk konfigurasi satu klik atau edit `~/.claude/settings.json` secara manual. +Use the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually. ### Codex CLI @@ -1290,13 +1679,13 @@ codex "your prompt" ### OpenClaw -**Pilihan 1 — Papan Pemuka (disyorkan):** +**Option 1 — Dashboard (recommended):** ``` Dashboard → CLI Tools → OpenClaw → Select Model → Apply ``` -**Pilihan 2 — Manual:** Edit `~/.openclaw/openclaw.json`: +**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`: ```json { @@ -1312,9 +1701,9 @@ Dashboard → CLI Tools → OpenClaw → Select Model → Apply } ``` -> **Nota:** OpenClaw hanya berfungsi dengan OmniRoute tempatan. Gunakan `127.0.0.1` dan bukannya `localhost` untuk mengelakkan isu resolusi IPv6. +> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues. -### Cline / Teruskan / RooCode +### Cline / Continue / RooCode ``` Settings → API Configuration: @@ -1324,108 +1713,243 @@ Settings → API Configuration: 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. +
-
-- **Waktu Jalan**: Node.js 18–22 LTS (⚠️ Node.js 24+ **tidak disokong** — `better-sqlite3` binari asli tidak serasi)
-- **Bahasa**: TypeScript 5.9 — **100% TypeScript** merentas `src/` dan `open-sse/` (v1.0.6)
-- **Kerangka**: Next.js 16 + React 19 + Tailwind CSS 4
-- **Pangkalan Data**: LowDB (JSON) + SQLite (keadaan domain + log proksi)
-- **Penstriman**: Acara Dihantar Pelayan (SSE)
-- **Auth**: OAuth 2.0 (PKCE) + JWT + Kunci API
-- **Ujian**: Pelari ujian Node.js (368+ ujian unit)
-- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub pada keluaran)
-- **Laman web**: [omniroute.online](https://omniroute.online)
-- **Pakej**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
-- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
-- **Ketahanan**: Pemutus litar, mundur eksponen, kumpulan anti gemuruh, penipuan TLS
-
----
-
-## 📖 Dokumentasi
-
-| Dokumen | Penerangan |
-| -------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Pembekal, kombo, penyepaduan CLI, penggunaan |
-| [API Reference](docs/API_REFERENCE.md) | Semua titik akhir dengan contoh |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Masalah dan penyelesaian biasa |
-| [Architecture](docs/ARCHITECTURE.md) | Seni bina sistem dan dalaman |
-| [Contributing](CONTRIBUTING.md) | Persediaan pembangunan dan garis panduan |
-| [OpenAPI Spec](docs/openapi.yaml) | Spesifikasi OpenAPI 3.0 |
-| [Security Policy](SECURITY.md) | Pelaporan kerentanan dan amalan keselamatan |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Panduan lengkap: Persediaan VM + nginx + Cloudflare |
-| [Features Gallery](docs/FEATURES.md) | Lawatan papan pemuka visual dengan tangkapan skrin |
-
-### 📸 Pratonton Papan Pemuka
+## 🛠️ Tech Stack
Klik untuk mengembangkan panduan penyelesaian masalah
+Click to expand troubleshooting guide
-**"Model bahasa tidak memberikan mesej"** +**"Language model did not provide messages"** -- Kuota pembekal habis → Semak penjejak kuota papan pemuka -- Penyelesaian: Gunakan sandaran kombo atau tukar kepada peringkat yang lebih murah +- Provider quota exhausted → Check dashboard quota tracker +- Solution: Use combo fallback or switch to cheaper tier -**Penghadan kadar** +**Rate limiting** -- Kuota langganan habis → Sandar kepada GLM/MiniMax -- Tambah kombo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Subscription quota out → Fallback to GLM/MiniMax +- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -**Token OAuth tamat tempoh** +**OAuth token expired** -- Dikemas semula secara automatik oleh OmniRoute -- Jika isu berterusan: Papan Pemuka → Pembekal → Sambung semula +- Auto-refreshed by OmniRoute +- If issues persist: Dashboard → Provider → Reconnect -**Kos tinggi** +**High costs** -- Semak statistik penggunaan dalam Papan Pemuka → Kos -- Tukar model utama kepada GLM/MiniMax -- Gunakan peringkat percuma (Gemini CLI, iFlow) untuk tugasan yang tidak kritikal +- Check usage stats in Dashboard → Costs +- Switch primary model to GLM/MiniMax +- Use free tier (Gemini CLI, iFlow) for non-critical tasks -**Papan pemuka dibuka pada port yang salah** +**Dashboard/API ports are wrong** -- Tetapkan `PORT=20128` dan `NEXT_PUBLIC_BASE_URL=http://localhost:20128` +- `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) -**Ralat penyegerakan awan** +**Cloud sync errors** -- Sahkan `BASE_URL` mata pada contoh larian anda -- Sahkan `CLOUD_URL` mata ke titik akhir awan anda yang dijangkakan -- Pastikan nilai `NEXT_PUBLIC_*` sejajar dengan nilai sebelah pelayan +- 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 -**Log masuk pertama tidak berfungsi** +**First login not working** -- Semak `INITIAL_PASSWORD` dalam `.env` -- Jika tidak ditetapkan, kata laluan sandaran ialah `123456` +- Check `INITIAL_PASSWORD` in `.env` +- If unset, fallback password is `123456` -**Tiada log permintaan** +**No request logs** -- Tetapkan `ENABLE_REQUEST_LOGS=true` dalam `.env` +- Set `ENABLE_REQUEST_LOGS=true` in `.env` -**Ujian sambungan menunjukkan "Tidak sah" untuk pembekal yang serasi dengan OpenAI** +**Connection test shows "Invalid" for OpenAI-compatible providers** -- Banyak pembekal tidak mendedahkan titik akhir `/models` -- OmniRoute v1.0.6+ termasuk pengesahan sandaran melalui pelengkapan sembang -- Pastikan URL asas mengandungi akhiran `/v1` +- 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 +### 🔐 OAuth on a Remote Server + -> **⚠️ PENTING untuk biasa menggunakan OmniRoute em VPS/Docker/servidor remoto** +> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server** -### Adakah OAuth melakukan Antigraviti / Gemini CLI tidak menggunakan perkhidmatan anda? +#### Why does Antigravity / Gemini CLI OAuth fail on remote servers? -Ia membuktikan **Antigraviti** dan **Gemini CLI** menggunakan **Google OAuth 2.0** untuk autenticação. O Google exige que a `redirect_uri` gunakan tiada fluks OAuth seja **exatamente** uma das URIs sebelum kadastrada tiada Google Cloud Console untuk aplicativo. +The **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console. -Sebagai credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas untuk `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (cth: `https://omniroute.meuservidor.com`), o Google rejeita a autenticação com: +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 ``` -### Penyelesaian: Konfigurasikan suas próprias credenciais OAuth +#### 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 + +# For Gemini CLI: +GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com +GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +``` + +**6. Restart OmniRoute** + +```bash +# npm: +npm run dev + +# Docker: +docker restart omniroute +``` + +**7. Try connecting again** + +Dashboard → Providers → Antigravity (or Gemini CLI) → OAuth + +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. + +--- + +
+
---
-## 🛠️
+🇧🇷 Versão em Português
+ +#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos? + +Os provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo. + +As credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticação com: + +``` +Error 400: redirect_uri_mismatch +``` + +#### Solução: Configure suas próprias credenciais OAuth Você precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor. #### Passo a passo -**1. Akses ke Konsol Awan Google** +**1. Acesse o Google Cloud Console** Abra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) -**2. Crie um novo ID Pelanggan OAuth 2.0** +**2. Crie um novo OAuth 2.0 Client ID** -- Klik em **"+ Cipta Bukti Kelayakan"** → **"ID klien OAuth"** -- Tipo de aplicativo: **"Aplikasi web"** -- Nama: escolha qualquer nome (cth: `OmniRoute Remote`) +- Clique em **"+ Create Credentials"** → **"OAuth client ID"** +- Tipo de aplicativo: **"Web application"** +- Nome: escolha qualquer nome (ex: `OmniRoute Remote`) -**3. Tambah sebagai URI Ubah Hala Dibenarkan** +**3. Adicione as Authorized Redirect URIs** -Tiada **"URI ubah hala yang dibenarkan"**, tambahan: +No campo **"Authorized redirect URIs"**, adicione: ``` https://seu-servidor.com/callback ``` -> Gantikan `seu-servidor.com` pelo domínio ou IP do seu servidor (termasuk porta se necessário, cth: `http://45.33.32.156:20128/callback`). +> Substitua `seu-servidor.com` pelo domínio ou IP do seu servidor (inclua a porta se necessário, ex: `http://45.33.32.156:20128/callback`). -**4. Simpan dan salin sebagai kredensia** +**4. Salve e copie as credenciais** -Após criar, o Google mostrará o **ID Pelanggan** e o **Rahsia Pelanggan**. +Após criar, o Google mostrará o **Client ID** e o **Client Secret**. -**5. Konfigurasikan sebagai variáveis de ambiente** +**5. Configure as variáveis de ambiente** No seu `.env` (ou nas variáveis de ambiente do Docker): @@ -1452,151 +1976,145 @@ docker restart omniroute **7. Tente conectar novamente** -Papan pemuka → Pembekal → Antigraviti (ou Gemini CLI) → OAuth +Dashboard → Providers → Antigravity (ou Gemini CLI) → OAuth -Agora o Google redirectionará corretamente untuk `https://seu-servidor.com/callback` dan a autenticação funcionará. +Agora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará. --- -### Penyelesaian sementara (sem configurar credenciais próprias) +#### Workaround temporário (sem configurar credenciais próprias) -Jika anda ingin mendapatkan credenciais próprias agora, ada kemungkinan penggunaan atau fluks **manual de URL**: +Se não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**: -1. OmniRoute abrirá a URL de authorização do Google -2. Após você authorizar, o Google tentará redirectionar para `localhost` (que falha no servidor remoto) -3. **Salin URL lengkap** pada penyemak imbas barra de endereço do seu (mesmo que a página não carregue) +1. O OmniRoute abrirá a URL de autorização do Google +2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto) +3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue) 4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute -5. Klik em **"Sambung"** +5. Clique em **"Connect"** -> Penyelesaian ini berfungsi sebagai kodigo de autorização na URL adalah bebas untuk mengubah hala mengikut arahan atau tidak. +> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.
-
---
-## 🗺️
+## Dokumentasi
-OmniRoute mempunyai **210+ ciri yang dirancang** merentas berbilang fasa pembangunan. Berikut adalah bidang utama:
-
-| Kategori | Ciri Terancang | Sorotan |
-| ------------------------------ | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
-| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |
-| 🧠 **Penghalaan & Perisikan** | 25+ | Penghalaan kependaman terendah, penghalaan berasaskan teg, kuota prapenerbangan, pemilihan akaun P2C |
-| 🔒 **Keselamatan & Pematuhan** | 20+ | Pengerasan SSRF, penyelubungan kelayakan, had kadar setiap titik akhir, skop kunci pengurusan |
-| 📊 **Kebolehlihatan** | 15+ | Penyepaduan OpenTelemetry, pemantauan kuota masa nyata, penjejakan kos setiap model |
-| 🔄 **Integrasi Pembekal** | 20+ | Pendaftaran model dinamik, penyejukan pembekal, Codex berbilang akaun, penghuraian kuota Copilot |
-| ⚡ **Prestasi** | 15+ | Lapisan cache dwi, cache gesaan, cache respons, penstriman keepalive, API kelompok |
-| 🌐 **Ekosistem** | 10+ | API WebSocket, konfigurasi hot-reload, kedai konfigurasi teragih, mod komersial |
-
-### 🔜 Akan Datang
-
-- 🔗 **OpenCode Integration** — Sokongan pembekal asli untuk IDE pengekodan AI OpenCode
-- 🔗 **Pengintegrasian TRAE** — Sokongan penuh untuk rangka kerja pembangunan TRAE AI
-- 📦 **API Kelompok** — Pemprosesan kelompok tak segerak untuk permintaan pukal
-- 🎯 **Penghalaan Berasaskan Teg** — Permintaan laluan berdasarkan teg tersuai dan metadata
-- 💰 **Strategi Kos Terendah** — Pilih pembekal yang tersedia paling murah secara automatik
-
-> 📝 Spesifikasi ciri penuh tersedia dalam [link](docs/new-features/) (217 spesifikasi terperinci)
+| Document | Description |
+| ---------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 16 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/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
+| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
-## 👥 Penyumbang
+## 🗺️ Roadmap
+
+OmniRoute has **210+ 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, P2C account selection |
+| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |
+| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |
+| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider 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
[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
-### Cara Menyumbang
+### How to Contribute
-1. Garpu repositori
-2. Buat cawangan ciri anda (`git checkout -b feature/amazing-feature`)
-3. Serahkan perubahan anda (`git commit -m 'Add amazing feature'`)
-4. Tolak ke cawangan (`git push origin feature/amazing-feature`)
-5. Buka Permintaan Tarik
+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
-Lihat [CONTRIBUTING.md](CONTRIBUTING.md) untuk garis panduan terperinci.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
-### Mengeluarkan Versi Baharu
+### Releasing a New Version
```bash
# Create a release — npm publish happens automatically
-gh release create v1.0.6 --title "v1.0.6" --generate-notes
+gh release create v2.0.0 --title "v2.0.0" --generate-notes
```
---
-## 📊 Sejarah Bintang
+## 📊 Star History
## Stargazers over time
## [](https://starchart.cc/diegosouzapw/OmniRoute)
-## 🙏 Ucapan terima kasih
+## 🙏 Acknowledgments
-Terima kasih khas kepada **[9router](https://github.com/decolua/9router)** oleh **[decolua](https://github.com/decolua)** — projek asal yang mengilhamkan garpu ini. OmniRoute membina asas yang luar biasa itu dengan ciri tambahan, API berbilang modal dan penulisan semula TypeScript penuh.
+Special thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.
-Terima kasih khas kepada **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — pelaksanaan Go asal yang mengilhamkan port JavaScript ini.
+Special thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.
---
-## 📄 Lesen
+## Lesen
-Lesen MIT - lihat [LICENSE](LICENSE) untuk butiran.
+MIT License - see [LICENSE](LICENSE) for details.
---
Klik untuk melihat tangkapan skrin papan pemuka
+Click to expand tech stack details
-| Halaman | Tangkapan skrin | -| ------------------ | ------------------------------------------------- | -| **Pembekal** |  | -| **Kombo** |  | -| **Analisis** |  | -| **Kesihatan** |  | -| **Penterjemah** |  | -| **Tetapan** |  | -| **Alat CLI** |  | -| **Log Penggunaan** |  | -| **Titik Akhir** |  | +- **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**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions) +- **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
- Dibina dengan ❤️ untuk pembangun yang kod 24/7
+ Built with ❤️ for developers who code 24/7
omniroute.online
+
diff --git a/docs/i18n/ms/docs/FEATURES.md b/docs/i18n/ms/docs/FEATURES.md
new file mode 100644
index 0000000000..343035644b
--- /dev/null
+++ b/docs/i18n/ms/docs/FEATURES.md
@@ -0,0 +1,145 @@
+# OmniRoute — Dashboard Features Gallery (Bahasa Melayu)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/FEATURES.md) · 🇪🇸 [es](../../es/docs/FEATURES.md) · 🇫🇷 [fr](../../fr/docs/FEATURES.md) · 🇩🇪 [de](../../de/docs/FEATURES.md) · 🇮🇹 [it](../../it/docs/FEATURES.md) · 🇷🇺 [ru](../../ru/docs/FEATURES.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FEATURES.md) · 🇯🇵 [ja](../../ja/docs/FEATURES.md) · 🇰🇷 [ko](../../ko/docs/FEATURES.md) · 🇸🇦 [ar](../../ar/docs/FEATURES.md) · 🇮🇳 [in](../../in/docs/FEATURES.md) · 🇹🇭 [th](../../th/docs/FEATURES.md) · 🇻🇳 [vi](../../vi/docs/FEATURES.md) · 🇮🇩 [id](../../id/docs/FEATURES.md) · 🇲🇾 [ms](../../ms/docs/FEATURES.md) · 🇳🇱 [nl](../../nl/docs/FEATURES.md) · 🇵🇱 [pl](../../pl/docs/FEATURES.md) · 🇸🇪 [sv](../../sv/docs/FEATURES.md) · 🇳🇴 [no](../../no/docs/FEATURES.md) · 🇩🇰 [da](../../da/docs/FEATURES.md) · 🇫🇮 [fi](../../fi/docs/FEATURES.md) · 🇵🇹 [pt](../../pt/docs/FEATURES.md) · 🇷🇴 [ro](../../ro/docs/FEATURES.md) · 🇭🇺 [hu](../../hu/docs/FEATURES.md) · 🇧🇬 [bg](../../bg/docs/FEATURES.md) · 🇸🇰 [sk](../../sk/docs/FEATURES.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FEATURES.md) · 🇮🇱 [he](../../he/docs/FEATURES.md) · 🇵🇭 [phi](../../phi/docs/FEATURES.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FEATURES.md)
+
+---
+
+Visual guide to every section of the OmniRoute dashboard.
+
+---
+
+## 🔌 Providers
+
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
+
+
+
+---
+
+## 🎨 Combos
+
+Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
+
+
+
+---
+
+## 📊 Analytics
+
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
+
+
+
+---
+
+## 🏥 System Health
+
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+
+
+
+---
+
+## 🔧 Translator Playground
+
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
+
+
+
+---
+
+## 🎮 Model Playground _(v2.0.9+)_
+
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
+
+---
+
+## 🎨 Themes _(v2.0.5+)_
+
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
+
+## ⚙️ Settings
+
+Comprehensive settings panel with tabs:
+
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning
+- **Advanced** — Configuration overrides
+
+
+
+---
+
+## 🔧 CLI Tools
+
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
+
+
+
+---
+
+## 🤖 CLI Agents _(v2.0.11+)_
+
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
+
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
+
+---
+
+## 🖼️ Media _(v2.0.3+)_
+
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
+
+## 📝 Request Logs
+
+Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
+
+
+
+---
+
+## 🌐 API Endpoint
+
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
+
+
+
+---
+
+## 🔑 API Key Management
+
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
+
+---
+
+## 📋 Audit Log
+
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
+
+---
+
+## 🖥️ Desktop Application
+
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
+
+Key features:
+
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
+
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.
diff --git a/docs/i18n/nl/README.md b/docs/i18n/nl/README.md
index 81456f9c35..37a098d557 100644
--- a/docs/i18n/nl/README.md
+++ b/docs/i18n/nl/README.md
@@ -1,24 +1,94 @@
-omniroute.online
-
-
- # 🚀 OmniRoute — De gratis AI-gateway
+# 🚀 OmniRoute — The Free AI Gateway (Nederlands)
-### Stop nooit met coderen. Slimme routering naar **GRATIS en voordelige AI-modellen** met automatische terugval.
-
-_Uw universele API-proxy: één eindpunt, meer dan 36 providers, geen downtime._
-
-**Chatvoltooiingen • Insluitingen • Afbeelding genereren • Audio • Herrangschikking • 100% TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Gratis AI-provider voor uw favoriete codeeragenten
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Verbind elke AI-aangedreven IDE- of CLI-tool via OmniRoute: gratis API-gateway voor onbeperkte codering._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+` tags no longer leak to clients in SSE streaming responses (#585) |
+| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with per-provider/account quota enforcement, idempotency, SHA-256 storage, and optional GitHub issue reporting |
+| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG → generic fallback chain |
+| 🔄 **Model Auto-Sync** | 24h scheduler and manual UI toggle to sync model lists for built-in and custom OpenAI-compatible providers |
+| 🌐 **OpenCode Zen/Go** | Two new providers from @kang-heewon via PR #530: free tier + subscription tier via `OpencodeExecutor` |
+| 🐛 **Gemini CLI OAuth** | Actionable error when `GEMINI_OAUTH_CLIENT_SECRET` is missing in Docker (was cryptic Google error) |
+| 🐛 **OpenCode config** | `saveOpenCodeConfig()` now correctly writes TOML to `XDG_CONFIG_HOME` |
+| 🐛 **Pinned model override** | `body.model` correctly set to `pinnedModel` on context-cache protection |
+| 🐛 **Codex/Claude loop** | `tool_result` blocks now converted to text to stop infinite loops |
+| 🐛 **Login redirect** | Login no longer freezes after skipping password setup |
+| 🐛 **Windows paths** | MSYS2/Git-Bash paths (`/c/...`) normalized to `C:\...` automatically |
+
+---
+
+## 🖼️ Main Dashboard
+
+
-📡 Alle agenten maken verbinding via ` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**Stop wasting money and hitting limits:**
-### 🆕 What's New in v3.0.0
+- Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**OmniRoute solves this:**
+
+- ✅ **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
+- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool
---
-[](https://www.npmjs.com/package/omniroute)
-[](https://hub.docker.com/r/diegosouzapw/omniroute)
-[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
-[](https://omniroute.online)
-[](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
+## 📧 Support
-[🌐 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)
-
-🌐 **Available in:** 🇺🇸 [English](../../README.md) | 🇧🇷 [Português (Brasil)](../pt-BR/README.md) | 🇪🇸 [Español](../es/README.md) | 🇫🇷 [Français](../fr/README.md) | 🇮🇹 [Italiano](../it/README.md) | 🇷🇺 [Русский](../ru/README.md) | 🇨🇳 [中文 (简体)](../zh-CN/README.md) | 🇩🇪 [Deutsch](../de/README.md) | 🇮🇳 [हिन्दी](../in/README.md) | 🇹🇭 [ไทย](../th/README.md) | 🇺🇦 [Українська](../uk-UA/README.md) | 🇸🇦 [العربية](../ar/README.md) | 🇯🇵 [日本語](../ja/README.md) | 🇻🇳 [Tiếng Việt](../vi/README.md) | 🇧🇬 [Български](../bg/README.md) | 🇩🇰 [Dansk](../da/README.md) | 🇫🇮 [Suomi](../fi/README.md) | 🇮🇱 [עברית](../he/README.md) | 🇭🇺 [Magyar](../hu/README.md) | 🇮🇩 [Bahasa Indonesia](../id/README.md) | 🇰🇷 [한국어](../ko/README.md) | 🇲🇾 [Bahasa Melayu](../ms/README.md) | 🇳🇱 [Nederlands](../nl/README.md) | 🇳🇴 [Norsk](../no/README.md) | 🇵🇹 [Português (Portugal)](../pt/README.md) | 🇷🇴 [Română](../ro/README.md) | 🇵🇱 [Polski](../pl/README.md) | 🇸🇰 [Slovenčina](../sk/README.md) | 🇸🇪 [Svenska](../sv/README.md) | 🇵🇭 [Filipino](../phi/README.md)
-
-
-
----
-
-## 🖼️
-
-
-
- # 🚀 OmniRoute — De gratis AI-gateway
+# 🚀 OmniRoute — The Free AI Gateway (Nederlands)
-### Stop nooit met coderen. Slimme routering naar **GRATIS en voordelige AI-modellen** met automatische terugval.
-
-_Uw universele API-proxy: één eindpunt, meer dan 36 providers, geen downtime._
-
-**Chatvoltooiingen • Insluitingen • Afbeelding genereren • Audio • Herrangschikking • 100% TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Gratis AI-provider voor uw favoriete codeeragenten
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Verbind elke AI-aangedreven IDE- of CLI-tool via OmniRoute: gratis API-gateway voor onbeperkte codering._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+
+
+[](https://www.npmjs.com/package/omniroute)
+[](https://www.npmjs.com/package/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
+[](https://omniroute.online)
+[](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)
+
+
+
+🌐 **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)
+
+---
+
+## 🆕 What's New in v3.0.0
+
+> **Upgrading from v2.9.5?** — See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes.
+
+| Area | Change |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection remediation |
+| ✅ **Route Validation** | All 176 API routes now validated with Zod schemas + `validateBody()` — CI `check:route-validation:t06` passes |
+| 🐛 **omniModel Tag Leak** | Internal `
+
+
+
+---
+
+## 📸 Dashboard Preview
+
+
+
+
+
+---
+
+### 🤖 Free AI Provider for your favorite coding agents
+
+_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._
Click to see dashboard screenshots
+ +| Page | Screenshot | +| -------------- | ------------------------------------------------- | +| **Providers** |  | +| **Combos** |  | +| **Analytics** |  | +| **Health** |  | +| **Translator** |  | +| **Settings** |  | +| **CLI Tools** |  | +| **Usage Logs** |  | +| **Endpoints** |  | + +|
-
+
OpenClaw @@ -92,113 +162,52 @@ _Verbind elke AI-aangedreven IDE- of CLI-tool via OmniRoute: gratis API-gateway |
http://localhost:20128/v1 of http://cloud.omniroute.online/v1 — één configuratie, onbeperkte modellen en quota
+📡 All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 — one config, unlimited models and quota
---
-### 🆕 What's New in v3.0.0
+## 🤔 Why OmniRoute?
-| Area | Change |
-| ------------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal ` Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `
-
-
-
----
-
-## 📸
-
-
-
-
-
----
-
-## 🤔 Waarom OmniRoute?
-
-**Stop met het verspillen van geld en het bereiken van grenzen:**
-
-- ...
- -| # | # | -| ----- | ---------------------------------------- | -| **1** |  | -| **2** |  | -| **3** |  | -| **4** |  | -| **5** |  | -| **6** |  | -| **7** |  | -| **8** |  | -| **9** |  | - - Het abonnementsquotum verloopt elke maand ongebruikt
-- Snelheidslimieten voorkomen dat u halverwege codeert
-- Dure API's ($20-50/maand per provider)
-- Handmatig schakelen tussen providers
-
-**OmniRoute lost dit op:**
-
-- ✅ **Maximaliseer abonnementen** - Houd quota bij, gebruik elk bit voordat u het opnieuw instelt
-- ✅ **Automatische fallback** - Abonnement → API-sleutel → Goedkoop → Gratis, geen downtime
-- ✅ **Multi-account** - Round-robin tussen accounts per provider
-- ✅ **Universeel** - Werkt met Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, elke CLI-tool
-
----
-
-## 📧 Ondersteuning
-
-> 💬 **Word lid van onze community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Krijg hulp, deel tips en blijf op de hoogte.
+> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.
- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Problemen**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Origineel project**: [9router by decolua](https://github.com/decolua/9router)
+- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 Hoe het werkt
+## 🔄 How It Works
```
┌─────────────┐
@@ -227,451 +236,453 @@ Result: Never stop coding, minimal cost
---
-## 🎯 Wat OmniRoute oplost — 30 echte pijnpunten en gebruiksscenario's
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **Elke ontwikkelaar die AI-tools gebruikt, wordt dagelijks met deze problemen geconfronteerd.** OmniRoute is gebouwd om ze allemaal op te lossen: van kostenoverschrijdingen tot regionale blokkades, van kapotte OAuth-stromen tot protocolbewerkingen en bedrijfsobservatie.
+> **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.
-
💸 1. "Ik betaal voor een duur abonnement, maar word nog steeds onderbroken door limieten"
+💸 1. "I pay for an expensive subscription but still get interrupted by limits"
-Ontwikkelaars betalen $20-200/maand voor Claude Pro, Codex Pro of GitHub Copilot. Zelfs als je betaalt, heeft het quotum een plafond: 5 uur gebruik, wekelijkse limieten of tarieflimieten per minuut. Halverwege de codeersessie reageert de provider niet meer en verliest de ontwikkelaar flow en productiviteit. +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. -**Hoe OmniRoute het oplost:** +**How OmniRoute solves it:** -- **Smart 4-Tier Fallback** — Als het abonnementsquotum opraakt, wordt automatisch doorgestuurd naar API Key → Goedkoop → Gratis zonder handmatige tussenkomst -- **Realtime bijhouden van quota** — Toont het tokenverbruik in realtime met aftellen van de reset (5 uur, dagelijks, wekelijks) -- **Ondersteuning voor meerdere accounts** — Meerdere accounts per provider met automatische round-robin — als de ene op is, wordt er overgeschakeld naar de volgende -- **Aangepaste combo's** — Aanpasbare fallback-ketens met 6 balanceringsstrategieën (fill-first, round-robin, P2C, willekeurig, minst gebruikt, kostengeoptimaliseerd) -- **Codex Business Quota** — Quotabewaking van zakelijke/teamwerkruimte rechtstreeks in het dashboard +- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention +- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly) +- **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 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
-`-blokken uit modellen zoals DeepSeek R1 naar gestandaardiseerde `reasoning_content`
-- **Gestructureerde uitvoer voor Gemini** — `json_schema` → `responseMimeType`/`responseSchema` automatische conversie
-- **`stream` is standaard ingesteld op `false`** — Sluit aan bij de OpenAI-specificaties en vermijdt onverwachte SSE in Python/Rust/Go SDK's
+- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 67+ 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
🔌 2. "Ik moet meerdere providers gebruiken, maar elk heeft een andere API"
+🔌 2. "I need to use multiple providers but each has a different API"
-OpenAI gebruikt het ene formaat, Claude (Anthropic) gebruikt een ander, Gemini nog een ander. Als een ontwikkelaar modellen van verschillende providers wil testen of terug wil vallen tussen deze providers, moet hij SDK's opnieuw configureren, eindpunten wijzigen en omgaan met incompatibele formaten. Aangepaste providers (FriendLI, NIM) hebben niet-standaard modeleindpunten. +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. -**Hoe OmniRoute het oplost:** +**How OmniRoute solves it:** -- **Unified Endpoint** — Eén enkele `http://localhost:20128/v1` dient als proxy voor alle 67+ providers -- **Formatvertaling** — Automatisch en transparant: OpenAI ↔ Claude ↔ Gemini ↔ Responses API -- **Response Sanitization** — Verwijdert niet-standaardvelden (`x_groq`, `usage_breakdown`, `service_tier`) die OpenAI SDK v1.83+ breken -- **Rolnormalisatie** — Converteert `developer` → `system` voor niet-OpenAI-providers; `system` → `user` voor GLM/ERNIE -- **Think Tag Extraction** — Extraheert `
-
🌐 3. "Mijn AI-provider blokkeert mijn regio/land"
+🌐 3. "My AI provider blocks my region/country"
-Providers zoals OpenAI/Codex blokkeren de toegang vanuit bepaalde geografische regio's. Gebruikers krijgen fouten zoals `unsupported_country_region_territory` tijdens OAuth- en API-verbindingen. Dit is vooral frustrerend voor ontwikkelaars uit ontwikkelingslanden. +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. -**Hoe OmniRoute het oplost:** +**How OmniRoute solves it:** -- **Proxyconfiguratie op 3 niveaus** — Configureerbare proxy op 3 niveaus: globaal (al het verkeer), per provider (slechts één provider) en per verbinding/sleutel -- **Kleurgecodeerde proxybadges** — Visuele indicatoren: 🟢 globale proxy, 🟡 providerproxy, 🔵verbindingsproxy, waarbij altijd het IP-adres wordt weergegeven -- **OAuth-tokenuitwisseling via proxy**: de OAuth-stroom verloopt ook via de proxy, waardoor `unsupported_country_region_territory` wordt opgelost -- **Verbindingstests via proxy** — Verbindingstests gebruiken de geconfigureerde proxy (geen directe bypass meer) -- **SOCKS5-ondersteuning** — Volledige SOCKS5-proxyondersteuning voor uitgaande routering -- **TLS Fingerprint Spoofing** — Browserachtige TLS-vingerafdruk via `wreq-js` om botdetectie te omzeilen +- **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
-` prefix
-- **Alleen gratis combo's** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $ 0/maand zonder downtime
-- **NVIDIA NIM Free Credits** — 1000 gratis credits geïntegreerd
-- **Kostengeoptimaliseerde strategie** — Routingstrategie die automatisch de goedkoopste beschikbare provider kiest
+- **Free-Only Combos** — Chain `gc/gemini-3-flash → 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
🆓 4. "Ik wil AI gebruiken voor codering, maar ik heb geen geld"
+🆓 4. "I want to use AI for coding but I have no money"
-Niet iedereen kan $ 20-200 per maand betalen voor AI-abonnementen. Studenten, ontwikkelaars uit opkomende landen, hobbyisten en freelancers hebben kosteloos toegang nodig tot kwaliteitsmodellen. +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. -**Hoe OmniRoute het oplost:** +**How OmniRoute solves it:** -- **Free Tier Providers ingebouwd** — Native ondersteuning voor 100% gratis providers: iFlow (8 onbeperkte modellen), Qwen (3 onbeperkte modellen), Kiro (Claude gratis), Gemini CLI (180K/maand gratis) +- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free) - **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/
-
🔒 5. "Ik moet mijn AI-gateway beschermen tegen ongeoorloofde toegang"
+🔒 5. "I need to protect my AI gateway from unauthorized access"
-Bij het blootstellen van een AI-gateway aan het netwerk (LAN, VPS, Docker) kan iedereen met het adres de tokens/quota van de ontwikkelaar gebruiken. Zonder bescherming zijn API's kwetsbaar voor misbruik, snelle injectie en misbruik. +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. -**Hoe OmniRoute het oplost:** +**How OmniRoute solves it:** -- **API Key Management** — Generatie, rotatie en bereik per provider met een speciale `/dashboard/api-manager`-pagina -- **Machtigingen op modelniveau** — Beperk API-sleutels tot specifieke modellen (`openai/*`, jokertekenpatronen), met de schakelaar Alles toestaan/Beperken -- **API Endpoint Protection** — Vereist een sleutel voor `/v1/models` en blokkeer specifieke providers uit de lijst -- **Auth Guard + CSRF-bescherming** — Alle dashboardroutes beschermd met `withAuth` middleware + CSRF-tokens -- **Rate Limiter** — Per-IP-snelheidslimiet met configureerbare vensters -- **IP-filtering** — Toelatingslijst/blokkeerlijst voor toegangscontrole -- **Prompt Injection Guard** — Sanering tegen kwaadaardige promptpatronen -- **AES-256-GCM-codering** — Inloggegevens gecodeerd in rust +- **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. "Mijn provider is uitgevallen en ik ben mijn codeerstroom kwijt"
+🛑 6. "My provider went down and I lost my coding flow"
-AI-aanbieders kunnen instabiel worden, 5xx-fouten retourneren of tijdelijke tarieflimieten bereiken. Als een ontwikkelaar afhankelijk is van één enkele provider, worden deze onderbroken. Zonder stroomonderbrekers kunnen herhaalde pogingen de toepassing laten crashen. +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. -**Hoe OmniRoute het oplost:** +**How OmniRoute solves it:** -- **Stroomonderbreker per provider** — Automatisch openen/sluiten met configureerbare drempels en cooldown (gesloten/open/halfopen) -- **Exponentiële uitstel** — Progressieve vertragingen bij nieuwe pogingen -- **Anti-Thundering Herd** — Mutex + semafoorbescherming tegen gelijktijdige nieuwe stormen -- **Combo Fallback Chains** — Als de primaire provider faalt, valt deze automatisch zonder tussenkomst door de keten -- **Combo-stroomonderbreker** — Schakelt falende providers binnen een combo-keten automatisch uit -- **Gezondheidsdashboard** — Uptime-monitoring, status van stroomonderbrekers, uitsluitingen, cachestatistieken, p50/p95/p99-latentie +- **Circuit Breaker per-model** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks +- **Exponential Backoff** — Progressive retry delays +- **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 +- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain +- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
-
🔧 7. "Het configureren van elke AI-tool is vervelend en repetitief"
+🔧 7. "Configuring each AI tool is tedious and repetitive"
-Ontwikkelaars gebruiken Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Elke tool heeft een andere configuratie nodig (API-eindpunt, sleutel, model). Opnieuw configureren bij het wisselen van provider of model is tijdverspilling. +Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time. -**Hoe OmniRoute het oplost:** +**How OmniRoute solves it:** -- **CLI Tools Dashboard** — Speciale pagina met installatie met één klik voor Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline -- **GitHub Copilot Config Generator** — Genereert `chatLanguageModels.json` voor VS-code met bulkmodelselectie -- **Onboarding Wizard** — Begeleide installatie in 4 stappen voor nieuwe gebruikers -- **Eén eindpunt, alle modellen** — Configureer `http://localhost:20128/v1` één keer, krijg toegang tot meer dan 36 providers +- **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 67+ providers
-
🔑 8. "Het beheren van OAuth-tokens van meerdere providers is een hel"
+🔑 8. "Managing OAuth tokens from multiple providers is hell"
-Claude Code, Codex, Gemini CLI, Copilot: ze gebruiken allemaal OAuth 2.0 met aflopende tokens. Ontwikkelaars moeten zich voortdurend opnieuw authenticeren en omgaan met `client_secret is missing`, `redirect_uri_mismatch` en storingen op externe servers. OAuth op LAN/VPS is bijzonder problematisch. +Claude Code, Codex, Gemini CLI, 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. -**Hoe OmniRoute het oplost:** +**How OmniRoute solves it:** -- **Automatische tokenvernieuwing**: OAuth-tokens worden op de achtergrond vernieuwd voordat ze verlopen -- **OAuth 2.0 (PKCE) ingebouwd** — Automatische stroom voor Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow -- **Multi-Account OAuth** — Meerdere accounts per provider via JWT/ID-tokenextractie -- **OAuth LAN/Remote Fix** — Privé-IP-detectie voor `redirect_uri` + handmatige URL-modus voor externe servers -- **OAuth achter Nginx** — gebruikt `window.location.origin` voor reverse proxy-compatibiliteit -- **Remote OAuth-handleiding** — Stapsgewijze handleiding voor Google Cloud-inloggegevens op VPS/Docker +- **Auto Token Refresh** — OAuth tokens refresh in background before expiration +- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow +- **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. "Ik weet niet hoeveel ik uitgeef of waar"
+📊 9. "I don't know how much I'm spending or where"
-Ontwikkelaars gebruiken meerdere betaalde providers, maar hebben geen uniform beeld van de uitgaven. Elke provider heeft zijn eigen factureringsdashboard, maar er is geen geconsolideerd overzicht. Onverwachte kosten kunnen zich opstapelen. +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. -**Hoe OmniRoute het oplost:** +**How OmniRoute solves it:** -- **Cost Analytics Dashboard** — Kostenregistratie per token en budgetbeheer per provider -- **Budgetlimieten per niveau** — Uitgavenplafond per niveau dat automatische terugval activeert -- **Prijsconfiguratie per model** — Configureerbare prijzen per model -- **Gebruiksstatistieken per API-sleutel** — Verzoekaantal en laatst gebruikte tijdstempel per sleutel -- **Analytics Dashboard** — Statistiekkaarten, modelgebruiksgrafiek, providertabel met succespercentages en latentie +- **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. "Ik kan geen fouten en problemen in AI-oproepen diagnosticeren"
+🐛 10. "I can't diagnose errors and problems in AI calls"
-Wanneer een oproep mislukt, weet de ontwikkelaar niet of het een snelheidslimiet, een verlopen token, een verkeerd formaat of een providerfout is. Gefragmenteerde logboeken over verschillende terminals. Zonder waarneembaarheid is debuggen een kwestie van vallen en opstaan. +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. -**Hoe OmniRoute het oplost:** +**How OmniRoute solves it:** -- **Unified Logs Dashboard** — 4 tabbladen: aanvraaglogboeken, proxylogboeken, auditlogboeken, console -- **Consolelogviewer** — Realtime viewer in terminalstijl met kleurgecodeerde niveaus, automatisch scrollen, zoeken, filteren -- **SQLite Proxy Logs** — Persistente logs die het opnieuw opstarten van de server overleven -- **Translator Playground** — 4 foutopsporingsmodi: Playground (formaatvertaling), Chat Tester (retour), Testbank (batch), Live Monitor (realtime) -- **Request Telemetry** — p50/p95/p99 latentie + X-Request-Id-tracering -- **Op bestanden gebaseerde logboekregistratie met rotatie** — Console-interceptor legt alles vast in JSON-logboek met op grootte gebaseerde rotatie +- **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 Proxy Logs** — Persistent logs that survive server restarts +- **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 Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation +- **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. "Het implementeren en onderhouden van de gateway is complex"
+🏗️ 11. "Deploying and maintaining the gateway is complex"
-Het installeren, configureren en onderhouden van een AI-proxy in verschillende omgevingen (lokaal, VPS, Docker, cloud) is arbeidsintensief. Problemen zoals hardgecodeerde paden, `EACCES` in mappen, poortconflicten en platformonafhankelijke builds zorgen voor wrijving. +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. -**Hoe OmniRoute het oplost:** +**How OmniRoute solves it:** -- **npm globale installatie** — `npm install -g omniroute && omniroute` — klaar +- **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` (geen CLI-tools) en `cli` (met Claude Code, Codex, OpenClaw) -- **Electron Desktop App** — Native app voor Windows/macOS/Linux met systeemvak, automatisch starten, offlinemodus -- **Split-Port-modus** — API en Dashboard op afzonderlijke poorten voor geavanceerde scenario's (reverse proxy, containernetwerken) -- **Cloud Sync** — Configureer synchronisatie tussen apparaten via Cloudflare Workers -- **DB-back-ups** — Automatische back-up, herstel, export en import van alle instellingen +- **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
-
🌍 12. "De interface is alleen in het Engels en mijn team spreekt geen Engels"
+🌍 12. "The interface is English-only and my team doesn't speak English"
-Teams in niet-Engelssprekende landen, vooral in Latijns-Amerika, Azië en Europa, worstelen met interfaces die alleen in het Engels beschikbaar zijn. Taalbarrières verminderen de adoptie en vergroten de configuratiefouten. +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. -**Hoe OmniRoute het oplost:** +**How OmniRoute solves it:** -- **Dashboard i18n — 30 talen** — Alle 500+ toetsen vertaald, waaronder Arabisch, Bulgaars, Deens, Duits, Spaans, Fins, Frans, Hebreeuws, Hindi, Hongaars, Indonesisch, Italiaans, Japans, Koreaans, Maleis, Nederlands, Noors, Pools, Portugees (PT/BR), Roemeens, Russisch, Slowaaks, Zweeds, Thais, Oekraïens, Vietnamees, Chinees, Filipijns, Engels -- **RTL-ondersteuning** — Ondersteuning van rechts naar links voor Arabisch en Hebreeuws -- **Meertalige README's** — 30 volledige documentatievertalingen -- **Taalkiezer** — Wereldbolpictogram in de koptekst voor realtime schakelen +- **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. "Ik heb meer nodig dan chatten - ik heb insluitingen, afbeeldingen en audio nodig"
+🔄 13. "I need more than chat — I need embeddings, images, audio"
-AI is niet alleen het voltooien van chats. Ontwikkelaars moeten afbeeldingen genereren, audio transcriberen, insluitingen voor RAG maken, documenten opnieuw rangschikken en inhoud modereren. Elke API heeft een ander eindpunt en formaat. +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. -**Hoe OmniRoute het oplost:** +**How OmniRoute solves it:** -- **Inbedding** — `/v1/embeddings` met 6 providers en 9+ modellen -- **Beeldgeneratie** — `/v1/images/generations` met 10 providers en 20+ modellen (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI) -- **Tekst-naar-video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) en SD WebUI -- **Tekst-naar-muziek** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen) -- **Audiotranscriptie** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3 -- **Tekst-naar-spraak** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, Inworld, Cartesia, PlayHT, + bestaande providers -- **Moderaties** — `/v1/moderations` — Veiligheidscontroles van inhoud -- **Herschikking** — `/v1/rerank` — Herschikking van de relevantie van documenten -- **Responses API** — Volledige `/v1/responses`-ondersteuning voor Codex +- **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. "Ik heb geen manier om de kwaliteit van verschillende modellen te testen en te vergelijken"
+🧪 14. "I have no way to test and compare quality across models"
-Ontwikkelaars willen weten welk model het beste is voor hun gebruiksscenario (code, vertaling, redenering), maar handmatig vergelijken gaat traag. Er bestaan geen geïntegreerde evaluatietools. +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. -**Hoe OmniRoute het oplost:** +**How OmniRoute solves it:** -- **LLM-evaluaties** — Golden set-tests met 10 vooraf geladen cases over begroetingen, wiskunde, aardrijkskunde, codegeneratie, JSON-compliance, vertaling, prijsverlaging, veiligheidsweigering -- **4 Matchstrategieën** — `exact`, `contains`, `regex`, `custom` (JS-functie) -- **Translator Playground Test Bench** — Batchtests met meerdere inputs en verwachte outputs, vergelijking tussen providers -- **Chat Tester** — Volledige rondreis met visuele responsweergave -- **Live Monitor** — Realtime stream van alle verzoeken die door de proxy stromen +- **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. "Ik moet schalen zonder prestatieverlies"
+📈 15. "I need to scale without losing performance"
-Naarmate het verzoekvolume groeit, genereren dezelfde vragen dubbele kosten als dezelfde vragen niet in de cache worden opgeslagen. Zonder idempotentie verspillen dubbele aanvragen de verwerking. Tarieflimieten per aanbieder moeten worden gerespecteerd. +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. -**Hoe OmniRoute het oplost:** +**How OmniRoute solves it:** -- **Semantische cache** — Cache met twee lagen (handtekening + semantisch) verlaagt de kosten en de latentie -- **Request Idempotency** — 5s deduplicatievenster voor identieke verzoeken -- **Detectie van tarieflimiet** — RPM per provider, minimale tussenruimte en maximale gelijktijdige tracking -- **Bewerkbare snelheidslimieten** — Configureerbare standaardinstellingen in Instellingen → Veerkracht met doorzettingsvermogen -- **API Key Validation Cache** — 3-tier cache voor productieprestaties -- **Gezondheidsdashboard met telemetrie** — p50/p95/p99-latentie, cachestatistieken, uptime +- **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 +- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence +- **API Key Validation Cache** — 3-tier cache for production performance +- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
-
🤖 16. "Ik wil het modelgedrag wereldwijd controleren"
+🤖 16. "I want to control model behavior globally"
-Ontwikkelaars die alle antwoorden in een specifieke taal willen, met een specifieke toon, of redeneringstokens willen beperken. Het is onpraktisch om dit in elke tool/verzoek te configureren. +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. -**Hoe OmniRoute het oplost:** +**How OmniRoute solves it:** -- **Systeempromptinjectie**: algemene prompt toegepast op alle verzoeken -- **Thinking Budget Validation** — Redenering van tokentoewijzingscontrole per verzoek (passthrough, automatisch, aangepast, adaptief) -- **6 Routingstrategieën** — Globale strategieën die bepalen hoe verzoeken worden gedistribueerd -- **Wildcard Router** — `provider/*`-patronen routeren dynamisch naar elke provider -- **Combo in-/uitschakelen schakelen** — Schakel combo's rechtstreeks vanuit het dashboard in -- **Provider wisselen** — Schakel alle verbindingen voor een provider met één klik in/uit -- **Geblokkeerde providers**: sluit specifieke providers uit van de `/v1/models`-lijst +- **System Prompt Injection** — Global prompt applied to all requests +- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive) +- **6 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 +- **Provider Toggle** — Enable/disable all connections for a provider with one click +- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
-
🧰 17. "Ik heb MCP-tools nodig als eersteklas productmogelijkheden"
+🧰 17. "I need MCP tools as first-class product capabilities"
-Veel AI-gateways stellen MCP alleen bloot als een verborgen implementatiedetail. Teams hebben een zichtbare, beheersbare operationele laag nodig. +Many AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer. -**Hoe OmniRoute het oplost:** +**How OmniRoute solves it:** -- MCP verschijnt op het dashboardnavigatie- en eindpuntprotocoltabblad -- Speciale MCP-beheerpagina met proces, tools, scopes en audit -- Ingebouwde snelstart voor `omniroute --mcp` en onboarding van klanten +- 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. "Ik heb A2A-orkestratie nodig met synchronisatie- en streamtaakpaden"
+🧠 18. "I need A2A orchestration with sync + stream task paths"
-Agentworkflows hebben zowel directe antwoorden nodig als langdurige gestreamde uitvoering met levenscycluscontrole. +Agent workflows need both direct replies and long-running streamed execution with lifecycle control. -**Hoe OmniRoute het oplost:** +**How OmniRoute solves it:** -- A2A JSON-RPC-eindpunt (`POST /a2a`) met `message/send` en `message/stream` -- SSE-streaming met voortplanting van de terminalstatus -- Taaklevenscyclus-API's voor `tasks/get` en `tasks/cancel` +- 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. "Ik heb echte MCP-processtatus nodig, geen geraden status"
+🛰️ 19. "I need real MCP process health, not guessed status"
-Operationele teams moeten weten of MCP daadwerkelijk leeft, en niet alleen of een API bereikbaar is. +Operational teams need to know if MCP is actually alive, not just whether an API is reachable. -**Hoe OmniRoute het oplost:** +**How OmniRoute solves it:** -- Runtime-hartslagbestand met PID, tijdstempels, transport, aantal gereedschappen en scope-modus -- MCP-status-API die hartslag + recente activiteit combineert -- UI-statuskaarten voor proces/uptime/hartslagversheid +- 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. "Ik heb controleerbare MCP-tooluitvoering nodig"
+📋 20. "I need auditable MCP tool execution"
-Wanneer tools de configuratie muteren of operationele acties activeren, hebben teams forensische traceerbaarheid nodig. +When tools mutate config or trigger ops actions, teams need forensic traceability. -**Hoe OmniRoute het oplost:** +**How OmniRoute solves it:** -- SQLite-ondersteunde auditregistratie voor MCP-toolaanroepen -- Filters op tool, succes/mislukking, API-sleutel en paginering -- Dashboard-audittabel + statistiekeneindpunten voor automatisering +- 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. "Ik heb MCP-rechten per integratie nodig"
+🔐 21. "I need scoped MCP permissions per integration"
-Verschillende clients moeten toegang tot de toolcategorieën met de minste bevoegdheden hebben. +Different clients should have least-privilege access to tool categories. -**Hoe OmniRoute het oplost:** +**How OmniRoute solves it:** -- 9 gedetailleerde MCP-scopes voor gecontroleerde toegang tot tools -- Scopehandhaving en zichtbaarheid in de MCP-beheerinterface -- Veilige standaardhouding voor operationeel gereedschap +- 9 granular MCP scopes for controlled tool access +- Scope enforcement and visibility in MCP management UI +- Safe default posture for operational tooling
-
⚙️ 22. "Ik heb operationele controles nodig zonder opnieuw te implementeren"
+⚙️ 22. "I need operational controls without redeploying"
-Teams hebben snelle runtimewijzigingen nodig tijdens incidenten of kostengebeurtenissen. +Teams need quick runtime changes during incidents or cost events. -**Hoe OmniRoute het oplost:** +**How OmniRoute solves it:** -- Schakel combo-activering rechtstreeks vanuit het MCP-dashboard -- Pas veerkrachtprofielen toe uit vooraf gedefinieerde beleidspakketten -- Reset de status van de stroomonderbreker vanaf hetzelfde bedieningspaneel +- Switch combo activation directly from MCP dashboard +- Apply resilience profiles from pre-defined policy packs +- Reset circuit breaker state from the same operations panel
-
🔄 23. "Ik heb live zichtbaarheid en annulering van de levenscyclus van A2A-taken nodig"
+🔄 23. "I need live A2A task lifecycle visibility and cancellation"
-Zonder inzicht in de levenscyclus worden taakincidenten moeilijk te beoordelen. +Without lifecycle visibility, task incidents become hard to triage. -**Hoe OmniRoute het oplost:** +**How OmniRoute solves it:** -- Takenlijst/filteren op staat/vaardigheid met paginering -- Inzoomen op taakmetagegevens, gebeurtenissen en artefacten -- Eindpunt voor het annuleren van taken en UI-actie met bevestiging +- 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. "Ik heb actieve streamstatistieken nodig voor A2A-belasting"
+🌊 24. "I need active stream metrics for A2A load"
-Streamingworkflows vereisen operationeel inzicht in gelijktijdigheid en liveverbindingen. +Streaming workflows require operational insight into concurrency and live connections. -**Hoe OmniRoute het oplost:** +**How OmniRoute solves it:** -- Actieve streamtellers geïntegreerd in de A2A-status -- Tijdstempel van de laatste taak en tellingen per staat -- A2A-dashboardkaarten voor real-time operationele monitoring +- Active stream counters integrated into A2A status +- Last task timestamp and per-state counts +- A2A dashboard cards for real-time ops monitoring
-
🪪 25. "Ik heb standaard agentdetectie nodig voor klanten"
+🪪 25. "I need standard agent discovery for clients"
-Externe klanten en orkestrators hebben machinaal leesbare metagegevens nodig voor onboarding. +External clients and orchestrators need machine-readable metadata for onboarding. -**Hoe OmniRoute het oplost:** +**How OmniRoute solves it:** -- Agentkaart zichtbaar op `/.well-known/agent.json` -- Mogelijkheden en vaardigheden weergegeven in de management-UI -- A2A-status-API bevat ontdekkingsmetagegevens voor automatisering +- Agent Card exposed at `/.well-known/agent.json` +- Capabilities and skills shown in management UI +- A2A status API includes discovery metadata for automation
-
🧭 26. "Ik heb protocolvindbaarheid nodig in de product-UX"
+🧭 26. "I need protocol discoverability in the product UX"
-Als gebruikers protocoloppervlakken niet kunnen ontdekken, neemt de acceptatie- en ondersteuningskwaliteit af. +If users cannot discover protocol surfaces, adoption and support quality drop. -**Hoe OmniRoute het oplost:** +**How OmniRoute solves it:** -- Zijbalkinvoer voor MCP en A2A -- Eindpuntpagina Tabblad Protocollen met snelstart en status -- Koppelingen van overzicht naar speciale managementdashboards +- 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. "Ik heb end-to-end protocolvalidatie nodig met echte clients"
+🧪 27. "I need end-to-end protocol validation with real clients"
-Mock-tests zijn niet voldoende om de protocolcompatibiliteit vóór de release te valideren. +Mock tests are not enough to validate protocol compatibility before release. -**Hoe OmniRoute het oplost:** +**How OmniRoute solves it:** -- E2E-suite die de app opstart en echt MCP SDK-clienttransport gebruikt -- A2A-clienttests voor het ontdekken, verzenden, streamen, ophalen en annuleren van stromen -- Controleer beweringen aan de hand van MCP-audit- en A2A-taken-API's +- 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. "Ik heb uniforme observatie nodig over alle interfaces heen"
+📡 28. "I need unified observability across all interfaces"
-Het opsplitsen van de waarneembaarheid per protocol creëert blinde vlekken en een langere MTTR. +Splitting observability by protocol creates blind spots and longer MTTR. -**Hoe OmniRoute het oplost:** +**How OmniRoute solves it:** -- Uniforme dashboards/logboeken/analyses in één product -- Gezondheid + audit + verzoektelemetrie over OpenAI-, MCP- en A2A-lagen -- Operationele API's voor status en automatisering +- Unified dashboards/logs/analytics in one product +- Health + audit + request telemetry across OpenAI, MCP, and A2A layers +- Operational APIs for status and automation
-
💼 29. "Ik heb één runtime nodig voor proxy + tools + agentorkestratie"
+💼 29. "I need one runtime for proxy + tools + agent orchestration"
-Het uitvoeren van veel afzonderlijke services verhoogt de operationele kosten en faalwijzen. +Running many separate services increases operational cost and failure modes. -**Hoe OmniRoute het oplost:** +**How OmniRoute solves it:** -- OpenAI-compatibele proxy, MCP-server en A2A-server in één stapel -- Gedeelde authenticatie, veerkracht, gegevensopslag en waarneembaarheid -- Consistent beleidsmodel op alle interactieoppervlakken +- 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
-
-### Voorbeeld-playbooks (geïntegreerde gebruiksscenario's)
+### Example Playbooks (Integrated Use Cases)
-**Playbook A: Maximaliseer betaald abonnement + goedkope back-up**
+**Playbook A: Maximize paid subscription + cheap backup**
```txt
Combo: "maximize-claude"
@@ -683,7 +694,7 @@ Monthly cost: $20 + small backup spend
Outcome: higher quality, near-zero interruption
```
-**Playbook B: Codeerstapel zonder kosten**
+**Playbook B: Zero-cost coding stack**
```txt
Combo: "free-forever"
@@ -695,7 +706,7 @@ Monthly cost: $0
Outcome: stable free coding workflow
```
-**Playbook C: 24/7, altijd actieve fallback-keten**
+**Playbook C: 24/7 always-on fallback chain**
```txt
Combo: "always-on"
@@ -708,65 +719,132 @@ Combo: "always-on"
Outcome: deep fallback depth for deadline-critical workloads
```
-**Playbook D: Agentoperaties met MCP + A2A**
+**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/mcp and /dashboard/a2a
-4) Control incidents with resilience profile + task cancellation
+3) Observe via /dashboard/endpoint (MCP and A2A tabs)
+4) Toggle services via inline status controls
```
---
-## ⚡ Snelle start
+## 🆓 Start Free — Zero Configuration Cost
-**1. Wereldwijd installeren:**
+> 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 **iFlow** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |
+| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |
+| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |
+| 5 | `/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).
+
+## Snel starten
+
+### 1) Install and run
```bash
npm install -g omniroute
omniroute
```
-🎉 Dashboard wordt geopend op `http://localhost:20128`
+> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:
+>
+> ```bash
+> pnpm install -g omniroute
+> pnpm approve-builds -g # Select all packages → approve
+> omniroute
+> ```
-| Commando | Beschrijving |
-| ----------------------- | ---------------------------------- |
-| `omniroute` | Startserver (standaardpoort 20128) |
-| `omniroute --port 3000` | Gebruik aangepaste poort |
-| `omniroute --no-open` | Browser niet automatisch openen |
-| `omniroute --help` | Hulp tonen |
+Dashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.
-**2. Sluit een GRATIS provider aan:**
+| 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 |
-Dashboard → Providers → **Claude Code** of **Antigravity** verbinden → OAuth-aanmelding → Klaar!
+Optional split-port mode:
-**3. Gebruik in uw CLI-tool:**
-
-```
-Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Settings:
- Endpoint: http://localhost:20128/v1
- API Key: [copy from dashboard]
- Model: if/kimi-k2-thinking
+```bash
+PORT=20128 DASHBOARD_PORT=20129 omniroute
+# API: http://localhost:20128/v1
+# Dashboard: http://localhost:20129
```
-**Dat is alles!** Begin met coderen met GRATIS AI-modellen.
+### 2) Connect providers and create your API key
-**Alternatief — uitvoeren vanaf bron:**
+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
+
+```txt
+Base URL: http://localhost:20128/v1
+API Key: [copy from Endpoint page]
+Model: if/kimi-k2-thinking (or any provider/model prefix)
+```
+
+Works with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.
+
+### 4) Enable and validate protocols (v2.0)
+
+**MCP (for tool-driven operations):**
+
+```bash
+omniroute --mcp
+```
+
+Then connect your MCP client over `stdio` and test tools like:
+
+- `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 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
+PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev
```
---
## 🐳 Docker
-OmniRoute is beschikbaar als openbare Docker-image op [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
+OmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
-**Snelle uitvoering:**
+**Quick run:**
```bash
docker run -d \
@@ -777,7 +855,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Met omgevingsbestand:**
+**With environment file:**
```bash
# Copy and edit .env first
@@ -792,7 +870,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-** Docker Compose gebruiken:**
+**Using Docker Compose:**
```bash
# Base profile (no CLI tools)
@@ -802,257 +880,552 @@ docker compose --profile base up -d
docker compose --profile cli up -d
```
-| Afbeelding | Label | Maat | Beschrijving |
-| ------------------------ | -------- | ------ | ------------------------- |
-| `diegosouzapw/omniroute` | `latest` | ~250MB | Nieuwste stabiele release |
-| `diegosouzapw/omniroute` | `1.0.3` | ~250MB | Huidige versie |
+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.
+- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.
+- 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` | `1.0.3` | ~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
+### Snel starten
+
```bash
-npm run electron:dev # Development mode
+# 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)
+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)
---
-## 💰 Prijzen in één oogopslag
+## 💰 Pricing at a Glance
-| Niveau | Aanbieder | Kosten | Quotum opnieuw instellen | Beste voor |
-| ------------------ | ----------------- | ------------------------- | ------------------------ | -------------------------- |
-| **💳 ABONNEMENT** | Claude Code (Pro) | $ 20/maand | 5u + wekelijks | Al geabonneerd |
-| | Codex (Plus/Pro) | $ 20-200/maand | 5u + wekelijks | OpenAI-gebruikers |
-| | Tweeling CLI | **GRATIS** | 180K/maand + 1K/dag | Iedereen! |
-| | GitHub-copiloot | $ 10-19/maand | Maandelijks | GitHub-gebruikers |
-| **🔑 API-SLEUTEL** | NVIDIA NIM | **GRATIS** (1000 credits) | Eenmalig | Gratis niveautesten |
-| | DeepSeek | Betalen per gebruik | Geen | Beste prijs/kwaliteit |
-| | Groq | Gratis niveau + betaald | Tarief beperkt | Ultrasnelle gevolgtrekking |
-| | xAI (Grok) | Betalen per gebruik | Geen | Grok-modellen |
-| | Mistral | Gratis niveau + betaald | Tarief beperkt | Europese AI |
-| | OpenRouter | Betalen per gebruik | Geen | 100+ modellen |
-| **💰GOEDKOOP** | GLM-4.7 | $ 0,6/1 miljoen | Dagelijks 10.00 uur | Budgetback-up |
-| | MiniMax M2.1 | $ 0,2/1 miljoen | 5-uurs rollen | Goedkoopste optie |
-| | Kimi K2 | $ 9/maand plat | 10 miljoen tokens/maand | Voorspelbare kosten |
-| **🆓 GRATIS** | iFlow | $0 | Onbeperkt | 8 modellen gratis |
-| | Qwen | $0 | Onbeperkt | 3 modellen gratis |
-| | Kiro | $0 | Onbeperkt | Claude vrij |
+| 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 |
+| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |
+| | 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** | iFlow | **$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 |
-**💡 Pro-tip:** Begin met Gemini CLI (180K gratis/maand) + iFlow (onbeperkt gratis) combo = $ 0 kosten!
+> 🆕 **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
+iFlow (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.
---
-## 💡 Belangrijkste kenmerken
+---
-### 🧠 Kernroutering en intelligentie
+## 🆓 Free Models — What You Actually Get
-| Kenmerk | Wat het doet |
-| ------------------------------------------- | ------------------------------------------------------------------------------------------------- |
-| 🎯 **Slimme terugval op 4 niveaus** | Autoroute: Abonnement → API-sleutel → Goedkoop → Gratis |
-| 📊 **Realtime quota bijhouden** | Live tokentelling + reset-aftelling per provider |
-| 🔄 **Formaatvertaling** | OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro naadloos + responsopschoning |
-| 👥 **Ondersteuning voor meerdere accounts** | Meerdere accounts per aanbieder met intelligente selectie |
-| 🔄 **Automatische tokenvernieuwing** | OAuth-tokens worden automatisch vernieuwd bij nieuwe poging |
-| 🎨 **Aangepaste combo's** | 6 strategieën: eerst vullen, round-robin, p2c, willekeurig, minst gebruikt, kostengeoptimaliseerd |
-| 🧩 **Aangepaste modellen** | Voeg elke model-ID toe aan elke provider |
-| 🌐 **Wildcard-router** | Stuur `provider/*` patronen dynamisch naar elke provider |
-| 🧠 **Denkbudget** | Passthrough-, automatische, aangepaste en adaptieve modi voor redeneermodellen |
-| 🔀 **Model Aliases** | Auto-forward deprecated model IDs to current replacements (built-in + custom) |
-| ⚡ **Background Degradation** | Auto-route background tasks (titles, summaries) to cheaper models |
-| 💬 **Systeempromptinjectie** | Algemene systeemprompt toegepast op alle verzoeken |
-| 📄 **Reacties-API** | Volledige OpenAI Responses API (`/v1/responses`) ondersteuning voor Codex |
+> 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.
-### 🎵 Multimodale API's
+### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)
-| Kenmerk | Wat het doet |
-| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 🖼️ **Beeldgeneratie** | `/v1/images/generations` — 4 providers, 9+ modellen |
-| 📐 **Insluitingen** | `/v1/embeddings` — 6 providers, 9+ modellen |
-| 🎤 **Audiotranscriptie** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |
-| 🔊 **Tekst-naar-spraak** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) |
-| 🛡️ **Moderaties** | `/v1/moderations` — Veiligheidscontroles van inhoud |
-| 🔀 **Herschikking** | `/v1/rerank` — Herschikking van documentrelevantie |
+| 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 |
-### 🛡️ Veerkracht en veiligheid
+### 🟢 IFLOW MODELS (Free OAuth — No Credit Card)
-| Kenmerk | Wat het doet |
-| ------------------------------------- | ---------------------------------------------------------------------------------------- |
-| 🔌 **Stroomonderbreker** | Automatisch openen/sluiten per provider met configureerbare drempels |
-| 🛡️ **Anti-donderende kudde** | Mutex + semafoorsnelheidslimiet voor API-sleutelproviders |
-| 🧠 **Semantische cache** | Tweelaagse cache (handtekening + semantisch) verlaagt de kosten en latentie |
-| ⚡ **Idempotentie aanvragen** | 5s ontdubbelingsvenster voor dubbele verzoeken |
-| 🔒 **TLS-vingerafdrukspoofing** | Omzeil TLS-gebaseerde botdetectie via wreq-js |
-| 🌐 **IP-filtering** | Toelatingslijst/blokkeerlijst voor API-toegangscontrole |
-| 📊 **Bewerkbare tarieflimieten** | Configureerbare RPM, minimale tussenruimte en maximale gelijktijdigheid op systeemniveau |
-| 💾 **Rate Limit Persistence** | Learned limits survive restarts via SQLite with 60s debounce + 24h staleness |
-| 🔄 **Token Refresh Resilience** | Per-provider circuit breaker (5 fails→30min) + 30s timeout per attempt |
-| 🛡 **API-eindpuntbescherming** | Auth-gating + providerblokkering voor het `/models` eindpunt |
-| 🔒 **Proxyzichtbaarheid** | Kleurgecodeerde badges: 🟢 wereldwijd, 🟡 provider, 🔵 per verbinding met IP-display |
-| 🌐 **Proxyconfiguratie op 3 niveaus** | Configureer proxy's op globaal, per provider of per verbindingsniveau |
+| 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 |
-### 📊 Waarneembaarheid en analyse
+### 🟡 QWEN MODELS (Device Code Auth)
-| Kenmerk | Wat het doet |
-| ------------------------------------------------- | ------------------------------------------------------------------------------------------- |
-| 📝 **Logboekregistratie aanvragen** | Foutopsporingsmodus met volledige aanvraag-/antwoordlogboeken |
-| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |
-| 💾 **SQLite Proxy-logboeken** | Aanhoudende proxylogboeken overleven het opnieuw opstarten van de server |
-| 📊 **Analytics-dashboard** | Recharts-aangedreven: statistische kaarten, modelgebruiksgrafiek, providertabel |
-| 📈 **Voortgang bijhouden** | SSE-voortgangsgebeurtenissen aanmelden voor streaming |
-| 🧪 **LLM-evaluaties** | Gouden settesten met 4 wedstrijdstrategieën |
-| 🔍 **Telemetrie aanvragen** | p50/p95/p99 latentie-aggregatie + X-Request-Id-tracering |
-| 📋 **Logdashboard** | Uniforme pagina met 4 tabbladen: aanvraaglogboeken, proxylogboeken, auditlogboeken, console |
-| 🖥️ **Consolelogviewer** | Realtime viewer in terminalstijl met niveaufilter, zoeken, automatisch scrollen |
-| 📑 **Op bestanden gebaseerde logboekregistratie** | Console-interceptor legt alle uitvoer vast naar JSON-logbestand met rotatie |
-| 🏥 **Gezondheidsdashboard** | Systeemuptime, status van stroomonderbrekers, uitsluitingen, cachestatistieken |
-| 💰 **Kosten bijhouden** | Budgetbeheer + prijsconfiguratie per model |
+| 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) |
-### ☁️ Implementatie en synchronisatie
+### 🟣 GEMINI CLI (Google OAuth)
-| Kenmerk | Wat het doet |
-| ----------------------------- | ------------------------------------------------------------------------------- |
-| 💾 **Cloudsynchronisatie** | Synchroniseer de configuratie op verschillende apparaten via Cloudflare Workers |
-| 🌐 **Overal implementeren** | Localhost, VPS, Docker, Cloudflare Workers |
-| 🔑 **API-sleutelbeheer** | Genereer, roteer en bereik API-sleutels per provider |
-| 🧙 **Onboarding-wizard** | Begeleide installatie in 4 stappen voor nieuwe gebruikers |
-| 🔧 **CLI Tools-dashboard** | Configureer met één klik Claude, Codex, Cline, OpenClaw, Kilo, Antigravity |
-| 🔄 **DB-back-ups** | Automatische back-up, herstel, export en import voor alle instellingen |
-| 🌐 **Internationalisering** | Volledige i18n met next-intl — Engels + Portugees (Brazilië) ondersteuning |
-| 🌍 **Taalkiezer** | Wereldbolpictogram in koptekst voor realtime taalwisseling (🇺🇸/🇧🇷) |
-| 🧹 **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 |
-| 📂 **Aangepaste gegevensmap** | `DATA_DIR` env var om standaard `~/.omniroute` opslagpad te overschrijven |
+| Model | Prefix | Limit | Rate Limit |
+| ------------------------ | ------ | --------------------------- | ------------- |
+| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |
+| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |
+
+### ⚫ 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
+> iFlow (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 v2.0 is built as an operational platform, not just a relay proxy.
+
+### 🆕 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 Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |
+| 🤖 **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 (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) |
+| 🤝 **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** | 9 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 combo, apply resilience profiles, reset breakers from one control surface |
+
+### 🧠 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** | 6 balancing strategies + fallback chain control |
+| 🌐 **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) |
+| 💬 **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 |
+| ----------------------------------- | -------------------------------------------------------------------------------------- |
+| 🔌 **Circuit Breakers** | Per-model trip/recover with threshold controls |
+| 🎯 **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 |
+| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |
+| 🔑 **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 |
+
+### 📊 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 |
+| 📋 **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 |
+
+### ☁️ Deployment & Platform
+
+| Feature | What It Does |
+| ----------------------------- | --------------------------------------------------------- |
+| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |
+| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |
+| 💾 **Cloud Sync** | Configuration sync via cloud worker |
+| 🔄 **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 |
+
+### Feature Deep Dive
+
+#### Smart fallback with practical cost control
+
+```txt
+Combo: "my-coding-stack"
+ 1. cc/claude-opus-4-6
+ 2. nvidia/llama-3.3-70b
+ 3. glm/glm-4.7
+ 4. if/kimi-k2-thinking
+```
+
+When quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.
+
+#### 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)
+
+#### 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)
🚀 30. "Ik moet agentische workflows verzenden zonder wildgroei van lijmcodes"
+🚀 30. "I need to ship agentic workflows without glue-code sprawl"
-Teams verliezen snelheid bij het samenvoegen van meerdere ad-hocservices en scripts. +Teams lose velocity when stitching multiple ad-hoc services and scripts. -**Hoe OmniRoute het oplost:** +**How OmniRoute solves it:** -- Uniforme eindpuntstrategie voor klanten en agenten -- Ingebouwde gebruikersinterfaces voor protocolbeheer en rookvalidatiepaden -- Productieklare fundamenten (beveiliging, loggen, veerkracht, back-up) +- Unified endpoint strategy for clients and agents +- Built-in protocol management UIs and smoke validation paths +- Production-ready foundations (security, logging, resilience, backup)
-` blokken → `reasoning_content` voor denkmodellen
-- **Gestructureerde uitvoer** — `json_schema` → Gemini's `responseMimeType`/`responseSchema`
-
-### 👥 Ondersteuning voor meerdere accounts
-
-- Voeg meerdere accounts per aanbieder toe
-- Automatische round-robin of op prioriteit gebaseerde routering
-- Terugval naar het volgende account wanneer één het quotum bereikt
-
-### 🔄 Automatische tokenvernieuwing
-
-- OAuth-tokens worden automatisch vernieuwd voordat ze verlopen
-- Geen handmatige herauthenticatie nodig
-- Naadloze ervaring bij alle providers
-
-### 🎨 Aangepaste combo's
-
-- Creëer onbeperkte modelcombinaties
-- 6 strategieën: eerst vullen, round-robin, macht van twee keuzes, willekeurig, minst gebruikt, kostengeoptimaliseerd
-- Deel combo's op verschillende apparaten met Cloud Sync
-
-### 🏥 Gezondheidsdashboard
-
-- Systeemstatus (uptime, versie, geheugengebruik)
-- Status van de stroomonderbrekers per provider (Gesloten/Open/Half-Open)
-- Tarieflimietstatus en actieve uitsluitingen
-- Kenmerkende cachestatistieken
-- Latency-telemetrie (p50/p95/p99) + promptcache
-- Reset de gezondheidsstatus met één klik
-
-### 🔧 Vertalerspeeltuin
-
-OmniRoute bevat een krachtige ingebouwde Translator Playground met **4 modi** voor het debuggen, testen en monitoren van API-vertalingen:
-
-| Modus | Beschrijving |
-| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **💻 Speeltuin** | Directe formaatvertaling: plak de hoofdtekst van een API-verzoek en zie direct hoe OmniRoute deze vertaalt tussen providerformaten (OpenAI ↔ Claude ↔ Gemini ↔ Responses API). Bevat voorbeeldsjablonen en automatische detectie van formaten. |
-| **💬 Chattester** | Stuur echte chatverzoeken via OmniRoute en bekijk het volledige overzicht: uw invoer, het vertaalde verzoek, het antwoord van de provider en het vertaalde antwoord terug. Van onschatbare waarde voor het valideren van combo-routering. |
-| **🧪 Proefbank** | Batchtestmodus: definieer meerdere testgevallen met verschillende inputs en verwachte outputs, voer ze allemaal tegelijk uit en vergelijk de resultaten van verschillende providers en modellen. |
-| **📱Livemonitor** | Real-time monitoring van verzoeken: bekijk binnenkomende verzoeken terwijl ze door OmniRoute stromen, bekijk de formaatvertalingen live en identificeer problemen direct. |
-
-**Toegang:** Dashboard → Vertaler (zijbalk)
-
-### 💾Cloudsynchronisatie
-
-- Synchroniseer providers, combo's en instellingen op verschillende apparaten
-- Automatische achtergrondsynchronisatie
-- Veilige gecodeerde opslag
+- `GET /api/mcp/status`
+- `GET /api/mcp/tools`
+- `GET /api/mcp/audit`
+- `GET /api/mcp/audit/stats`
-## 🧪 Evaluaties (Evals)
+📖 Functiedetails
+🧩 MCP Setup (Model Context Protocol)
-### 🎯 Slimme terugval op 4 niveaus +Start MCP transport in stdio mode: -Creëer combo's met automatische terugval: - -``` -Combo: "my-coding-stack" - 1. cc/claude-opus-4-6 (your subscription) - 2. nvidia/llama-3.3-70b (free NVIDIA API) - 3. glm/glm-4.7 (cheap backup, $0.6/1M) - 4. if/kimi-k2-thinking (free fallback) - -→ Auto switches when quota runs out or errors occur +```bash +omniroute --mcp ``` -### 📊 Realtime quota bijhouden +Recommended validation flow: -- Tokenverbruik per aanbieder -- Aftellen resetten (5 uur, dagelijks, wekelijks) -- Kostenraming voor betaalde niveaus -- Maandelijkse uitgavenrapporten +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. -### 🔄 Formaatvertaling +Useful APIs for automation: -Naadloze vertaling tussen formaten: - -- **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **OpenAI-reacties** -- Uw CLI-tool verzendt OpenAI-formaat → OmniRoute vertaalt → Provider ontvangt native formaat -- Werkt met elke tool die aangepaste OpenAI-eindpunten ondersteunt -- **Reactieopschoning** — Verwijdert niet-standaardvelden voor strikte OpenAI SDK-compatibiliteit -- **Rolnormalisatie** — `developer` → `system` voor niet-OpenAI; `system` → `user` voor GLM/ERNIE-modellen -- **Extractie van Think-tags** — `
+
🤝 A2A Setup (Agent2Agent)
-OmniRoute bevat een ingebouwd evaluatieframework om de LLM-responskwaliteit te testen aan de hand van een gouden set. U kunt deze openen via **Analytics → Evaluaties** in het dashboard. +Discover the agent: -### Ingebouwde gouden set +```bash +curl http://localhost:20128/.well-known/agent.json +``` -De vooraf geladen "OmniRoute Golden Set" bevat 10 testcases die betrekking hebben op: +Send a task: -- Groeten, wiskunde, aardrijkskunde, codegeneratie -- Naleving van JSON-formaat, vertaling, prijsverlaging -- Veiligheidsweigering (schadelijke inhoud), tellen, booleaanse logica +```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."}]}}' +``` -### Evaluatiestrategieën +Manage lifecycle: -| Strategie | Beschrijving | Voorbeeld | -| ---------- | --------------------------------------------------------------------- | -------------------------------- | -| `exact` | De uitvoer moet exact overeenkomen met | `"4"` | -| `contains` | De uitvoer moet een subtekenreeks bevatten (niet hoofdlettergevoelig) | `"Paris"` | -| `regex` | Uitvoer moet overeenkomen met regex-patroon | `"1.*2.*3"` | -| `custom` | Aangepaste JS-functie retourneert waar/onwaar | `(output) => output.length > 10` | +- `GET /api/a2a/status` +- `GET /api/a2a/tasks` +- `GET /api/a2a/tasks/:id` +- `POST /api/a2a/tasks/:id/cancel` ---- +Operational UI: -## 📖 Installatiehandleiding +- `/dashboard/a2a` for task/state/stream observability and smoke actions + +
-
+
+💳 Abonnementaanbieders
+🧪 End-to-end protocol validation
-### Claude-code (Pro/Max) +Validate both protocols with real clients: + +```bash +npm run test:protocols:e2e +``` + +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) ```bash Dashboard → Providers → Connect Claude Code @@ -1065,9 +1438,9 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Pro-tip:** Gebruik Opus voor complexe taken, Sonnet voor snelheid. OmniRoute houdt quota bij per model! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! -### OpenAI-codex (Plus/Pro) +### OpenAI Codex (Plus/Pro) ```bash Dashboard → Providers → Connect Codex @@ -1079,7 +1452,24 @@ Models: cx/gpt-5.1-codex-max ``` -### Gemini CLI (GRATIS 180K/maand!) +#### 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). + +### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -1091,9 +1481,9 @@ Models: gc/gemini-2.5-pro ``` -**Beste waarde:** Enorm gratis niveau! Gebruik dit vóór betaalde niveaus. +**Best Value:** Huge free tier! Use this before paid tiers. -### GitHub-copiloot +### GitHub Copilot ```bash Dashboard → Providers → Connect GitHub @@ -1109,88 +1499,88 @@ Models:
-
🔑 API-sleutelproviders
+🔑 API Key Providers
-### NVIDIA NIM (GRATIS 1000 credits!) +### NVIDIA NIM (FREE developer access — 70+ models) -1. Aanmelden: [build.nvidia.com](https://build.nvidia.com) -2. Ontvang een gratis API-sleutel (inclusief 1000 inferentiecredits) -3. Dashboard → Provider toevoegen → NVIDIA NIM: - - API-sleutel: `nvapi-your-key` +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` -**Modellen:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct` en nog meer dan 50 +**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more -**Pro-tip:** OpenAI-compatibele API — werkt naadloos samen met de formaatvertaling van OmniRoute! +**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation! -### Diepzoeken +### DeepSeek -1. Aanmelden: [platform.deepseek.com](https://platform.deepseek.com) -2. Haal de API-sleutel op -3. Dashboard → Provider toevoegen → DeepSeek +1. Sign up: [platform.deepseek.com](https://platform.deepseek.com) +2. Get API key +3. Dashboard → Add Provider → DeepSeek -**Modellen:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` +**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` -### Groq (gratis niveau beschikbaar!) +### Groq (Free Tier Available!) -1. Aanmelden: [console.groq.com](https://console.groq.com) -2. Ontvang een API-sleutel (inclusief gratis laag) -3. Dashboard → Provider toevoegen → Groq +1. Sign up: [console.groq.com](https://console.groq.com) +2. Get API key (free tier included) +3. Dashboard → Add Provider → Groq -**Modellen:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` +**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` -**Pro-tip:** Ultrasnelle gevolgtrekking — het beste voor realtime coderen! +**Pro Tip:** Ultra-fast inference — best for real-time coding! -### OpenRouter (meer dan 100 modellen) +### OpenRouter (100+ Models) -1. Aanmelden: [openrouter.ai](https://openrouter.ai) -2. Haal de API-sleutel op -3. Dashboard → Provider toevoegen → OpenRouter +1. Sign up: [openrouter.ai](https://openrouter.ai) +2. Get API key +3. Dashboard → Add Provider → OpenRouter -**Modellen:** Krijg toegang tot meer dan 100 modellen van alle grote providers via één API-sleutel. +**Models:** Access 100+ models from all major providers through a single API key.
-
💰 Goedkope providers (back-up)
+💰 Cheap Providers (Backup)
-### GLM-4.7 (dagelijkse reset, $0,6/1 miljoen) +### GLM-4.7 (Daily reset, $0.6/1M) -1. Aanmelden: [Zhipu AI](https://open.bigmodel.cn/) -2. Haal de API-sleutel op uit het Coderingsplan -3. Dashboard → API-sleutel toevoegen: - - Aanbieder: `glm` - - API-sleutel: `your-key` +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` -**Gebruik:** `glm/glm-4.7` +**Use:** `glm/glm-4.7` -**Pro-tip:** Coderingsplan biedt 3× quotum tegen 1/7 kosten! Dagelijks resetten om 10:00 uur. +**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -### MiniMax M2.1 (5 uur resetten, $0,20/1M) +### MiniMax M2.1 (5h reset, $0.20/1M) -1. Aanmelden: [MiniMax](https://www.minimax.io/) -2. Haal de API-sleutel op -3. Dashboard → API-sleutel toevoegen +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key +3. Dashboard → Add API Key -**Gebruik:** `minimax/MiniMax-M2.1` +**Use:** `minimax/MiniMax-M2.1` -**Pro-tip:** Goedkoopste optie voor lange context (1 miljoen tokens)! +**Pro Tip:** Cheapest option for long context (1M tokens)! -### Kimi K2 ($9/maand vast) +### Kimi K2 ($9/month flat) -1. Abonneer je: [Moonshot AI](https://platform.moonshot.ai/) -2. Haal de API-sleutel op -3. Dashboard → API-sleutel toevoegen +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key +3. Dashboard → Add API Key -**Gebruik:** `kimi/kimi-latest` +**Use:** `kimi/kimi-latest` -**Pro-tip:** Vaste $ 9/maand voor 10 miljoen tokens = $ 0,90/1 miljoen effectieve kosten! +**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
-
🆓 GRATIS providers (noodback-up)
+🆓 FREE Providers (Emergency Backup)
-### iFlow (8 GRATIS modellen) +### iFlow (5 FREE models via OAuth) ```bash Dashboard → Connect iFlow @@ -1205,7 +1595,7 @@ Models: if/deepseek-r1 ``` -### Qwen (3 GRATIS modellen) +### Qwen (4 FREE models via Device Code) ```bash Dashboard → Connect Qwen @@ -1217,7 +1607,7 @@ Models: qw/qwen3-coder-flash ``` -### Kiro (Claude GRATIS) +### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro @@ -1232,9 +1622,9 @@ Models:
-
🎨 Combo's maken
+🎨 Create Combos
-### Voorbeeld 1: Maximaliseer abonnement → Goedkope back-up +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -1248,7 +1638,7 @@ Models: Use in CLI: premium-coding ``` -### Voorbeeld 2: Alleen gratis (geen kosten) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -1263,9 +1653,9 @@ Cost: $0 forever!
-
---
-## 🐛 Problemen oplossen
+## Probleemoplossing
🔧 CLI-integratie
+🔧 CLI Integration
-### Cursor-IDE +### Cursor IDE ``` Settings → Models → Advanced: @@ -1274,11 +1664,11 @@ Settings → Models → Advanced: Model: cc/claude-opus-4-6 ``` -### Claude-code +### Claude Code -Gebruik de pagina **CLI Tools** in het dashboard voor configuratie met één klik, of bewerk `~/.claude/settings.json` handmatig. +Use the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually. -### Codex-CLI +### Codex CLI ```bash export OPENAI_BASE_URL="http://localhost:20128" @@ -1287,15 +1677,15 @@ export OPENAI_API_KEY="your-omniroute-api-key" codex "your prompt" ``` -### Open Klauw +### OpenClaw -**Optie 1 — Dashboard (aanbevolen):** +**Option 1 — Dashboard (recommended):** ``` Dashboard → CLI Tools → OpenClaw → Select Model → Apply ``` -**Optie 2 — Handmatig:** Bewerk `~/.openclaw/openclaw.json`: +**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`: ```json { @@ -1311,9 +1701,9 @@ Dashboard → CLI Tools → OpenClaw → Select Model → Apply } ``` -> **Opmerking:** OpenClaw werkt alleen met lokale OmniRoute. Gebruik `127.0.0.1` in plaats van `localhost` om IPv6-resolutieproblemen te voorkomen. +> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues. -### Cline / Doorgaan / RooCode +### Cline / Continue / RooCode ``` Settings → API Configuration: @@ -1323,110 +1713,245 @@ Settings → API Configuration: 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. +
-
-- **Runtime**: Node.js 18–22 LTS (⚠️ Node.js 24+ wordt **niet ondersteund** — `better-sqlite3` native binaire bestanden zijn incompatibel)
-- **Taal**: TypeScript 5.9 — **100% TypeScript** voor `src/` en `open-sse/` (v1.0.6)
-- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4
-- **Database**: LowDB (JSON) + SQLite (domeinstatus + proxylogboeken)
-- **Streaming**: door de server verzonden gebeurtenissen (SSE)
-- **Auth**: OAuth 2.0 (PKCE) + JWT + API-sleutels
-- **Testen**: Node.js-testloper (368+ unit-tests)
-- **CI/CD**: GitHub-acties (automatische npm-publicatie + Docker Hub bij release)
-- **Website**: [omniroute.online](https://omniroute.online)
-- **Pakket**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
-- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
-- **Veerkracht**: stroomonderbreker, exponentieel uitstel, anti-donderkudde, TLS-spoofing
-
----
-
-## 📖 Documentatie
-
-| Document | Beschrijving |
-| -------------------------------------------- | --------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combo's, CLI-integratie, implementatie |
-| [API Reference](docs/API_REFERENCE.md) | Alle eindpunten met voorbeelden |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Veelvoorkomende problemen en oplossingen |
-| [Architecture](docs/ARCHITECTURE.md) | Systeemarchitectuur en internals |
-| [Contributing](CONTRIBUTING.md) | Ontwikkelingsopstelling en richtlijnen |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0-specificatie |
-| [Security Policy](SECURITY.md) | Kwetsbaarheidsrapportage en beveiligingspraktijken |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Volledige gids: VM + nginx + Cloudflare-installatie |
-| [Features Gallery](docs/FEATURES.md) | Visuele dashboardrondleiding met screenshots |
-
-### 📸 Dashboardvoorbeeld
+## 🛠️ Tech Stack
Klik om de probleemoplossingsgids uit te vouwen
+Click to expand troubleshooting guide
-**"Taalmodel heeft geen berichten verstrekt"** +**"Language model did not provide messages"** -- Providerquotum opgebruikt → Controleer dashboardquotumtracker -- Oplossing: gebruik combo-fallback of schakel over naar een goedkoper niveau +- Provider quota exhausted → Check dashboard quota tracker +- Solution: Use combo fallback or switch to cheaper tier -**Snelheidslimiet** +**Rate limiting** -- Abonnementquotum op → Terugval op GLM/MiniMax -- Combinatie toevoegen: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Subscription quota out → Fallback to GLM/MiniMax +- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -**OAuth-token verlopen** +**OAuth token expired** -- Automatisch vernieuwd door OmniRoute -- Als de problemen aanhouden: Dashboard → Provider → Opnieuw verbinding maken +- Auto-refreshed by OmniRoute +- If issues persist: Dashboard → Provider → Reconnect -**Hoge kosten** +**High costs** -- Controleer gebruiksstatistieken in Dashboard → Kosten -- Schakel het primaire model over naar GLM/MiniMax -- Gebruik de gratis laag (Gemini CLI, iFlow) voor niet-kritieke taken +- Check usage stats in Dashboard → Costs +- Switch primary model to GLM/MiniMax +- Use free tier (Gemini CLI, iFlow) for non-critical tasks -**Dashboard opent op verkeerde poort** +**Dashboard/API ports are wrong** -- Stel `PORT=20128` en `NEXT_PUBLIC_BASE_URL=http://localhost:20128` in +- `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) -**Cloudsynchronisatiefouten** +**Cloud sync errors** -- Controleer of `BASE_URL` verwijst naar uw actieve exemplaar -- Controleer of `CLOUD_URL` verwijst naar uw verwachte cloudeindpunt -- Houd `NEXT_PUBLIC_*` waarden afgestemd op de waarden op de server +- 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 -**Eerste login werkt niet** +**First login not working** -- Controleer `INITIAL_PASSWORD` in `.env` -- Indien niet ingesteld, is het reservewachtwoord `123456` +- Check `INITIAL_PASSWORD` in `.env` +- If unset, fallback password is `123456` -**Geen verzoeklogboeken** +**No request logs** -- Stel `ENABLE_REQUEST_LOGS=true` in in `.env` +- Set `ENABLE_REQUEST_LOGS=true` in `.env` -**Verbindingstest toont "Ongeldig" voor OpenAI-compatibele providers** +**Connection test shows "Invalid" for OpenAI-compatible providers** -- Veel providers stellen geen `/models` eindpunt beschikbaar -- OmniRoute v1.0.6+ omvat fallback-validatie via chat-voltooiingen -- Zorg ervoor dat de basis-URL het achtervoegsel `/v1` bevat +- 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 +### 🔐 OAuth on a Remote Server + -> **⚠️ BELANGRIJK voor gebruik met OmniRoute op VPS/Docker/server op afstand** +> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server** -### OAuth +#### Why does Antigravity / Gemini CLI OAuth fail on remote servers? -Deze bewijzen **Antigravity** en **Gemini CLI** gebruiken **Google OAuth 2.0** voor authenticatie. O Google vraagt dat `redirect_uri` geen OAuth-stroom gebruikt **exatamente** een van de URI's vóór de kadaster zonder toepassing van Google Cloud Console. +The **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console. -Omdat OAuth geen OmniRoute heeft geregistreerd, is dit **apenas para `localhost`**. Wanneer u OmniRoute op een externe server opent (bijvoorbeeld: `https://omniroute.meuservidor.com`), of Google een authenticatie aanvraagt: +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 ``` -### Oplossing: Configureer uw eigen OAuth-credenciais +#### Solution: Configure your own OAuth credentials -U kunt precies zien hoe **OAuth 2.0 Client ID** geen Google Cloud Console heeft met een URI van zijn server. +You need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI. -#### Passo een passo +#### Step-by-step -**1. Toegang tot Google Cloud Console** +**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 + +# For Gemini CLI: +GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com +GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +``` + +**6. Restart OmniRoute** + +```bash +# npm: +npm run dev + +# Docker: +docker restart omniroute +``` + +**7. Try connecting again** + +Dashboard → Providers → Antigravity (or Gemini CLI) → OAuth + +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. + +--- + +
+
---
-## 🛠️Technische stapel
+🇧🇷 Versão em Português
+ +#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos? + +Os provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo. + +As credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticação com: + +``` +Error 400: redirect_uri_mismatch +``` + +#### Solução: Configure suas próprias credenciais OAuth + +Você precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor. + +#### Passo a passo + +**1. Acesse o Google Cloud Console** Abra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) -**2. Nieuwe OAuth 2.0 client-ID** +**2. Crie um novo OAuth 2.0 Client ID** -- Klik op **"+ Credentials aanmaken"** → **"OAuth-client-ID"** -- Applicatietip: **"Webapplicatie"** -- Nome: escolha qualquer nome (bijvoorbeeld: `OmniRoute Remote`) +- Clique em **"+ Create Credentials"** → **"OAuth client ID"** +- Tipo de aplicativo: **"Web application"** +- Nome: escolha qualquer nome (ex: `OmniRoute Remote`) -**3. Adicione als geautoriseerde omleidings-URI's** +**3. Adicione as Authorized Redirect URIs** -Geen campagne **"Geautoriseerde omleidings-URI's"**, aanbevolen: +No campo **"Authorized redirect URIs"**, adicione: ``` https://seu-servidor.com/callback ``` -> Vervang `seu-servidor.com` door de domicilie of het IP-adres van uw server (inclusief een noodzakelijke poort, bijvoorbeeld: `http://45.33.32.156:20128/callback`). +> Substitua `seu-servidor.com` pelo domínio ou IP do seu servidor (inclua a porta se necessário, ex: `http://45.33.32.156:20128/callback`). -**4. Bewaar en kopieer als credenciais** +**4. Salve e copie as credenciais** -U kunt ook op Google klikken op **Client-ID** en **Clientgeheim**. +Após criar, o Google mostrará o **Client ID** e o **Client Secret**. -**5. Configureer als variáveis de ambiente** +**5. Configure as variáveis de ambiente** -Geen `.env` (of de verschillende omgevingen van Docker): +No seu `.env` (ou nas variáveis de ambiente do Docker): ```bash # Para Antigravity: @@ -1439,7 +1964,7 @@ GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret ``` -**6. Reinicie van OmniRoute** +**6. Reinicie o OmniRoute** ```bash # Se usando npm: @@ -1449,153 +1974,147 @@ npm run dev docker restart omniroute ``` -**7. Nieuwe verbinding** +**7. Tente conectar novamente** Dashboard → Providers → Antigravity (ou Gemini CLI) → OAuth -Nadat Google de juiste verwijzing naar `https://seu-servidor.com/callback` heeft gemaakt, is deze autenticaal functioneel geworden. +Agora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará. --- -### Tijdelijke tijdelijke oplossing (sem credenciais próprias configureren) +#### Workaround temporário (sem configurar credenciais próprias) -Als u geen geloofwaardige geloofwaardigheid meer heeft, is het mogelijk om de stroom **handleiding van de URL** te gebruiken: +Se não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**: -1. OmniRoute gebruikt een autorisatie-URL van Google -2. Als u de autorisatie heeft gegeven, zal Google de doorverwijzing naar `localhost` uitvoeren (die geen externe service biedt) -3. **Kopieer een volledige URL** door de browser van uw browser (het bericht dat de pagina niet verder gaat) -4. Cole essa URL is niet beschikbaar op de verbindingswijze van OmniRoute -5. Klik op **"Verbinden"** +1. O OmniRoute abrirá a URL de autorização do Google +2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto) +3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue) +4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute +5. Clique em **"Connect"** -> Deze tijdelijke oplossing werkt door de autorisatiecode van de URL en is onafhankelijk van het omleiden naar uw autorisatie of niet. +> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.
-
---
-## 🗺️
+## Documentatie
-OmniRoute heeft **210+ functies gepland** over meerdere ontwikkelingsfasen. Dit zijn de belangrijkste gebieden:
-
-| Categorie | Geplande functies | Hoogtepunten |
-| ------------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
-| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |
-| 🧠 **Routing en intelligentie** | 25+ | Routering met de laagste latentie, op tags gebaseerde routering, quota-preflight, P2C-accountselectie |
-| 🔒 **Beveiliging en naleving** | 20+ | SSRF-verharding, cloaking van inloggegevens, snelheidslimiet per eindpunt, scoping van beheersleutels |
-| 📊 **Waarneembaarheid** | 15+ | OpenTelemetry-integratie, realtime quotabewaking, kostenregistratie per model |
-| 🔄 **Provider-integraties** | 20+ | Dynamisch modelregister, cooldowns van providers, Codex met meerdere accounts, parseren van Copilot-quota |
-| ⚡ **Prestaties** | 15+ | Dubbele cachelaag, promptcache, responscache, streaming keepalive, batch-API |
-| 🌐 **Ecosysteem** | 10+ | WebSocket API, configuratie hot-reload, gedistribueerde configuratieopslag, commerciële modus |
-
-### 🔜 Binnenkort beschikbaar
-
-- 🔗 **OpenCode-integratie** — Native providerondersteuning voor de OpenCode AI-coderings-IDE
-- 🔗 **TRAE-integratie** — Volledige ondersteuning voor het TRAE AI-ontwikkelingsframework
-- 📦 **Batch API** — Asynchrone batchverwerking voor bulkaanvragen
-- 🎯 **Op tags gebaseerde routering** — Routeer verzoeken op basis van aangepaste tags en metagegevens
-- 💰 **Laagste kostenstrategie** — Selecteer automatisch de goedkoopste beschikbare provider
-
-> 📝 Volledige functiespecificaties beschikbaar in [link](docs/new-features/) (217 gedetailleerde specificaties)
+| Document | Description |
+| ---------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 16 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/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
+| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
-## 👥 Bijdragers
+## 🗺️ Roadmap
+
+OmniRoute has **210+ 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, P2C account selection |
+| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |
+| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |
+| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider 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
[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
-### Hoe u kunt bijdragen
+### How to Contribute
-1. Fork de repository
-2. Maak uw feature branch (`git checkout -b feature/amazing-feature`)
-3. Leg uw wijzigingen vast (`git commit -m 'Add amazing feature'`)
-4. Duw naar het filiaal (`git push origin feature/amazing-feature`)
-5. Open een Pull Request
+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
-Zie [CONTRIBUTING.md](CONTRIBUTING.md) voor gedetailleerde richtlijnen.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
-### Er wordt een nieuwe versie uitgebracht
+### Releasing a New Version
```bash
# Create a release — npm publish happens automatically
-gh release create v1.0.6 --title "v1.0.6" --generate-notes
+gh release create v2.0.0 --title "v2.0.0" --generate-notes
```
---
-## 📊 Sterrengeschiedenis
+## 📊 Star History
## Stargazers over time
## [](https://starchart.cc/diegosouzapw/OmniRoute)
-## 🙏 Dankbetuigingen
+## 🙏 Acknowledgments
-Speciale dank aan **[9router](https://github.com/decolua/9router)** door **[decolua](https://github.com/decolua)** — het originele project dat deze vork inspireerde. OmniRoute bouwt voort op die ongelooflijke basis met extra functies, multimodale API's en een volledige TypeScript-herschrijving.
+Special thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.
-Speciale dank aan **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — de originele Go-implementatie die deze JavaScript-port inspireerde.
+Special thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.
---
-## 📄 Licentie
+## Licentie
-MIT-licentie - zie [LICENSE](LICENSE) voor details.
+MIT License - see [LICENSE](LICENSE) for details.
---
Klik om dashboardscreenshots te bekijken
+Click to expand tech stack details
-| Pagina | Schermafbeelding | -| --------------------- | ------------------------------------------------- | -| **Aanbieders** |  | -| **Combo's** |  | -| **Analytics** |  | -| **Gezondheid** |  | -| **Vertaler** |  | -| **Instellingen** |  | -| **CLI-hulpmiddelen** |  | -| **Gebruikslogboeken** |  | -| **Eindpunt** |  | +- **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**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions) +- **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
- Gebouwd met ❤️ voor ontwikkelaars die 24/7 coderen
+ Built with ❤️ for developers who code 24/7
omniroute.online
+
diff --git a/docs/i18n/nl/docs/FEATURES.md b/docs/i18n/nl/docs/FEATURES.md
new file mode 100644
index 0000000000..e5ec5b8073
--- /dev/null
+++ b/docs/i18n/nl/docs/FEATURES.md
@@ -0,0 +1,145 @@
+# OmniRoute — Dashboard Features Gallery (Nederlands)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/FEATURES.md) · 🇪🇸 [es](../../es/docs/FEATURES.md) · 🇫🇷 [fr](../../fr/docs/FEATURES.md) · 🇩🇪 [de](../../de/docs/FEATURES.md) · 🇮🇹 [it](../../it/docs/FEATURES.md) · 🇷🇺 [ru](../../ru/docs/FEATURES.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FEATURES.md) · 🇯🇵 [ja](../../ja/docs/FEATURES.md) · 🇰🇷 [ko](../../ko/docs/FEATURES.md) · 🇸🇦 [ar](../../ar/docs/FEATURES.md) · 🇮🇳 [in](../../in/docs/FEATURES.md) · 🇹🇭 [th](../../th/docs/FEATURES.md) · 🇻🇳 [vi](../../vi/docs/FEATURES.md) · 🇮🇩 [id](../../id/docs/FEATURES.md) · 🇲🇾 [ms](../../ms/docs/FEATURES.md) · 🇳🇱 [nl](../../nl/docs/FEATURES.md) · 🇵🇱 [pl](../../pl/docs/FEATURES.md) · 🇸🇪 [sv](../../sv/docs/FEATURES.md) · 🇳🇴 [no](../../no/docs/FEATURES.md) · 🇩🇰 [da](../../da/docs/FEATURES.md) · 🇫🇮 [fi](../../fi/docs/FEATURES.md) · 🇵🇹 [pt](../../pt/docs/FEATURES.md) · 🇷🇴 [ro](../../ro/docs/FEATURES.md) · 🇭🇺 [hu](../../hu/docs/FEATURES.md) · 🇧🇬 [bg](../../bg/docs/FEATURES.md) · 🇸🇰 [sk](../../sk/docs/FEATURES.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FEATURES.md) · 🇮🇱 [he](../../he/docs/FEATURES.md) · 🇵🇭 [phi](../../phi/docs/FEATURES.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FEATURES.md)
+
+---
+
+Visual guide to every section of the OmniRoute dashboard.
+
+---
+
+## 🔌 Providers
+
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
+
+
+
+---
+
+## 🎨 Combos
+
+Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
+
+
+
+---
+
+## 📊 Analytics
+
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
+
+
+
+---
+
+## 🏥 System Health
+
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+
+
+
+---
+
+## 🔧 Translator Playground
+
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
+
+
+
+---
+
+## 🎮 Model Playground _(v2.0.9+)_
+
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
+
+---
+
+## 🎨 Themes _(v2.0.5+)_
+
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
+
+## ⚙️ Settings
+
+Comprehensive settings panel with tabs:
+
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning
+- **Advanced** — Configuration overrides
+
+
+
+---
+
+## 🔧 CLI Tools
+
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
+
+
+
+---
+
+## 🤖 CLI Agents _(v2.0.11+)_
+
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
+
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
+
+---
+
+## 🖼️ Media _(v2.0.3+)_
+
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
+
+## 📝 Request Logs
+
+Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
+
+
+
+---
+
+## 🌐 API Endpoint
+
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
+
+
+
+---
+
+## 🔑 API Key Management
+
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
+
+---
+
+## 📋 Audit Log
+
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
+
+---
+
+## 🖥️ Desktop Application
+
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
+
+Key features:
+
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
+
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.
diff --git a/docs/i18n/no/README.md b/docs/i18n/no/README.md
index a7eae274a0..2806587a15 100644
--- a/docs/i18n/no/README.md
+++ b/docs/i18n/no/README.md
@@ -1,24 +1,94 @@
-omniroute.online
-
-
- # 🚀 OmniRoute — Den gratis AI-gatewayen
+# 🚀 OmniRoute — The Free AI Gateway (Norsk)
-### Slutt aldri å kode. Smart ruting til **GRATIS og rimelige AI-modeller** med automatisk fallback.
-
-_Din universelle API-proxy – ett endepunkt, 36+ leverandører, null nedetid._
-
-**Chatfullføringer • Innebygginger • Bildegenerering • Lyd • Omrangering • 100 % TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Gratis AI-leverandør for dine favorittkodeagenter
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Koble til ethvert AI-drevet IDE- eller CLI-verktøy gjennom OmniRoute – gratis API-gateway for ubegrenset koding._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+` tags no longer leak to clients in SSE streaming responses (#585) |
+| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with per-provider/account quota enforcement, idempotency, SHA-256 storage, and optional GitHub issue reporting |
+| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG → generic fallback chain |
+| 🔄 **Model Auto-Sync** | 24h scheduler and manual UI toggle to sync model lists for built-in and custom OpenAI-compatible providers |
+| 🌐 **OpenCode Zen/Go** | Two new providers from @kang-heewon via PR #530: free tier + subscription tier via `OpencodeExecutor` |
+| 🐛 **Gemini CLI OAuth** | Actionable error when `GEMINI_OAUTH_CLIENT_SECRET` is missing in Docker (was cryptic Google error) |
+| 🐛 **OpenCode config** | `saveOpenCodeConfig()` now correctly writes TOML to `XDG_CONFIG_HOME` |
+| 🐛 **Pinned model override** | `body.model` correctly set to `pinnedModel` on context-cache protection |
+| 🐛 **Codex/Claude loop** | `tool_result` blocks now converted to text to stop infinite loops |
+| 🐛 **Login redirect** | Login no longer freezes after skipping password setup |
+| 🐛 **Windows paths** | MSYS2/Git-Bash paths (`/c/...`) normalized to `C:\...` automatically |
+
+---
+
+## 🖼️ Main Dashboard
+
+
-📡 Alle agenter kobler til via ` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**Stop wasting money and hitting limits:**
-### 🆕 What's New in v3.0.0
+- Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**OmniRoute solves this:**
+
+- ✅ **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
+- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool
---
-[](https://www.npmjs.com/package/omniroute)
-[](https://hub.docker.com/r/diegosouzapw/omniroute)
-[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
-[](https://omniroute.online)
-[](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
+## 📧 Support
-[🌐 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)
+> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.
-🌐 **Available in:** 🇺🇸 [English](../../README.md) | 🇧🇷 [Português (Brasil)](../pt-BR/README.md) | 🇪🇸 [Español](../es/README.md) | 🇫🇷 [Français](../fr/README.md) | 🇮🇹 [Italiano](../it/README.md) | 🇷🇺 [Русский](../ru/README.md) | 🇨🇳 [中文 (简体)](../zh-CN/README.md) | 🇩🇪 [Deutsch](../de/README.md) | 🇮🇳 [हिन्दी](../in/README.md) | 🇹🇭 [ไทย](../th/README.md) | 🇺🇦 [Українська](../uk-UA/README.md) | 🇸🇦 [العربية](../ar/README.md) | 🇯🇵 [日本語](../ja/README.md) | 🇻🇳 [Tiếng Việt](../vi/README.md) | 🇧🇬 [Български](../bg/README.md) | 🇩🇰 [Dansk](../da/README.md) | 🇫🇮 [Suomi](../fi/README.md) | 🇮🇱 [עברית](../he/README.md) | 🇭🇺 [Magyar](../hu/README.md) | 🇮🇩 [Bahasa Indonesia](../id/README.md) | 🇰🇷 [한국어](../ko/README.md) | 🇲🇾 [Bahasa Melayu](../ms/README.md) | 🇳🇱 [Nederlands](../nl/README.md) | 🇳🇴 [Norsk](../no/README.md) | 🇵🇹 [Português (Portugal)](../pt/README.md) | 🇷🇴 [Română](../ro/README.md) | 🇵🇱 [Polski](../pl/README.md) | 🇸🇰 [Slovenčina](../sk/README.md) | 🇸🇪 [Svenska](../sv/README.md) | 🇵🇭 [Filipino](../phi/README.md)
-
-
-
----
-
-## 🖼️
-
-
-
- # 🚀 OmniRoute — Den gratis AI-gatewayen
+# 🚀 OmniRoute — The Free AI Gateway (Norsk)
-### Slutt aldri å kode. Smart ruting til **GRATIS og rimelige AI-modeller** med automatisk fallback.
-
-_Din universelle API-proxy – ett endepunkt, 36+ leverandører, null nedetid._
-
-**Chatfullføringer • Innebygginger • Bildegenerering • Lyd • Omrangering • 100 % TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Gratis AI-leverandør for dine favorittkodeagenter
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Koble til ethvert AI-drevet IDE- eller CLI-verktøy gjennom OmniRoute – gratis API-gateway for ubegrenset koding._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+
+
+[](https://www.npmjs.com/package/omniroute)
+[](https://www.npmjs.com/package/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
+[](https://omniroute.online)
+[](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)
+
+
+
+🌐 **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)
+
+---
+
+## 🆕 What's New in v3.0.0
+
+> **Upgrading from v2.9.5?** — See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes.
+
+| Area | Change |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection remediation |
+| ✅ **Route Validation** | All 176 API routes now validated with Zod schemas + `validateBody()` — CI `check:route-validation:t06` passes |
+| 🐛 **omniModel Tag Leak** | Internal `
+
+
+
+---
+
+## 📸 Dashboard Preview
+
+
+
+
+
+---
+
+### 🤖 Free AI Provider for your favorite coding agents
+
+_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._
Click to see dashboard screenshots
+ +| Page | Screenshot | +| -------------- | ------------------------------------------------- | +| **Providers** |  | +| **Combos** |  | +| **Analytics** |  | +| **Health** |  | +| **Translator** |  | +| **Settings** |  | +| **CLI Tools** |  | +| **Usage Logs** |  | +| **Endpoints** |  | + +|
-
+
OpenClaw @@ -92,113 +162,52 @@ _Koble til ethvert AI-drevet IDE- eller CLI-verktøy gjennom OmniRoute – grati |
http://localhost:20128/v1 eller http://cloud.omniroute.online/v1, —limited one models_245 kvote
+📡 All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 — one config, unlimited models and quota
---
-### 🆕 What's New in v3.0.0
+## 🤔 Why OmniRoute?
-| Area | Change |
-| ------------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal ` Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `
-
-
-
----
-
-## 📸
-
-
-
-
-
----
-
-## 🤔 Hvorfor OmniRoute?
-
-**Slutt å kaste bort penger og nå grensene:**
-
-- ...
- -| # | # | -| ----- | ---------------------------------------- | -| **1** |  | -| **2** |  | -| **3** |  | -| **4** |  | -| **5** |  | -| **6** |  | -| **7** |  | -| **8** |  | -| **9** |  | - - Abonnementskvoten utløper ubrukt hver måned
-- Takstgrenser stopper deg med midtkoding
-- Dyre APIer ($20–50/måned per leverandør)
-- Manuell veksling mellom tilbydere
-
-**OmniRoute løser dette:**
-
-- ✅ **Maksimer abonnementer** - Spor kvote, bruk hver bit før tilbakestilling
-- ✅ **Automatisk fallback** - Abonnement → API-nøkkel → Billig → Gratis, null nedetid
-- ✅ **Multi-konto** - Round-robin mellom kontoer per leverandør
-- ✅ **Universal** - Fungerer med Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, hvilket som helst CLI-verktøy
-
----
-
-## 📧 Støtte
-
-> 💬 **Bli med i fellesskapet vårt!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Få hjelp, del tips og hold deg oppdatert.
-
-- **Nettsted**: [omniroute.online](https://omniroute.online)
+- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Problemer**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Originalt prosjekt**: [9router by decolua](https://github.com/decolua/9router)
+- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 Hvordan det fungerer
+## 🔄 How It Works
```
┌─────────────┐
@@ -227,451 +236,453 @@ Result: Never stop coding, minimal cost
---
-## 🎯 Hva OmniRoute løser — 30 ekte smertepoeng og brukstilfeller
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **Hver utviklere som bruker AI-verktøy møter disse problemene daglig.** OmniRoute ble bygget for å løse dem alle – fra kostnadsoverskridelser til regionale blokker, fra ødelagte OAuth-flyter til protokolloperasjoner og observerbarhet i bedrifter.
+> **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.
-
💸 1. "Jeg betaler for et dyrt abonnement, men blir fortsatt avbrutt av grenser"
+💸 1. "I pay for an expensive subscription but still get interrupted by limits"
-Utviklere betaler $20–200/måned for Claude Pro, Codex Pro eller GitHub Copilot. Selv om du betaler, har kvoten et tak – 5 timers bruk, ukentlige grenser eller rategrenser per minutt. Midtkodingsøkt, leverandøren slutter å svare og utvikleren mister flyt og produktivitet. +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. -**Hvordan OmniRoute løser det:** +**How OmniRoute solves it:** -- **Smart 4-lags fallback** — Hvis abonnementskvoten går tom, omdirigeres automatisk til API-nøkkel → Billig → Gratis med null manuell intervensjon -- **Sanntidskvotesporing** — Viser tokenforbruk i sanntid med tilbakestilt nedtelling (5 timer, daglig, ukentlig) -- **Støtte for flere kontoer** - Flere kontoer per leverandør med automatisk round-robin - når en går tom, bytter du til den neste -- **Egendefinerte kombinasjoner** — Tilpassbare reservekjeder med 6 balansestrategier (fyll først, round-robin, P2C, tilfeldig, minst brukt, kostnadsoptimalisert) -- **Codex Business Quotas** — Overvåking av bedrifts-/teamarbeidsområdekvoter direkte i dashbordet +- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention +- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly) +- **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 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
-`-blokker fra modeller som DeepSeek R1 til standardiserte `reasoning_content`
-- **Structured Output for Gemini** — `json_schema` → `responseMimeType`/`responseSchema` automatisk konvertering
-- **`stream` er standard til `false`** — Justerer med OpenAI-spesifikasjoner, og unngår uventet SSE i Python/Rust/Go SDK-er
+- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 67+ 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
🔌 2. "Jeg trenger å bruke flere leverandører, men hver av dem har en annen API"
+🔌 2. "I need to use multiple providers but each has a different API"
-OpenAI bruker ett format, Claude (Anthropic) bruker et annet, Gemini enda et annet. Hvis en utvikler ønsker å teste modeller fra forskjellige leverandører eller fallback mellom dem, må de rekonfigurere SDK-er, endre endepunkter, håndtere inkompatible formater. Tilpassede leverandører (FriendLI, NIM) har ikke-standardmodellende endepunkter. +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. -**Hvordan OmniRoute løser det:** +**How OmniRoute solves it:** -- **Unified Endpoint** - En enkelt `http://localhost:20128/v1` fungerer som proxy for alle 36+ leverandører -- **Formatoversettelse** — Automatisk og gjennomsiktig: OpenAI ↔ Claude ↔ Gemini ↔ Responses API -- **Responsrensing** — Fjerner ikke-standardfelter (`x_groq`, `usage_breakdown`, `service_tier`) som bryter OpenAI SDK v1.83+ -- **Rollenormalisering** — Konverterer `developer` → `system` for ikke-OpenAI-leverandører; `system` → `user` for GLM/ERNIE -- **Think Tag Extraction** — Trekker ut `
-
🌐 3. "Min AI-leverandør blokkerer min region/land"
+🌐 3. "My AI provider blocks my region/country"
-Leverandører som OpenAI/Codex blokkerer tilgang fra visse geografiske områder. Brukere får feil som `unsupported_country_region_territory` under OAuth- og API-tilkoblinger. Dette er spesielt frustrerende for utviklere fra utviklingsland. +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. -**Hvordan OmniRoute løser det:** +**How OmniRoute solves it:** -- **3-Level Proxy Config** — Konfigurerbar proxy på 3 nivåer: global (all trafikk), per leverandør (kun én leverandør) og per tilkobling/nøkkel -- **Fargekodede proxy-merker** — Visuelle indikatorer: 🟢 global proxy, 🟡 leverandørproxy, 🔵 tilkoblings proxy, viser alltid IP -- **OAuth-tokenutveksling gjennom proxy** - OAuth-flyt går også gjennom proxyen, og løser `unsupported_country_region_territory` -- **Test av tilkobling via proxy** — Tilkoblingstester bruker den konfigurerte proxyen (ikke mer direkte forbikobling) -- **SOCKS5-støtte** — Full SOCKS5-proxystøtte for utgående ruting -- **TLS-fingeravtrykkspoofing** — Nettleserlignende TLS-fingeravtrykk via `wreq-js` for å omgå botdeteksjon +- **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
-` prefix
-- **Kun gratis kombinasjoner** — Kjede `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/måned med null nedetid
-- **NVIDIA NIM gratis kreditter** — 1000 gratis kreditter integrert
-- **Kostnadsoptimalisert strategi** — Rutingstrategi som automatisk velger den billigste tilgjengelige leverandøren
+- **Free-Only Combos** — Chain `gc/gemini-3-flash → 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
🆓 4. "Jeg vil bruke AI for koding, men jeg har ingen penger"
+🆓 4. "I want to use AI for coding but I have no money"
-Ikke alle kan betale $20–200 per måned for AI-abonnementer. Studenter, utviklere fra fremvoksende land, hobbyfolk og frilansere trenger tilgang til kvalitetsmodeller uten kostnad. +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. -**Hvordan OmniRoute løser det:** +**How OmniRoute solves it:** -- **Gratis-tilbydere innebygd** — Innebygd støtte for 100 % gratisleverandører: iFlow (8 ubegrensede modeller), Qwen (3 ubegrensede modeller), Kiro (Claude gratis), Gemini CLI (180K/mnd gratis) +- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free) - **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/
-
🔒 5. "Jeg trenger å beskytte AI-gatewayen min mot uautorisert tilgang"
+🔒 5. "I need to protect my AI gateway from unauthorized access"
-Når du eksponerer en AI-gateway til nettverket (LAN, VPS, Docker), kan alle med adressen konsumere utviklerens tokens/kvote. Uten beskyttelse er API-er sårbare for misbruk, umiddelbar injeksjon og misbruk. +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. -**Hvordan OmniRoute løser det:** +**How OmniRoute solves it:** -- **API Key Management** — Generering, rotasjon og scoping per leverandør med en dedikert `/dashboard/api-manager`-side -- **Tillatelser på modellnivå** — Begrens API-nøkler til spesifikke modeller (`openai/*`, jokertegnmønstre), med Tillat alt/begrens -- **API Endpoint Protection** — Krev en nøkkel for `/v1/models` og blokker spesifikke leverandører fra oppføringen -- **Auth Guard + CSRF Protection** — Alle dashbordruter beskyttet med `withAuth` mellomvare + CSRF-tokens -- **Rate Limiter** — Per-IP ratebegrensning med konfigurerbare vinduer -- **IP-filtrering** — Tillatelsesliste/blokkeringsliste for tilgangskontroll -- **Prompt Injection Guard** — Sanitisering mot ondsinnede spørsmålsmønstre -- **AES-256-GCM-kryptering** — Legitimasjon kryptert i hvile +- **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. «Tilbyderen min gikk ned og jeg mistet kodeflyten min»
+🛑 6. "My provider went down and I lost my coding flow"
-AI-leverandører kan bli ustabile, returnere 5xx-feil eller nå midlertidige hastighetsgrenser. Hvis en utvikler er avhengig av en enkelt leverandør, blir de avbrutt. Uten strømbrytere kan gjentatte forsøk krasje applikasjonen. +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. -**Hvordan OmniRoute løser det:** +**How OmniRoute solves it:** -- **Circuit Breaker per leverandør** — Automatisk åpning/lukking med konfigurerbare terskler og nedkjøling (Lukket/Åpen/HalvÅpen) -- **Eksponentiell backoff** — Progressive forsinkelser på nytt forsøk -- **Anti-tordenflokk** — Mutex + semaforbeskyttelse mot samtidige stormer på nytt forsøk -- **Combo Fallback Chains** — Hvis primærleverandøren mislykkes, faller den automatisk gjennom kjeden uten inngrep -- **Combo Circuit Breaker** - Deaktiverer sviktende leverandører automatisk i en kombinasjonskjede -- **Helsedashbord** — Oppetidsovervåking, strømbrytertilstander, sperringer, cachestatistikk, p50/p95/p99 latency +- **Circuit Breaker per-model** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks +- **Exponential Backoff** — Progressive retry delays +- **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 +- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain +- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
-
🔧 7. "Å konfigurere hvert AI-verktøy er kjedelig og repeterende"
+🔧 7. "Configuring each AI tool is tedious and repetitive"
-Utviklere bruker Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Hvert verktøy trenger en annen konfigurasjon (API-endepunkt, nøkkel, modell). Å konfigurere på nytt når du bytter leverandør eller modell er bortkastet tid. +Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time. -**Hvordan OmniRoute løser det:** +**How OmniRoute solves it:** -- **CLI Tools Dashboard** — Dedikert side med ett-klikksoppsett for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline -- **GitHub Copilot Config Generator** — Genererer `chatLanguageModels.json` for VS-kode med bulkmodellvalg -- **Onboarding Wizard** — Veiledet 4-trinns oppsett for førstegangsbrukere -- **Ett endepunkt, alle modeller** — Konfigurer `http://localhost:20128/v1` én gang, få tilgang til 36+ leverandører +- **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 67+ providers
-
🔑 8. "Å administrere OAuth-tokens fra flere leverandører er et helvete"
+🔑 8. "Managing OAuth tokens from multiple providers is hell"
-Claude Code, Codex, Gemini CLI, Copilot – alle bruker OAuth 2.0 med tokens som utløper. Utviklere må re-autentisere hele tiden, håndtere `client_secret is missing`, `redirect_uri_mismatch` og feil på eksterne servere. OAuth på LAN/VPS er spesielt problematisk. +Claude Code, Codex, Gemini CLI, 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. -**Hvordan OmniRoute løser det:** +**How OmniRoute solves it:** -- **Automatisk oppdatering av token** — OAuth-tokener oppdateres i bakgrunnen før utløp -- **OAuth 2.0 (PKCE) innebygd** — Automatisk flyt for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow -- **Multi-Account OAuth** - Flere kontoer per leverandør via JWT/ID-tokenutvinning -- **OAuth LAN/Remote Fix** — Privat IP-deteksjon for `redirect_uri` + manuell URL-modus for eksterne servere -- **OAuth Behind Nginx** — Bruker `window.location.origin` for omvendt proxy-kompatibilitet -- **Remote OAuth Guide** — Trinn-for-trinn-veiledning for Google Cloud-legitimasjon på VPS/Docker +- **Auto Token Refresh** — OAuth tokens refresh in background before expiration +- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow +- **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. "Jeg vet ikke hvor mye jeg bruker eller hvor"
+📊 9. "I don't know how much I'm spending or where"
-Utviklere bruker flere betalte leverandører, men har ikke noe enhetlig syn på utgifter. Hver leverandør har sitt eget faktureringsdashbord, men det er ingen konsolidert visning. Uventede kostnader kan hope seg opp. +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. -**Hvordan OmniRoute løser det:** +**How OmniRoute solves it:** -- **Dashboard for kostnadsanalyse** — Kostnadssporing per token og budsjettadministrasjon per leverandør - – **Budsjettgrenser per nivå** – Utgiftstak per nivå som utløser automatisk fallback -- **Priskonfigurasjon per modell** — Konfigurerbare priser per modell -- **Bruksstatistikk per API-nøkkel** — Antall forespørsler og sist brukte tidsstempel per nøkkel -- **Analytics Dashboard** — Statistiske kort, modellbruksdiagram, leverandørtabell med suksessrater og latens +- **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. "Jeg kan ikke diagnostisere feil og problemer i AI-anrop"
+🐛 10. "I can't diagnose errors and problems in AI calls"
-Når et anrop mislykkes, vet ikke utvikleren om det var en takstgrense, utløpt token, feil format eller leverandørfeil. Fragmenterte logger på tvers av forskjellige terminaler. Uten observerbarhet er feilsøking prøving og feiling. +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. -**Hvordan OmniRoute løser det:** +**How OmniRoute solves it:** -- **Unified Logs Dashboard** — 4 faner: Forespørselslogger, proxy-logger, revisjonslogger, konsoll -- **Console Log Viewer** — Viser i sanntid i terminalstil med fargekodede nivåer, automatisk rulling, søk, filter -- **SQLite Proxy Logger** — Vedvarende logger som overlever serverstarter -- **Translator Playground** — 4 feilsøkingsmoduser: Playground (formatoversettelse), Chat Tester (tur-retur), Test Bench (batch), Live Monitor (sanntid) -- **Request Telemetri** — p50/p95/p99 latens + X-Request-Id-sporing -- **Filbasert logging med rotasjon** — Konsollinterceptor fanger opp alt til JSON-logg med størrelsesbasert rotasjon +- **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 Proxy Logs** — Persistent logs that survive server restarts +- **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 Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation +- **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. "Deployering og vedlikehold av gatewayen er kompleks"
+🏗️ 11. "Deploying and maintaining the gateway is complex"
-Installering, konfigurering og vedlikehold av en AI-proxy på tvers av forskjellige miljøer (lokalt, VPS, Docker, sky) er arbeidskrevende. Problemer som hardkodede baner, `EACCES` på kataloger, portkonflikter og kryssplattformbygg gir friksjon. +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. -**Hvordan OmniRoute løser det:** +**How OmniRoute solves it:** -- **npm global installasjon** — `npm install -g omniroute && omniroute` — ferdig +- **npm global install** — `npm install -g omniroute && omniroute` — done - **Docker Multi-Platform** — AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi) -- **Docker Compose-profiler** — `base` (ingen CLI-verktøy) og `cli` (med Claude Code, Codex, OpenClaw) -- **Electron Desktop App** — Innebygd app for Windows/macOS/Linux med systemstatusfelt, automatisk start, offline-modus -- **Split-Port Mode** — API og Dashboard på separate porter for avanserte scenarier (omvendt proxy, containernettverk) -- **Cloud Sync** — Konfigurer synkronisering på tvers av enheter via Cloudflare Workers -- **DB-sikkerhetskopier** — Automatisk sikkerhetskopiering, gjenoppretting, eksport og import av alle innstillinger +- **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
-
🌍 12. "Grensesnittet er kun engelsk, og teamet mitt snakker ikke engelsk"
+🌍 12. "The interface is English-only and my team doesn't speak English"
-Lag i ikke-engelsktalende land, spesielt i Latin-Amerika, Asia og Europa, sliter med grensesnitt som kun er på engelsk. Språkbarrierer reduserer bruken og øker konfigurasjonsfeil. +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. -**Hvordan OmniRoute løser det:** +**How OmniRoute solves it:** -- **Dashboard i18n — 30 språk** — Alle 500+ nøkler oversatt, inkludert arabisk, bulgarsk, dansk, tysk, spansk, finsk, fransk, hebraisk, hindi, ungarsk, indonesisk, italiensk, japansk, koreansk, malaysisk, nederlandsk, norsk, polsk, portugisisk (PT/BR), rumensk, russisk, ukrainsk, ukrainsk, kinesisk, engelsk, kinesisk, ukrainsk, kinesisk, ukrainsk, kinesisk, ukrainsk, kinesisk, ukrainsk, kinesisk -- **RTL-støtte** — Høyre-til-venstre-støtte for arabisk og hebraisk -- **Multi-Language READMEs** - 30 komplette dokumentasjonsoversettelser -- **Språkvelger** — Globusikon i overskriften for sanntidsbytte +- **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. "Jeg trenger mer enn chat — jeg trenger innebygginger, bilder, lyd"
+🔄 13. "I need more than chat — I need embeddings, images, audio"
-AI er ikke bare fullføring av chat. Utviklere må generere bilder, transkribere lyd, lage innbygginger for RAG, omrangere dokumenter og moderere innhold. Hver API har et annet endepunkt og format. +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. -**Hvordan OmniRoute løser det:** +**How OmniRoute solves it:** -- **Innbygging** — `/v1/embeddings` med 6 leverandører og 9+ modeller -- **Bildegenerering** — `/v1/images/generations` med 10 leverandører og 20+ modeller (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI) -- **Tekst-til-video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) og SD WebUI -- **Tekst-til-musikk** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen) -- **Lydtranskripsjon** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3 -- **Tekst-til-tale** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, Inworld, Cartesia, PlayHT, + eksisterende leverandører -- **Moderasjoner** — `/v1/moderations` — Innholdssikkerhetssjekker -- **Rerangering** — `/v1/rerank` — Rerangering av dokumentrelevans -- **Responses API** — Full `/v1/responses`-støtte for Codex +- **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. "Jeg har ingen måte å teste og sammenligne kvalitet på tvers av modeller"
+🧪 14. "I have no way to test and compare quality across models"
-Utviklere ønsker å vite hvilken modell som er best for deres brukssituasjon – kode, oversettelse, resonnement – men det går tregt å sammenligne manuelt. Det finnes ingen integrerte evalueringsverktøy. +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. -**Hvordan OmniRoute løser det:** +**How OmniRoute solves it:** -- **LLM-evalueringer** — Gyldent sett-testing med 10 forhåndslastede tilfeller som dekker hilsener, matematikk, geografi, kodegenerering, JSON-overholdelse, oversettelse, nedskrivning, sikkerhetsavslag -- **4 matchstrategier** — `exact`, `contains`, `regex`, `custom` (JS-funksjon) -- **Translator Playground Test Bench** — Batchtesting med flere innganger og forventede utganger, sammenligning på tvers av leverandører -- **Chattetester** — Full rundtur med visuell responsgjengivelse -- **Live Monitor** — Sanntidsstrøm av alle forespørsler som strømmer gjennom proxyen +- **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. "Jeg trenger å skalere uten å miste ytelse"
+📈 15. "I need to scale without losing performance"
-Når forespørselsvolumet vokser, genererer de samme spørsmålene dupliserte kostnader uten å bufre. Uten idempotens, dupliserte forespørsler om avfallsbehandling. Satsgrenser per leverandør må respekteres. +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. -**Hvordan OmniRoute løser det:** +**How OmniRoute solves it:** -- **Semantisk hurtigbuffer** — To-lags cache (signatur + semantisk) reduserer kostnader og ventetid -- **Request Idempotency** — 5s dedupliseringsvindu for identiske forespørsler -- **Deteksjon av hastighetsgrense** - RPM per leverandør, minimum gap og maksimal samtidig sporing -- **Redigerbare frekvensgrenser** — Konfigurerbare standardinnstillinger i Innstillinger → Motstandsdyktighet med utholdenhet -- **API Key Validation Cache** — 3-lags cache for produksjonsytelse -- **Helsedashbord med telemetri** — p50/p95/p99-forsinkelse, hurtigbufferstatistikk, oppetid +- **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 +- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence +- **API Key Validation Cache** — 3-tier cache for production performance +- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
-
🤖 16. "Jeg vil kontrollere modellatferd globalt"
+🤖 16. "I want to control model behavior globally"
-Utviklere som vil ha alle svar på et spesifikt språk, med en bestemt tone, eller som ønsker å begrense resonnement-tokens. Å konfigurere dette i hvert verktøy/hver forespørsel er upraktisk. +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. -**Hvordan OmniRoute løser det:** +**How OmniRoute solves it:** -- **System Prompt Injection** — Global forespørsel brukt på alle forespørsler +- **System Prompt Injection** — Global prompt applied to all requests - **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive) -- **6 rutingstrategier** — Globale strategier som bestemmer hvordan forespørsler distribueres -- **Wildcard-ruter** — `provider/*`-mønstre ruter dynamisk til enhver leverandør -- **Kombo aktiver/deaktiver veksle** — Veksle kombinasjoner direkte fra dashbordet -- **Tilkobling av leverandør** — Aktiver/deaktiver alle tilkoblinger for en leverandør med ett klikk -- **Blokkerte leverandører** — Ekskluder spesifikke leverandører fra `/v1/models`-oppføringen +- **6 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 +- **Provider Toggle** — Enable/disable all connections for a provider with one click +- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
-
🧰 17. "Jeg trenger MCP-verktøy som førsteklasses produktegenskaper"
+🧰 17. "I need MCP tools as first-class product capabilities"
-Mange AI-gatewayer avslører MCP bare som en skjult implementeringsdetalj. Team trenger et synlig, håndterbart driftslag. +Many AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer. -**Hvordan OmniRoute løser det:** +**How OmniRoute solves it:** -- MCP vises i dashbordnavigasjons- og endepunktprotokollfanen -- Dedikert MCP-administrasjonsside med prosess, verktøy, omfang og revisjon -- Innebygd hurtigstart for `omniroute --mcp` og klient onboarding +- 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. "Jeg trenger A2A-orkestrering med synkronisering + strømoppgavestier"
+🧠 18. "I need A2A orchestration with sync + stream task paths"
-Agentarbeidsflyter trenger både direkte svar og langvarig strømmet utførelse med livssykluskontroll. +Agent workflows need both direct replies and long-running streamed execution with lifecycle control. -**Hvordan OmniRoute løser det:** +**How OmniRoute solves it:** -- A2A JSON-RPC-endepunkt (`POST /a2a`) med `message/send` og `message/stream` -- SSE-streaming med forplantning av terminaltilstand -- Oppgavelivssyklus-APIer for `tasks/get` og `tasks/cancel` +- 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. "Jeg trenger ekte MCP-prosesshelse, ikke gjettet status"
+🛰️ 19. "I need real MCP process health, not guessed status"
-Operasjonelle team må vite om MCP faktisk er i live, ikke bare om en API er tilgjengelig. +Operational teams need to know if MCP is actually alive, not just whether an API is reachable. -**Hvordan OmniRoute løser det:** +**How OmniRoute solves it:** -- Runtime hjerteslag-fil med PID, tidsstempler, transport, verktøytelling og omfangsmodus -- MCP status API som kombinerer hjerteslag + nylig aktivitet -- UI-statuskort for prosess/oppetid/hjerteslag +- 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. "Jeg trenger reviderbar MCP-verktøykjøring"
+📋 20. "I need auditable MCP tool execution"
-Når verktøy muterer konfigurasjon eller utløser operasjonshandlinger, trenger teamene rettsmedisinsk sporbarhet. +When tools mutate config or trigger ops actions, teams need forensic traceability. -**Hvordan OmniRoute løser det:** +**How OmniRoute solves it:** -- SQLite-støttet revisjonslogging for MCP-verktøykall -- Filtrerer etter verktøy, suksess/fiasko, API-nøkkel og paginering -- Dashboard revisjonstabell + statistikkendepunkter for automatisering +- 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. "Jeg trenger scoped MCP-tillatelser per integrasjon"
+🔐 21. "I need scoped MCP permissions per integration"
-Ulike klienter bør ha minst privilegert tilgang til verktøykategorier. +Different clients should have least-privilege access to tool categories. -**Hvordan OmniRoute løser det:** +**How OmniRoute solves it:** -- 9 granulære MCP-skoper for kontrollert verktøytilgang -- Håndhevelse av omfang og synlighet i MCP-administrasjonsgrensesnittet -- Sikker standardstilling for operativt verktøy +- 9 granular MCP scopes for controlled tool access +- Scope enforcement and visibility in MCP management UI +- Safe default posture for operational tooling
-
⚙️ 22. "Jeg trenger operasjonelle kontroller uten å omdistribuere"
+⚙️ 22. "I need operational controls without redeploying"
-Lag trenger raske endringer i kjøretiden under hendelser eller kostnadshendelser. +Teams need quick runtime changes during incidents or cost events. -**Hvordan OmniRoute løser det:** +**How OmniRoute solves it:** -- Bytt kombinasjonsaktivering direkte fra MCP-dashbordet -- Bruk robusthetsprofiler fra forhåndsdefinerte policypakker -- Tilbakestill strømbryterens tilstand fra samme driftspanel +- Switch combo activation directly from MCP dashboard +- Apply resilience profiles from pre-defined policy packs +- Reset circuit breaker state from the same operations panel
-
🔄 23. «I need live A2A task lifecycle synibility and cancellation»
+🔄 23. "I need live A2A task lifecycle visibility and cancellation"
-Uten livssyklussynlighet blir oppgavehendelser vanskelig å triage. +Without lifecycle visibility, task incidents become hard to triage. -**Hvordan OmniRoute løser det:** +**How OmniRoute solves it:** -- Oppgaveliste/filtrering etter tilstand/ferdighet med paginering -- Drill-down på oppgavemetadata, hendelser og artefakter -- Sluttpunkt for kansellering av oppgave og UI-handling med bekreftelse +- 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. «Jeg trenger aktive strømmålinger for A2A-last»
+🌊 24. "I need active stream metrics for A2A load"
-Strømmearbeidsflyter krever operasjonell innsikt i samtidighet og direkteforbindelser. +Streaming workflows require operational insight into concurrency and live connections. -**Hvordan OmniRoute løser det:** +**How OmniRoute solves it:** -- Aktive strømtellere integrert i A2A-status -- Tidsstempel for siste oppgave og antall per stat -- A2A dashbordkort for operasjonsovervåking i sanntid +- Active stream counters integrated into A2A status +- Last task timestamp and per-state counts +- A2A dashboard cards for real-time ops monitoring
-
🪪 25. "Jeg trenger standard agentoppdagelse for klienter"
+🪪 25. "I need standard agent discovery for clients"
-Eksterne klienter og orkestratorer trenger maskinlesbare metadata for onboarding. +External clients and orchestrators need machine-readable metadata for onboarding. -**Hvordan OmniRoute løser det:** +**How OmniRoute solves it:** -- Agentkort eksponert på `/.well-known/agent.json` -- Evner og ferdigheter vist i ledelsens brukergrensesnitt -- A2A status API inkluderer oppdagelsesmetadata for automatisering +- Agent Card exposed at `/.well-known/agent.json` +- Capabilities and skills shown in management UI +- A2A status API includes discovery metadata for automation
-
🧭 26. "Jeg trenger protokolloppdagbarhet i produktets UX"
+🧭 26. "I need protocol discoverability in the product UX"
-Hvis brukere ikke kan oppdage protokolloverflater, faller kvaliteten på adopsjon og støtte. +If users cannot discover protocol surfaces, adoption and support quality drop. -**Hvordan OmniRoute løser det:** +**How OmniRoute solves it:** -- Sidefeltoppføringer for MCP og A2A -- Endpoint-side Protokoller-fane med hurtigstart og status -- Lenker fra oversikt til dedikerte styringsdashboards +- 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. "Jeg trenger ende-til-ende protokollvalidering med ekte klienter"
+🧪 27. "I need end-to-end protocol validation with real clients"
-Mock-tester er ikke nok til å validere protokollkompatibilitet før utgivelse. +Mock tests are not enough to validate protocol compatibility before release. -**Hvordan OmniRoute løser det:** +**How OmniRoute solves it:** -- E2E-suite som starter opp app og bruker ekte MCP SDK-klienttransport -- A2A-klient tester for å oppdage, sende, streame, hente og kansellere flyter -- Krysssjekk påstander mot MCP-revisjon og A2A-oppgave-APIer +- 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. «Jeg trenger enhetlig observerbarhet på tvers av alle grensesnitt»
+📡 28. "I need unified observability across all interfaces"
-Å dele observerbarhet etter protokoll skaper blinde flekker og lengre MTTR. +Splitting observability by protocol creates blind spots and longer MTTR. -**Hvordan OmniRoute løser det:** +**How OmniRoute solves it:** -- Samlede dashboards/logger/analyse i ett produkt -- Helse + revisjon + forespørsel om telemetri på tvers av OpenAI-, MCP- og A2A-lag -- Operasjonelle APIer for status og automatisering +- Unified dashboards/logs/analytics in one product +- Health + audit + request telemetry across OpenAI, MCP, and A2A layers +- Operational APIs for status and automation
-
💼 29. "Jeg trenger én kjøretid for proxy + verktøy + agentorkestrering"
+💼 29. "I need one runtime for proxy + tools + agent orchestration"
-Å kjøre mange separate tjenester øker driftskostnadene og feilmodusene. +Running many separate services increases operational cost and failure modes. -**Hvordan OmniRoute løser det:** +**How OmniRoute solves it:** -- OpenAI-kompatibel proxy, MCP-server og A2A-server i én stabel -- Delt autentisering, robusthet, datalagring og observerbarhet -- Konsekvent policymodell på tvers av alle interaksjonsflater +- 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
-
-### Eksempel på Playbooks (integrerte brukstilfeller)
+### Example Playbooks (Integrated Use Cases)
-**Playbook A: Maksimer betalt abonnement + billig backup**
+**Playbook A: Maximize paid subscription + cheap backup**
```txt
Combo: "maximize-claude"
@@ -683,7 +694,7 @@ Monthly cost: $20 + small backup spend
Outcome: higher quality, near-zero interruption
```
-**Playbook B: Nullkostnadskodestabel**
+**Playbook B: Zero-cost coding stack**
```txt
Combo: "free-forever"
@@ -695,7 +706,7 @@ Monthly cost: $0
Outcome: stable free coding workflow
```
-**Playbook C: 24/7 alltid aktiv reservekjede**
+**Playbook C: 24/7 always-on fallback chain**
```txt
Combo: "always-on"
@@ -708,65 +719,132 @@ Combo: "always-on"
Outcome: deep fallback depth for deadline-critical workloads
```
-**Playbook D: Agentoperasjoner med MCP + A2A**
+**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/mcp and /dashboard/a2a
-4) Control incidents with resilience profile + task cancellation
+3) Observe via /dashboard/endpoint (MCP and A2A tabs)
+4) Toggle services via inline status controls
```
---
-## ⚡ Hurtigstart
+## 🆓 Start Free — Zero Configuration Cost
-**1. Installer globalt:**
+> 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 **iFlow** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |
+| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |
+| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |
+| 5 | `/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).
+
+## Hurtigstart
+
+### 1) Install and run
```bash
npm install -g omniroute
omniroute
```
-🎉 Dashboard åpner kl. `http://localhost:20128`
+> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:
+>
+> ```bash
+> pnpm install -g omniroute
+> pnpm approve-builds -g # Select all packages → approve
+> omniroute
+> ```
-| Kommando | Beskrivelse |
-| ----------------------- | ---------------------------------- |
-| `omniroute` | Start server (standard port 20128) |
-| `omniroute --port 3000` | Bruk tilpasset port |
-| `omniroute --no-open` | Ikke åpne nettleseren automatisk |
-| `omniroute --help` | Vis hjelp |
+Dashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.
-**2. Koble til en GRATIS leverandør:**
+| 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 |
-Dashboard → Leverandører → Koble til **Claude-kode** eller **Antigravity** → OAuth-pålogging → Ferdig!
+Optional split-port mode:
-**3. Bruk i CLI-verktøyet:**
-
-```
-Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Settings:
- Endpoint: http://localhost:20128/v1
- API Key: [copy from dashboard]
- Model: if/kimi-k2-thinking
+```bash
+PORT=20128 DASHBOARD_PORT=20129 omniroute
+# API: http://localhost:20128/v1
+# Dashboard: http://localhost:20129
```
-**Det var det!** Begynn å kode med GRATIS AI-modeller.
+### 2) Connect providers and create your API key
-**Alternativt – kjør fra kilden:**
+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
+
+```txt
+Base URL: http://localhost:20128/v1
+API Key: [copy from Endpoint page]
+Model: if/kimi-k2-thinking (or any provider/model prefix)
+```
+
+Works with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.
+
+### 4) Enable and validate protocols (v2.0)
+
+**MCP (for tool-driven operations):**
+
+```bash
+omniroute --mcp
+```
+
+Then connect your MCP client over `stdio` and test tools like:
+
+- `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 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
+PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev
```
---
## 🐳 Docker
-OmniRoute er tilgjengelig som et offentlig Docker-bilde på [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
+OmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
-**Rask løp:**
+**Quick run:**
```bash
docker run -d \
@@ -777,7 +855,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Med miljøfil:**
+**With environment file:**
```bash
# Copy and edit .env first
@@ -792,7 +870,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Bruke Docker Compose:**
+**Using Docker Compose:**
```bash
# Base profile (no CLI tools)
@@ -802,256 +880,550 @@ docker compose --profile base up -d
docker compose --profile cli up -d
```
-| Bilde | Tag | Størrelse | Beskrivelse |
-| ------------------------ | -------- | --------- | ----------------------- |
-| `diegosouzapw/omniroute` | `latest` | ~250MB | Siste stabile utgivelse |
-| `diegosouzapw/omniroute` | `1.0.3` | ~250MB | Gjeldende versjon |
+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.
+- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.
+- 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` | `1.0.3` | ~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
+### Hurtigstart
+
```bash
-npm run electron:dev # Development mode
+# 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)
+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)
---
-## 💰 Priser på et øyeblikk
+## 💰 Pricing at a Glance
-| Nivå | Leverandør | Kostnad | Kvote Tilbakestill | Best for |
-| ----------------- | ----------------- | ----------------------------- | ----------------------- | -------------------- |
-| **💳 ABONNEMENT** | Claude Code (Pro) | $20/md | 5t + ukentlig | Allerede abonnert |
-| | Codex (Pluss/Pro) | $20-200/md | 5t + ukentlig | OpenAI-brukere |
-| | Gemini CLI | **GRATIS** | 180K/mnd + 1K/dag | Alle sammen! |
-| | GitHub Copilot | $10-19/md | Månedlig | GitHub-brukere |
-| **🔑 API NØKKEL** | NVIDIA NIM | **GRATIS** (1000 studiepoeng) | Engangs | Gratis tier testing |
-| | DeepSeek | Betal per bruk | Ingen | Beste pris/kvalitet |
-| | Groq | Gratis lag + betalt | Begrenset pris | Ultrarask slutning |
-| | xAI (Grok) | Betal per bruk | Ingen | Grok modeller |
-| | Mistral | Gratis lag + betalt | Begrenset pris | Europeisk AI |
-| | OpenRouter | Betal per bruk | Ingen | 100+ modeller |
-| **💰 BILLIG** | GLM-4.7 | $0,6/1M | Daglig 10:00 | Budsjett backup |
-| | MiniMax M2.1 | $0,2/1M | 5-timers rullende | Billigste alternativ |
-| | Kimi K2 | $9/md leilighet | 10 millioner tokens/mnd | Forutsigbar kostnad |
-| **🆓 GRATIS** | iFlow | $0 | Ubegrenset | 8 modeller gratis |
-| | Qwen | $0 | Ubegrenset | 3 modeller gratis |
-| | Kiro | $0 | Ubegrenset | Claude gratis |
+| 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 |
+| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |
+| | 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** | iFlow | **$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 |
-**💡 Profftips:** Start med Gemini CLI (180K gratis/måned) + iFlow (ubegrenset gratis) kombinasjon = $0 kostnad!
+> 🆕 **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
+iFlow (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.
---
-## 💡 Nøkkelfunksjoner
+---
-### 🧠 Kjerneruting og intelligens
+## 🆓 Free Models — What You Actually Get
-| Funksjon | Hva det gjør |
-| ---------------------------------- | ---------------------------------------------------------------------------------------- |
-| 🎯 **Smart 4-lags fallback** | Automatisk rute: Abonnement → API-nøkkel → Billig → Gratis |
-| 📊 **Sanntidskvotesporing** | Live tokenantall + tilbakestilt nedtelling per leverandør |
-| 🔄 **Formatoversettelse** | OpenAI ↔ Claude ↔ Gemini ↔ Markør ↔ Kiro sømløs + respons sanitization |
-| 👥 **Støtte for flere kontoer** | Flere kontoer per leverandør med intelligent utvalg |
-| 🔄 **Auto Token Refresh** | OAuth-tokens oppdateres automatisk med prøv på nytt |
-| 🎨 **Egendefinerte kombinasjoner** | 6 strategier: fyll først, round-robin, p2c, tilfeldig, minst brukt, kostnadsoptimalisert |
-| 🧩 **Egendefinerte modeller** | Legg til hvilken som helst modell-ID til en hvilken som helst leverandør |
-| 🌐 **Wildcard-ruter** | Ruter `provider/*`-mønstre til enhver leverandør dynamisk |
-| 🧠 **Tenkebudsjett** | Passthrough, auto, egendefinerte og adaptive moduser for resonnerende modeller |
-| 🔀 **Model Aliases** | Auto-forward deprecated model IDs to current replacements (built-in + custom) |
-| ⚡ **Background Degradation** | Auto-route background tasks (titles, summaries) to cheaper models |
-| 💬 **Systemprompt-injeksjon** | Global systemforespørsel brukt på alle forespørsler |
-| 📄 **Responses API** | Full støtte for OpenAI Responses API (`/v1/responses`) for Codex |
+> 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.
-### 🎵 Multi-Modal APIer
+### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)
-| Funksjon | Hva det gjør |
-| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 🖼️ **Bildegenerering** | `/v1/images/generations` — 4 leverandører, 9+ modeller |
-| 📐 **Innbygging** | `/v1/embeddings` — 6 leverandører, 9+ modeller |
-| 🎤 **Lydtranskripsjon** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |
-| 🔊 **Tekst-til-tale** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) |
-| 🛡️ **Moderasjoner** | `/v1/moderations` — Innholdssikkerhetssjekker |
-| 🔀 **Omrangering** | `/v1/rerank` — Rerangering av dokumentrelevans |
+| 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 |
-### 🛡️ Spenst og sikkerhet
+### 🟢 IFLOW MODELS (Free OAuth — No Credit Card)
-| Funksjon | Hva det gjør |
-| --------------------------------- | ----------------------------------------------------------------------------- |
-| 🔌 **Circuit Breaker** | Automatisk åpning/lukking per leverandør med konfigurerbare terskler |
-| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |
-| 🛡️ **Anti-tordenflokk** | Mutex + semaforhastighetsgrense for API-nøkkelleverandører |
-| 🧠 **Semantisk cache** | To-lags cache (signatur + semantisk) reduserer kostnader og ventetid |
-| ⚡ **Be om idempotens** | 5s dedup-vindu for dupliserte forespørsler |
-| 🔒 **TLS-fingeravtrykkspoofing** | Omgå TLS-basert botdeteksjon via wreq-js |
-| 🌐 **IP-filtrering** | Tillatelsesliste/blokkeringsliste for API-tilgangskontroll |
-| 📊 **Redigerbare satsgrenser** | Konfigurerbar RPM, min gap og maks samtidig på systemnivå |
-| 💾 **Rate Limit Persistence** | Learned limits survive restarts via SQLite with 60s debounce + 24h staleness |
-| 🔄 **Token Refresh Resilience** | Per-provider circuit breaker (5 fails→30min) + 30s timeout per attempt |
-| 🛡 **API-endepunktbeskyttelse** | Auth-gate + leverandørblokkering for `/models`-endepunktet |
-| 🔒 **Proxy-synlighet** | Fargekodede merker: 🟢 global, 🟡 leverandør, 🔵 per tilkobling med IP-skjerm |
-| 🌐 **3-nivå proxy-konfigurasjon** | Konfigurer proxyer på globalt nivå, per leverandør eller per tilkoblingsnivå |
+| 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 |
-### 📊 Observerbarhet og analyse
+### 🟡 QWEN MODELS (Device Code Auth)
-| Funksjon | Hva det gjør |
-| -------------------------------- | ----------------------------------------------------------------------------------- |
-| 📝 **Be om logging** | Feilsøkingsmodus med fullstendige forespørsels-/svarlogger |
-| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |
-| 💾 **SQLite proxy-logger** | Vedvarende proxy-logger overlever omstart av server |
-| 📊 **Analytics Dashboard** | Recharts-drevet: statistikkkort, modellbruksdiagram, leverandørtabell |
-| 📈 **Fremdriftssporing** | Opt-in SSE-fremdriftshendelser for streaming |
-| 🧪 **LLM-evalueringer** | Gylden sett-testing med 4 kampstrategier |
-| 🔍 **Be om telemetri** | p50/p95/p99 latensaggregering + X-Request-Id-sporing |
-| 📋 **Logger Dashboard** | Samlet side med 4 faner: Forespørselslogger, proxy-logger, revisjonslogger, konsoll |
-| 🖥️ **Konsollloggvisning** | Viser i sanntid i terminalstil med nivåfilter, søk, automatisk rulling |
-| 📑 **Filbasert logging** | Console interceptor fanger opp all utgang til JSON-loggfil med rotasjon |
-| 🏥 **Helse Dashboard** | Systemoppetid, strømbrytertilstander, sperringer, cachestatistikk |
-| 💰 **Kostnadssporing** | Budsjettadministrasjon + priskonfigurasjon per modell |
+| 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) |
-### ☁️ Implementering og synkronisering
+### 🟣 GEMINI CLI (Google OAuth)
-| Funksjon | Hva det gjør |
-| -------------------------------- | ---------------------------------------------------------------------------------------- |
-| 💾 **Cloud Sync** | Synkroniser konfigurasjon på tvers av enheter via Cloudflare Workers |
-| 🌐 **Distribuer hvor som helst** | Localhost, VPS, Docker, Cloudflare Workers |
-| 🔑 **API Key Management** | Generer, roter og omfang API-nøkler per leverandør |
-| 🧙 **Onboarding Wizard** | 4-trinns veiledet oppsett for førstegangsbrukere |
-| 🔧 **CLI Tools Dashboard** | Ett-klikk konfigurer Claude, Codex, Cline, OpenClaw, Kilo, Antigravity |
-| 🔄 **DB-sikkerhetskopier** | Automatisk sikkerhetskopiering, gjenoppretting, eksport og import for alle innstillinger |
-| 🌐 **Internasjonalisering** | Full i18n med neste-intl — støtte for engelsk + portugisisk (Brasil) |
-| 🌍 **Språkvelger** | Globusikon i overskriften for sanntids språkbytte (🇺🇸/🇧🇷) |
-| 🧹 **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 |
-| 📂 **Tilpasset datakatalog** | `DATA_DIR` env var for å overstyre standard `~/.omniroute` lagringsbane |
+| Model | Prefix | Limit | Rate Limit |
+| ------------------------ | ------ | --------------------------- | ------------- |
+| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |
+| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |
+
+### ⚫ 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
+> iFlow (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 v2.0 is built as an operational platform, not just a relay proxy.
+
+### 🆕 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 Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |
+| 🤖 **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 (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) |
+| 🤝 **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** | 9 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 combo, apply resilience profiles, reset breakers from one control surface |
+
+### 🧠 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** | 6 balancing strategies + fallback chain control |
+| 🌐 **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) |
+| 💬 **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 |
+| ----------------------------------- | -------------------------------------------------------------------------------------- |
+| 🔌 **Circuit Breakers** | Per-model trip/recover with threshold controls |
+| 🎯 **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 |
+| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |
+| 🔑 **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 |
+
+### 📊 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 |
+| 📋 **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 |
+
+### ☁️ Deployment & Platform
+
+| Feature | What It Does |
+| ----------------------------- | --------------------------------------------------------- |
+| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |
+| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |
+| 💾 **Cloud Sync** | Configuration sync via cloud worker |
+| 🔄 **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 |
+
+### Feature Deep Dive
+
+#### Smart fallback with practical cost control
+
+```txt
+Combo: "my-coding-stack"
+ 1. cc/claude-opus-4-6
+ 2. nvidia/llama-3.3-70b
+ 3. glm/glm-4.7
+ 4. if/kimi-k2-thinking
+```
+
+When quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.
+
+#### 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)
+
+#### 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)
🚀 30. "Jeg trenger å sende agentiske arbeidsflyter uten limkodespredning"
+🚀 30. "I need to ship agentic workflows without glue-code sprawl"
-Lag mister hastighet når de setter sammen flere ad-hoc-tjenester og skript. +Teams lose velocity when stitching multiple ad-hoc services and scripts. -**Hvordan OmniRoute løser det:** +**How OmniRoute solves it:** -- Enhetlig endepunktstrategi for kunder og agenter -- Innebygde brukergrensesnitt for protokolladministrasjon og røykvalideringsveier -- Produksjonsklare fundamenter (sikkerhet, logging, robusthet, backup) +- Unified endpoint strategy for clients and agents +- Built-in protocol management UIs and smoke validation paths +- Production-ready foundations (security, logging, resilience, backup)
-` blokker → `reasoning_content` for tenkemodeller
-- **Strukturert utgang** — `json_schema` → Gemini's `responseMimeType`/`responseSchema`
-
-### 👥 Støtte for flere kontoer
-
-- Legg til flere kontoer per leverandør
-- Auto round-robin eller prioritetsbasert ruting
-- Tilbakeslag til neste konto når en når kvoten
-
-### 🔄 Automatisk tokenoppdatering
-
-- OAuth-tokens oppdateres automatisk før utløp
-- Ingen manuell re-autentisering nødvendig
-- Sømløs opplevelse på tvers av alle leverandører
-
-### 🎨 Egendefinerte kombinasjoner
-
-- Lag ubegrensede modellkombinasjoner
-- 6 strategier: fyll-først, round-robin, kraft-av-to-valg, tilfeldig, minst brukt, kostnadsoptimalisert
-- Del kombinasjoner på tvers av enheter med Cloud Sync
-
-### 🏥 Helse Dashboard
-
-- Systemstatus (oppetid, versjon, minnebruk)
-- Strømbrytertilstander per leverandør (lukket/åpen/halvåpen)
-- Takstgrensestatus og aktive sperringer
-- Signaturbufferstatistikk
-- Latency-telemetri (p50/p95/p99) + hurtigbuffer
-- Tilbakestill helsestatus med ett klikk
-
-### 🔧 Oversetter Lekeplass
-
-OmniRoute inkluderer en kraftig innebygd oversetterlekeplass med **4 moduser** for feilsøking, testing og overvåking av API-oversettelser:
-
-| Modus | Beskrivelse |
-| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **💻 Lekeplass** | Direkte formatoversettelse – lim inn hvilken som helst API-forespørselstekst og se umiddelbart hvordan OmniRoute oversetter den mellom leverandørformater (OpenAI ↔ Claude ↔ Gemini ↔ Responses API). Inkluderer eksempelmaler og automatisk gjenkjenning av formater. |
-| **💬 Chat Tester** | Send ekte chatteforespørsler gjennom OmniRoute og se hele rundturen: innspillet ditt, den oversatte forespørselen, leverandørens svar og det oversatte svaret tilbake. Uvurderlig for validering av kombinasjonsruting. |
-| **🧪 Testbenk** | Batch-testmodus – definer flere testtilfeller med forskjellige innganger og forventede utganger, kjør dem alle samtidig og sammenlign resultater på tvers av leverandører og modeller. |
-| **📱 Live Monitor** | Sanntidsovervåking av forespørsler – se innkommende forespørsler mens de strømmer gjennom OmniRoute, se formatoversettelser som skjer live, og identifiser problemer umiddelbart. |
-
-**Tilgang:** Dashboard → Oversetter (sidefelt)
-
-### 💾 Cloud Sync
-
-- Synkroniser leverandører, kombinasjoner og innstillinger på tvers av enheter
-- Automatisk bakgrunnssynkronisering
-- Sikker kryptert lagring
+- `GET /api/mcp/status`
+- `GET /api/mcp/tools`
+- `GET /api/mcp/audit`
+- `GET /api/mcp/audit/stats`
-## 🧪 Evalueringer (evalueringer)
+📖 Funksjonsdetaljer
+🧩 MCP Setup (Model Context Protocol)
-### 🎯 Smart 4-lags fallback +Start MCP transport in stdio mode: -Lag kombinasjoner med automatisk fallback: - -``` -Combo: "my-coding-stack" - 1. cc/claude-opus-4-6 (your subscription) - 2. nvidia/llama-3.3-70b (free NVIDIA API) - 3. glm/glm-4.7 (cheap backup, $0.6/1M) - 4. if/kimi-k2-thinking (free fallback) - -→ Auto switches when quota runs out or errors occur +```bash +omniroute --mcp ``` -### 📊 Sanntidskvotesporing +Recommended validation flow: -- Tokenforbruk per leverandør -- Tilbakestill nedtellingen (5 timer, daglig, ukentlig) -- Kostnadsestimat for betalte nivåer -- Månedlige utgiftsrapporter +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. -### 🔄 Formatoversettelse +Useful APIs for automation: -Sømløs oversettelse mellom formater: - -- **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **OpenAI-svar** -- CLI-verktøyet ditt sender OpenAI-format → OmniRoute oversetter → Leverandøren mottar eget format -- Fungerer med alle verktøy som støtter tilpassede OpenAI-endepunkter -- **Responssanering** - Fjerner ikke-standardfelter for streng OpenAI SDK-kompatibilitet -- **Rollenormalisering** — `developer` → `system` for ikke-OpenAI; `system` → `user` for GLM/ERNIE-modeller -- **Tenk tag-utvinning** — `
+
🤝 A2A Setup (Agent2Agent)
-OmniRoute inkluderer et innebygd evalueringsrammeverk for å teste LLM-responskvaliteten mot et gyldent sett. Få tilgang til den via **Analytics → Evals** i dashbordet. +Discover the agent: -### Innebygd gyldent sett +```bash +curl http://localhost:20128/.well-known/agent.json +``` -Det forhåndsinstallerte "OmniRoute Golden Set" inneholder 10 testcases som dekker: +Send a task: -- Hilsen, matematikk, geografi, kodegenerering -- JSON-formatoverholdelse, oversettelse, markdown -- Sikkerhetsavslag (skadelig innhold), telling, boolsk logikk +```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."}]}}' +``` -### Evalueringsstrategier +Manage lifecycle: -| Strategi | Beskrivelse | Eksempel | -| ---------- | --------------------------------------------------------------------- | -------------------------------- | -| `exact` | Utdata må samsvare nøyaktig med | `"4"` | -| `contains` | Utdata må inneholde understreng (uavhengig av store og små bokstaver) | `"Paris"` | -| `regex` | Utdata må samsvare med regulært uttrykksmønster | `"1.*2.*3"` | -| `custom` | Egendefinert JS-funksjon returnerer true/false | `(output) => output.length > 10` | +- `GET /api/a2a/status` +- `GET /api/a2a/tasks` +- `GET /api/a2a/tasks/:id` +- `POST /api/a2a/tasks/:id/cancel` ---- +Operational UI: -## 📖 Oppsettveiledning +- `/dashboard/a2a` for task/state/stream observability and smoke actions + +
-
+
+💳 Abonnementsleverandører
+🧪 End-to-end protocol validation
+ +Validate both protocols with real clients: + +```bash +npm run test:protocols:e2e +``` + +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) @@ -1066,7 +1438,7 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Profftips:** Bruk Opus for komplekse oppgaver, Sonnet for hastighet. OmniRoute sporer kvote per modell! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! ### OpenAI Codex (Plus/Pro) @@ -1080,7 +1452,24 @@ Models: cx/gpt-5.1-codex-max ``` -### Gemini CLI (GRATIS 180K/måned!) +#### 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). + +### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -1092,7 +1481,7 @@ Models: gc/gemini-2.5-pro ``` -**Mest verdi:** Enormt gratis nivå! Bruk dette før betalte nivåer. +**Best Value:** Huge free tier! Use this before paid tiers. ### GitHub Copilot @@ -1110,88 +1499,88 @@ Models:
-
🔑 API nøkkelleverandører
+🔑 API Key Providers
-### NVIDIA NIM (GRATIS 1000 studiepoeng!) +### NVIDIA NIM (FREE developer access — 70+ models) -1. Registrer deg: [build.nvidia.com](https://build.nvidia.com) -2. Få gratis API-nøkkel (1000 slutningspoeng inkludert) -3. Dashboard → Legg til leverandør → NVIDIA NIM: - - API-nøkkel: `nvapi-your-key` +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` -**Modeller:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct` og 50+ til +**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more -**Profftips:** OpenAI-kompatibel API — fungerer sømløst med OmniRoutes formatoversettelse! +**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation! ### DeepSeek -1. Registrer deg: [platform.deepseek.com](https://platform.deepseek.com) -2. Få API-nøkkel -3. Dashboard → Legg til leverandør → DeepSeek +1. Sign up: [platform.deepseek.com](https://platform.deepseek.com) +2. Get API key +3. Dashboard → Add Provider → DeepSeek -**Modeller:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` +**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` -### Groq (gratis nivå tilgjengelig!) +### Groq (Free Tier Available!) -1. Registrer deg: [console.groq.com](https://console.groq.com) -2. Få API-nøkkel (gratis nivå inkludert) -3. Dashboard → Legg til leverandør → Groq +1. Sign up: [console.groq.com](https://console.groq.com) +2. Get API key (free tier included) +3. Dashboard → Add Provider → Groq -**Modeller:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` +**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` -**Profftips:** Ultrarask slutning — best for sanntidskoding! +**Pro Tip:** Ultra-fast inference — best for real-time coding! -### OpenRouter (100+ modeller) +### OpenRouter (100+ Models) -1. Registrer deg: [openrouter.ai](https://openrouter.ai) -2. Få API-nøkkel -3. Dashboard → Legg til leverandør → OpenRouter +1. Sign up: [openrouter.ai](https://openrouter.ai) +2. Get API key +3. Dashboard → Add Provider → OpenRouter -**Modeller:** Få tilgang til 100+ modeller fra alle store leverandører gjennom én enkelt API-nøkkel. +**Models:** Access 100+ models from all major providers through a single API key.
-
💰 Billige leverandører (backup)
+💰 Cheap Providers (Backup)
-### GLM-4.7 (Daglig tilbakestilling, $0,6/1M) +### GLM-4.7 (Daily reset, $0.6/1M) -1. Registrer deg: [Zhipu AI](https://open.bigmodel.cn/) -2. Få API-nøkkel fra Coding Plan -3. Dashboard → Legg til API-nøkkel: - - Leverandør: `glm` - - API-nøkkel: `your-key` +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` -**Bruk:** `glm/glm-4.7` +**Use:** `glm/glm-4.7` -**Profftips:** Coding Plan tilbyr 3× kvote til 1/7 kostnad! Tilbakestill daglig 10:00. +**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -### MiniMax M2.1 (5t tilbakestilling, $0,20/1M) +### MiniMax M2.1 (5h reset, $0.20/1M) -1. Registrer deg: [MiniMax](https://www.minimax.io/) -2. Få API-nøkkel -3. Dashboard → Legg til API-nøkkel +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key +3. Dashboard → Add API Key -**Bruk:** `minimax/MiniMax-M2.1` +**Use:** `minimax/MiniMax-M2.1` -**Profftips:** Billigste alternativet for lang kontekst (1M tokens)! +**Pro Tip:** Cheapest option for long context (1M tokens)! -### Kimi K2 ($9/mnd leilighet) +### Kimi K2 ($9/month flat) -1. Abonner: [Moonshot AI](https://platform.moonshot.ai/) -2. Få API-nøkkel -3. Dashboard → Legg til API-nøkkel +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key +3. Dashboard → Add API Key -**Bruk:** `kimi/kimi-latest` +**Use:** `kimi/kimi-latest` -**Profftips:** Fast $9/måned for 10M tokens = $0,90/1M effektiv kostnad! +**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
-
🆓 GRATIS Leverandører (Emergency Backup)
+🆓 FREE Providers (Emergency Backup)
-### iFlow (8 GRATIS modeller) +### iFlow (5 FREE models via OAuth) ```bash Dashboard → Connect iFlow @@ -1206,7 +1595,7 @@ Models: if/deepseek-r1 ``` -### Qwen (3 GRATIS modeller) +### Qwen (4 FREE models via Device Code) ```bash Dashboard → Connect Qwen @@ -1233,9 +1622,9 @@ Models:
-
🎨 Lag kombinasjoner
+🎨 Create Combos
-### Eksempel 1: Maksimer abonnement → Billig sikkerhetskopi +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -1249,7 +1638,7 @@ Models: Use in CLI: premium-coding ``` -### Eksempel 2: Kun gratis (nullkostnad) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -1264,9 +1653,9 @@ Cost: $0 forever!
-
---
-## 🐛 Feilsøking
+## Feilsøking
🔧 CLI-integrasjon
+🔧 CLI Integration
-### Markør IDE +### Cursor IDE ``` Settings → Models → Advanced: @@ -1277,7 +1666,7 @@ Settings → Models → Advanced: ### Claude Code -Bruk **CLI Tools**-siden i dashbordet for ett-klikks konfigurasjon, eller rediger `~/.claude/settings.json` manuelt. +Use the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually. ### Codex CLI @@ -1290,13 +1679,13 @@ codex "your prompt" ### OpenClaw -**Alternativ 1 – Dashboard (anbefalt):** +**Option 1 — Dashboard (recommended):** ``` Dashboard → CLI Tools → OpenClaw → Select Model → Apply ``` -**Alternativ 2 — Manuell:** Rediger `~/.openclaw/openclaw.json`: +**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`: ```json { @@ -1312,9 +1701,9 @@ Dashboard → CLI Tools → OpenClaw → Select Model → Apply } ``` -> **Merk:** OpenClaw fungerer bare med lokale OmniRoute. Bruk `127.0.0.1` i stedet for `localhost` for å unngå problemer med IPv6-oppløsning. +> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues. -### Cline / Fortsett / RooCode +### Cline / Continue / RooCode ``` Settings → API Configuration: @@ -1324,96 +1713,231 @@ Settings → API Configuration: 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. +
-
-- **Kjøretid**: Node.js 18–22 LTS (⚠️ Node.js 24+ støttes **ikke** — `better-sqlite3` native binærfiler er inkompatible)
-- **Språk**: TypeScript 5.9 — **100 % TypeScript** på tvers av `src/` og `open-sse/` (v1.0.6)
-- **Rammeverk**: Next.js 16 + React 19 + Tailwind CSS 4
-- **Database**: LowDB (JSON) + SQLite (domenetilstand + proxy-logger)
-- **Streaming**: Server-sendte hendelser (SSE)
-- **Auth**: OAuth 2.0 (PKCE) + JWT + API-nøkler
-- **Test**: Node.js-testløper (368+ enhetstester)
-- **CI/CD**: GitHub-handlinger (automatisk npm-publisering + Docker Hub ved utgivelse)
-- **Nettsted**: [omniroute.online](https://omniroute.online)
-- **Pakke**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
-- **Dokker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
-- **Resiliens**: Strømbryter, eksponentiell backoff, anti-trdnende flokk, TLS-spoofing
-
----
-
-## 📖 Dokumentasjon
-
-| Dokument | Beskrivelse |
-| -------------------------------------------- | ---------------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Leverandører, kombinasjoner, CLI-integrasjon, distribusjon |
-| [API Reference](docs/API_REFERENCE.md) | Alle endepunkter med eksempler |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Vanlige problemer og løsninger |
-| [Architecture](docs/ARCHITECTURE.md) | Systemarkitektur og innvendig |
-| [Contributing](CONTRIBUTING.md) | Utviklingsoppsett og retningslinjer |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0-spesifikasjon |
-| [Security Policy](SECURITY.md) | Sårbarhetsrapportering og sikkerhetspraksis |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Komplett guide: VM + nginx + Cloudflare-oppsett |
-| [Features Gallery](docs/FEATURES.md) | Visuell dashbordomvisning med skjermbilder |
-
-### 📸 Forhåndsvisning av dashbord
+## 🛠️ Tech Stack
Klikk for å utvide feilsøkingsveiledningen
+Click to expand troubleshooting guide
-**«Språkmodellen ga ikke meldinger»** +**"Language model did not provide messages"** -- Leverandørkvoten er oppbrukt → Sjekk dashboardkvotesporing -- Løsning: Bruk kombinasjonsalternativ eller bytt til et billigere nivå +- Provider quota exhausted → Check dashboard quota tracker +- Solution: Use combo fallback or switch to cheaper tier -**Satsbegrensning** +**Rate limiting** -- Abonnementskvote ut → Fallback til GLM/MiniMax -- Legg til kombinasjon: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Subscription quota out → Fallback to GLM/MiniMax +- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -**OAuth-token er utløpt** +**OAuth token expired** -- Automatisk oppdatering av OmniRoute -- Hvis problemene vedvarer: Dashboard → Leverandør → Koble til på nytt +- Auto-refreshed by OmniRoute +- If issues persist: Dashboard → Provider → Reconnect -**Høye kostnader** +**High costs** -- Sjekk bruksstatistikk i Dashboard → Kostnader -- Bytt primærmodell til GLM/MiniMax -- Bruk gratis nivå (Gemini CLI, iFlow) for ikke-kritiske oppgaver +- Check usage stats in Dashboard → Costs +- Switch primary model to GLM/MiniMax +- Use free tier (Gemini CLI, iFlow) for non-critical tasks -**Dashboard åpnes på feil port** +**Dashboard/API ports are wrong** -- Sett `PORT=20128` og `NEXT_PUBLIC_BASE_URL=http://localhost:20128` +- `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) -**Skysynkroniseringsfeil** +**Cloud sync errors** -- Bekreft at `BASE_URL` peker på løpeforekomsten din -- Bekreft `CLOUD_URL` poeng til det forventede skyendepunktet -- Hold `NEXT_PUBLIC_*` verdier på linje med verdiene på tjenersiden +- 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 -**Første pålogging fungerer ikke** +**First login not working** -- Sjekk `INITIAL_PASSWORD` i `.env` -- Hvis det ikke er angitt, er reservepassordet `123456` +- Check `INITIAL_PASSWORD` in `.env` +- If unset, fallback password is `123456` -**Ingen forespørselslogger** +**No request logs** -- Sett `ENABLE_REQUEST_LOGS=true` i `.env` +- Set `ENABLE_REQUEST_LOGS=true` in `.env` -**Test viser «Ugyldig» for OpenAI-kompatible leverandører** +**Connection test shows "Invalid" for OpenAI-compatible providers** -- Mange leverandører avslører ikke et `/models`-endepunkt -- OmniRoute v1.0.6+ inkluderer reservevalidering via chatfullføringer -- Sørg for at basis-URL inkluderer suffikset `/v1` +- 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 +### 🔐 OAuth on a Remote Server + -> **⚠️ VIKTIG for bruk av OmniRoute med VPS/Docker/server-fjernkontroll** +> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server** -### OAuth +#### Why does Antigravity / Gemini CLI OAuth fail on remote servers? -Os testedores **Antigravity** og **Gemini CLI** usam **Google OAuth 2.0** for autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pre-cadastradas no Google Cloud Console do aplicativo. +The **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console. -Som credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (eks: `https://omniroute.meuservidor.com`), o Google avviser autenticação com: +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 ``` -### Løsning: Konfigurer OAuth-tilbehør +#### Solution: Configure your own OAuth credentials -Você precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com en URI for seu service. +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 + +# For Gemini CLI: +GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com +GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +``` + +**6. Restart OmniRoute** + +```bash +# npm: +npm run dev + +# Docker: +docker restart omniroute +``` + +**7. Try connecting again** + +Dashboard → Providers → Antigravity (or Gemini CLI) → OAuth + +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. + +--- + +
+
---
-## 🛠️
+🇧🇷 Versão em Português
+ +#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos? + +Os provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo. + +As credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticação com: + +``` +Error 400: redirect_uri_mismatch +``` + +#### Solução: Configure suas próprias credenciais OAuth + +Você precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor. #### Passo a passo -**1. Tilgang til Google Cloud Console** +**1. Acesse o Google Cloud Console** Abra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) **2. Crie um novo OAuth 2.0 Client ID** -- Klikk dem **"+ Opprett legitimasjon"** → **"OAuth-klient-ID"** -- Tipo de aplicativo: **"Nettapplikasjon"** -- Navn: escolha qualquer nome (eks.: `OmniRoute Remote`) +- Clique em **"+ Create Credentials"** → **"OAuth client ID"** +- Tipo de aplicativo: **"Web application"** +- Nome: escolha qualquer nome (ex: `OmniRoute Remote`) -**3. Adicione som autorisert omdirigerings-URI** +**3. Adicione as Authorized Redirect URIs** -Ingen campo **"Authorized redirect URIs"**, adicione: +No campo **"Authorized redirect URIs"**, adicione: ``` https://seu-servidor.com/callback @@ -1421,11 +1945,11 @@ https://seu-servidor.com/callback > Substitua `seu-servidor.com` pelo domínio ou IP do seu servidor (inclua a porta se necessário, ex: `http://45.33.32.156:20128/callback`). -**4. Salve e copy as credenciais** +**4. Salve e copie as credenciais** Após criar, o Google mostrará o **Client ID** e o **Client Secret**. -**5. Konfigurer som variáveis de ambiente** +**5. Configure as variáveis de ambiente** No seu `.env` (ou nas variáveis de ambiente do Docker): @@ -1452,150 +1976,145 @@ docker restart omniroute **7. Tente conectar novamente** -Dashboard → Leverandører → Antigravity (ou Gemini CLI) → OAuth +Dashboard → Providers → Antigravity (ou Gemini CLI) → OAuth -Agora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e autenticação funcionará. +Agora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará. --- -### Midlertidig midlertidig løsning (som konfigureres på forhånd) +#### Workaround temporário (sem configurar credenciais próprias) Se não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**: -1. O OmniRoute abrirá en URL fra autorização til Google -2. Após você autorizar, o Google tentará redirecionar for `localhost` (que falha no servidor remoto) -3. **Kopier en URL fullført** da barra de endereço do seu nettleseren (mesmo que a página não carregue) +1. O OmniRoute abrirá a URL de autorização do Google +2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto) +3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue) 4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute -5. Klikk på **"Koble til"** +5. Clique em **"Connect"** -> Este workaround funciona porque or código de autorização na URL é válido independente do redirect ter carregado or não. +> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.
-
---
-## 🗺️
+## Dokumentasjon
-OmniRoute har **210+ funksjoner planlagt** på tvers av flere utviklingsfaser. Her er nøkkelområdene:
-
-| Kategori | Planlagte funksjoner | Høydepunkter |
-| -------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------- |
-| 🧠 **Routing og intelligens** | 25+ | Ruting med lavest ventetid, tag-basert ruting, forhåndskontroll av kvoter, valg av P2C-konto |
-| 🔒 **Sikkerhet og overholdelse** | 20+ | SSRF-herding, tilsløring av legitimasjon, hastighetsgrense per endepunkt, styringsnøkkelomfang |
-| 📊 **Observerbarhet** | 15+ | OpenTelemetry-integrasjon, kvoteovervåking i sanntid, kostnadssporing per modell |
-| 🔄 **Tilbyderintegrasjoner** | 20+ | Dynamisk modellregister, leverandørnedkjøling, multi-konto Codex, Copilot-kvoteparsing |
-| ⚡ **Ytelse** | 15+ | Dobbelt hurtigbufferlag, promptbuffer, svarbuffer, streaming keepalive, batch API |
-| 🌐 **Økosystem** | 10+ | WebSocket API, config hot-reload, distribuert config store, kommersiell modus |
-
-### 🔜 Kommer snart
-
-- 🔗 **OpenCode Integration** — Innebygd leverandørstøtte for OpenCode AI-kodings-IDE
-- 🔗 **TRAE-integrasjon** — Full støtte for utviklingsrammeverket for TRAE AI
-- 📦 **Batch API** — Asynkron batchbehandling for bulkforespørsler
-- 🎯 **Tag-basert ruting** — Ruteforespørsler basert på tilpassede tagger og metadata
-- 💰 **Laveste kostnadsstrategi** — Velg automatisk den billigste tilgjengelige leverandøren
-
-> 📝 Full funksjonsspesifikasjoner tilgjengelig i [link](docs/new-features/) (217 detaljerte spesifikasjoner)
+| Document | Description |
+| ---------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 16 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/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
+| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
-## 👥 Bidragsytere
+## 🗺️ Roadmap
+
+OmniRoute has **210+ 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, P2C account selection |
+| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |
+| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |
+| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider 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
[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
-### Hvordan bidra
+### How to Contribute
-1. Fordel depotet
-2. Lag din funksjonsgren (`git checkout -b feature/amazing-feature`)
-3. Bekreft endringene dine (`git commit -m 'Add amazing feature'`)
-4. Skyv til grenen (`git push origin feature/amazing-feature`)
-5. Åpne en pull-forespørsel
+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
-Se [CONTRIBUTING.md](CONTRIBUTING.md) for detaljerte retningslinjer.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
-### Slipper en ny versjon
+### Releasing a New Version
```bash
# Create a release — npm publish happens automatically
-gh release create v1.0.6 --title "v1.0.6" --generate-notes
+gh release create v2.0.0 --title "v2.0.0" --generate-notes
```
---
-## 📊 Stjernehistorie
+## 📊 Star History
## Stargazers over time
## [](https://starchart.cc/diegosouzapw/OmniRoute)
-## 🙏 Anerkjennelser
+## 🙏 Acknowledgments
-Spesiell takk til **[9router](https://github.com/decolua/9router)** av **[decolua](https://github.com/decolua)** — det originale prosjektet som inspirerte denne gaffelen. OmniRoute bygger på det utrolige grunnlaget med tilleggsfunksjoner, multimodale APIer og en full TypeScript-omskriving.
+Special thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.
-Spesiell takk til **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — den originale Go-implementeringen som inspirerte denne JavaScript-porten.
+Special thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.
---
-## 📄 Lisens
+## Lisens
-MIT-lisens - se [LICENSE](LICENSE) for detaljer.
+MIT License - see [LICENSE](LICENSE) for details.
---
Klikk for å se skjermbilder av dashbordet
+Click to expand tech stack details
-| Side | Skjermbilde | -| ----------------- | ------------------------------------------------- | -| **Tilbydere** |  | -| **Komboer** |  | -| **Analyse** |  | -| **Helse** |  | -| **Oversetter** |  | -| **Innstillinger** |  | -| **CLI-verktøy** |  | -| **Brukslogger** |  | -| **Endepunkt** |  | +- **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**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions) +- **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
- Bygget med ❤️ for utviklere som koder 24/7
+ Built with ❤️ for developers who code 24/7
omniroute.online
+
diff --git a/docs/i18n/no/docs/FEATURES.md b/docs/i18n/no/docs/FEATURES.md
new file mode 100644
index 0000000000..7df4ba51a9
--- /dev/null
+++ b/docs/i18n/no/docs/FEATURES.md
@@ -0,0 +1,145 @@
+# OmniRoute — Dashboard Features Gallery (Norsk)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/FEATURES.md) · 🇪🇸 [es](../../es/docs/FEATURES.md) · 🇫🇷 [fr](../../fr/docs/FEATURES.md) · 🇩🇪 [de](../../de/docs/FEATURES.md) · 🇮🇹 [it](../../it/docs/FEATURES.md) · 🇷🇺 [ru](../../ru/docs/FEATURES.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FEATURES.md) · 🇯🇵 [ja](../../ja/docs/FEATURES.md) · 🇰🇷 [ko](../../ko/docs/FEATURES.md) · 🇸🇦 [ar](../../ar/docs/FEATURES.md) · 🇮🇳 [in](../../in/docs/FEATURES.md) · 🇹🇭 [th](../../th/docs/FEATURES.md) · 🇻🇳 [vi](../../vi/docs/FEATURES.md) · 🇮🇩 [id](../../id/docs/FEATURES.md) · 🇲🇾 [ms](../../ms/docs/FEATURES.md) · 🇳🇱 [nl](../../nl/docs/FEATURES.md) · 🇵🇱 [pl](../../pl/docs/FEATURES.md) · 🇸🇪 [sv](../../sv/docs/FEATURES.md) · 🇳🇴 [no](../../no/docs/FEATURES.md) · 🇩🇰 [da](../../da/docs/FEATURES.md) · 🇫🇮 [fi](../../fi/docs/FEATURES.md) · 🇵🇹 [pt](../../pt/docs/FEATURES.md) · 🇷🇴 [ro](../../ro/docs/FEATURES.md) · 🇭🇺 [hu](../../hu/docs/FEATURES.md) · 🇧🇬 [bg](../../bg/docs/FEATURES.md) · 🇸🇰 [sk](../../sk/docs/FEATURES.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FEATURES.md) · 🇮🇱 [he](../../he/docs/FEATURES.md) · 🇵🇭 [phi](../../phi/docs/FEATURES.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FEATURES.md)
+
+---
+
+Visual guide to every section of the OmniRoute dashboard.
+
+---
+
+## 🔌 Providers
+
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
+
+
+
+---
+
+## 🎨 Combos
+
+Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
+
+
+
+---
+
+## 📊 Analytics
+
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
+
+
+
+---
+
+## 🏥 System Health
+
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+
+
+
+---
+
+## 🔧 Translator Playground
+
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
+
+
+
+---
+
+## 🎮 Model Playground _(v2.0.9+)_
+
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
+
+---
+
+## 🎨 Themes _(v2.0.5+)_
+
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
+
+## ⚙️ Settings
+
+Comprehensive settings panel with tabs:
+
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning
+- **Advanced** — Configuration overrides
+
+
+
+---
+
+## 🔧 CLI Tools
+
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
+
+
+
+---
+
+## 🤖 CLI Agents _(v2.0.11+)_
+
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
+
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
+
+---
+
+## 🖼️ Media _(v2.0.3+)_
+
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
+
+## 📝 Request Logs
+
+Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
+
+
+
+---
+
+## 🌐 API Endpoint
+
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
+
+
+
+---
+
+## 🔑 API Key Management
+
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
+
+---
+
+## 📋 Audit Log
+
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
+
+---
+
+## 🖥️ Desktop Application
+
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
+
+Key features:
+
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
+
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.
diff --git a/docs/i18n/phi/README.md b/docs/i18n/phi/README.md
index 574beff116..0e128e685c 100644
--- a/docs/i18n/phi/README.md
+++ b/docs/i18n/phi/README.md
@@ -1,24 +1,94 @@
-omniroute.online
-
-
- # 🚀 OmniRoute — Ang Libreng AI Gateway
+# 🚀 OmniRoute — The Free AI Gateway (Filipino)
-### Huwag kailanman ihinto ang coding. Smart routing sa **LIBRE at murang mga modelo ng AI** na may awtomatikong fallback.
-
-_Iyong unibersal na API proxy — isang endpoint, 67+ provider, zero downtime._
-
-**Mga Pagkumpleto ng Chat • Mga Pag-embed • Pagbuo ng Imahe • Audio • Pag-rerank • 100% TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Libreng AI Provider para sa iyong mga paboritong coding agent
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Ikonekta ang anumang AI-powered IDE o CLI tool sa pamamagitan ng OmniRoute — libreng API gateway para sa walang limitasyong coding._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+` tags no longer leak to clients in SSE streaming responses (#585) |
+| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with per-provider/account quota enforcement, idempotency, SHA-256 storage, and optional GitHub issue reporting |
+| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG → generic fallback chain |
+| 🔄 **Model Auto-Sync** | 24h scheduler and manual UI toggle to sync model lists for built-in and custom OpenAI-compatible providers |
+| 🌐 **OpenCode Zen/Go** | Two new providers from @kang-heewon via PR #530: free tier + subscription tier via `OpencodeExecutor` |
+| 🐛 **Gemini CLI OAuth** | Actionable error when `GEMINI_OAUTH_CLIENT_SECRET` is missing in Docker (was cryptic Google error) |
+| 🐛 **OpenCode config** | `saveOpenCodeConfig()` now correctly writes TOML to `XDG_CONFIG_HOME` |
+| 🐛 **Pinned model override** | `body.model` correctly set to `pinnedModel` on context-cache protection |
+| 🐛 **Codex/Claude loop** | `tool_result` blocks now converted to text to stop infinite loops |
+| 🐛 **Login redirect** | Login no longer freezes after skipping password setup |
+| 🐛 **Windows paths** | MSYS2/Git-Bash paths (`/c/...`) normalized to `C:\...` automatically |
+
+---
+
+## 🖼️ Main Dashboard
+
+
-📡 Kumonekta ang lahat ng ahente sa pamamagitan ng ` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**Stop wasting money and hitting limits:**
-### 🆕 What's New in v3.0.0
+- Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**OmniRoute solves this:**
+
+- ✅ **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
+- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool
---
-[](https://www.npmjs.com/package/omniroute)
-[](https://hub.docker.com/r/diegosouzapw/omniroute)
-[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
-[](https://omniroute.online)
-[](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
+## 📧 Support
-[🌐 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)
-
-🌐 **Available in:** 🇺🇸 [English](../../README.md) | 🇧🇷 [Português (Brasil)](../pt-BR/README.md) | 🇪🇸 [Español](../es/README.md) | 🇫🇷 [Français](../fr/README.md) | 🇮🇹 [Italiano](../it/README.md) | 🇷🇺 [Русский](../ru/README.md) | 🇨🇳 [中文 (简体)](../zh-CN/README.md) | 🇩🇪 [Deutsch](../de/README.md) | 🇮🇳 [हिन्दी](../in/README.md) | 🇹🇭 [ไทย](../th/README.md) | 🇺🇦 [Українська](../uk-UA/README.md) | 🇸🇦 [العربية](../ar/README.md) | 🇯🇵 [日本語](../ja/README.md) | 🇻🇳 [Tiếng Việt](../vi/README.md) | 🇧🇬 [Български](../bg/README.md) | 🇩🇰 [Dansk](../da/README.md) | 🇫🇮 [Suomi](../fi/README.md) | 🇮🇱 [עברית](../he/README.md) | 🇭🇺 [Magyar](../hu/README.md) | 🇮🇩 [Bahasa Indonesia](../id/README.md) | 🇰🇷 [한국어](../ko/README.md) | 🇲🇾 [Bahasa Melayu](../ms/README.md) | 🇳🇱 [Nederlands](../nl/README.md) | 🇳🇴 [Norsk](../no/README.md) | 🇵🇹 [Português (Portugal)](../pt/README.md) | 🇷🇴 [Română](../ro/README.md) | 🇵🇱 [Polski](../pl/README.md) | 🇸🇰 [Slovenčina](../sk/README.md) | 🇸🇪 [Svenska](../sv/README.md) | 🇵🇭 [Filipino](../phi/README.md)
-
-
-
----
-
-## 🖼️
-
-
-
- # 🚀 OmniRoute — Ang Libreng AI Gateway
+# 🚀 OmniRoute — The Free AI Gateway (Filipino)
-### Huwag kailanman ihinto ang coding. Smart routing sa **LIBRE at murang mga modelo ng AI** na may awtomatikong fallback.
-
-_Iyong unibersal na API proxy — isang endpoint, 67+ provider, zero downtime._
-
-**Mga Pagkumpleto ng Chat • Mga Pag-embed • Pagbuo ng Imahe • Audio • Pag-rerank • 100% TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Libreng AI Provider para sa iyong mga paboritong coding agent
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Ikonekta ang anumang AI-powered IDE o CLI tool sa pamamagitan ng OmniRoute — libreng API gateway para sa walang limitasyong coding._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+
+
+[](https://www.npmjs.com/package/omniroute)
+[](https://www.npmjs.com/package/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
+[](https://omniroute.online)
+[](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)
+
+
+
+🌐 **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)
+
+---
+
+## 🆕 What's New in v3.0.0
+
+> **Upgrading from v2.9.5?** — See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes.
+
+| Area | Change |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection remediation |
+| ✅ **Route Validation** | All 176 API routes now validated with Zod schemas + `validateBody()` — CI `check:route-validation:t06` passes |
+| 🐛 **omniModel Tag Leak** | Internal `
+
+
+
+---
+
+## 📸 Dashboard Preview
+
+
+
+
+
+---
+
+### 🤖 Free AI Provider for your favorite coding agents
+
+_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._
Click to see dashboard screenshots
+ +| Page | Screenshot | +| -------------- | ------------------------------------------------- | +| **Providers** |  | +| **Combos** |  | +| **Analytics** |  | +| **Health** |  | +| **Translator** |  | +| **Settings** |  | +| **CLI Tools** |  | +| **Usage Logs** |  | +| **Endpoints** |  | + +|
-
+
OpenClaw @@ -92,113 +162,52 @@ _Ikonekta ang anumang AI-powered IDE o CLI tool sa pamamagitan ng OmniRoute — |
http://localhost:20128/v1 o http://cloud.omniroute.online/v1 >http://cloud.omniroute.online/v1 —iisang modelo at hindi config. quota
+📡 All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 — one config, unlimited models and quota
---
-### 🆕 What's New in v3.0.0
+## 🤔 Why OmniRoute?
-| Area | Change |
-| ------------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal ` Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `
-
-
-
----
-
-## 📸
-
-
-
-
-
----
-
-## 🤔 Bakit OmniRoute?
-
-**Ihinto ang pag-aaksaya ng pera at pag-abot sa mga limitasyon:**
-
-- ...
- -| # | # | -| ----- | ---------------------------------------- | -| **1** |  | -| **2** |  | -| **3** |  | -| **4** |  | -| **5** |  | -| **6** |  | -| **7** |  | -| **8** |  | -| **9** |  | - - Mag-e-expire ang quota ng subscription na hindi nagamit bawat buwan
-- Pinipigilan ka ng mga limitasyon sa rate sa mid-coding
-- Mga Mamahaling API ($20-50/buwan bawat provider)
-- Manu-manong paglipat sa pagitan ng mga provider
-
-**Sumalutas ito ng OmniRoute:**
-
-- ✅ **I-maximize ang mga subscription** - Subaybayan ang quota, gamitin ang bawat bit bago i-reset
-- ✅ **Auto fallback** - Subscription → API Key → Mura → Libre, zero downtime
-- ✅ **Multi-account** - Round-robin sa pagitan ng mga account sa bawat provider
-- ✅ **Universal** - Gumagana sa Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, anumang CLI tool
-
----
-
-## 📧 Suporta
-
-> 💬 **Sumali sa aming komunidad!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Humingi ng tulong, magbahagi ng mga tip, at manatiling updated.
+> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.
- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Mga Isyu**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Orihinal na Proyekto**: [9router by decolua](https://github.com/decolua/9router)
+- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 Paano Ito Gumagana
+## 🔄 How It Works
```
┌─────────────┐
@@ -227,451 +236,453 @@ Result: Never stop coding, minimal cost
---
-## 🎯 Ano ang Lutasin ng OmniRoute — 30 Tunay na Pain Points at Mga Kaso ng Paggamit
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **Ang bawat developer na gumagamit ng mga tool ng AI ay nahaharap sa mga problemang ito araw-araw.** Binuo ang OmniRoute para lutasin ang lahat ng ito — mula sa mga pag-overrun sa gastos hanggang sa mga panrehiyong bloke, mula sa mga sirang daloy ng OAuth hanggang sa mga pagpapatakbo ng protocol at pagmamasid sa enterprise.
+> **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.
-
💸 1. "Nagbabayad ako para sa isang mamahaling subscription ngunit naaantala pa rin ng mga limitasyon"
+💸 1. "I pay for an expensive subscription but still get interrupted by limits"
-Nagbabayad ang mga developer ng $20–200/buwan para sa Claude Pro, Codex Pro, o GitHub Copilot. Kahit na nagbabayad, may kisame ang quota — 5h ng paggamit, lingguhang limitasyon, o bawat minutong limitasyon sa rate. Sesyon sa kalagitnaan ng coding, hihinto sa pagtugon ang provider at nawawalan ng daloy at pagiging produktibo ang developer. +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. -**Paano ito niresolba ng OmniRoute:** +**How OmniRoute solves it:** -- **Smart 4-Tier Fallback** — Kung maubusan ang quota ng subscription, awtomatikong magre-redirect sa API Key → Murang → Libre nang walang manu-manong interbensyon -- **Real-Time Quota Tracking** — Ipinapakita ang pagkonsumo ng token sa real-time na may reset countdown (5h, araw-araw, lingguhan) -- **Multi-Account Support** — Maramihang account sa bawat provider na may auto round-robin — kapag naubos ang isa, lilipat sa susunod -- **Custom Combos** — Nako-customize na fallback chain na may 6 na diskarte sa pagbabalanse (fill-first, round-robin, P2C, random, hindi gaanong ginagamit, cost-optimized) -- **Codex Business Quotas** — Direktang pagsubaybay sa quota ng workspace ng Negosyo/Team sa dashboard +- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention +- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly) +- **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 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
-` block mula sa mga modelo tulad ng DeepSeek R1 sa standardized `reasoning_content`
-- **Structured Output para sa Gemini** — `json_schema` → `responseMimeType`/`responseSchema` awtomatikong conversion
-- **`stream` ang mga default sa `false`** — Naka-align sa OpenAI spec, iniiwasan ang hindi inaasahang SSE sa Python/Rust/Go SDK
+- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 67+ 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
🔌 2. "Kailangan kong gumamit ng maraming provider ngunit bawat isa ay may iba't ibang API"
+🔌 2. "I need to use multiple providers but each has a different API"
-Gumagamit ang OpenAI ng isang format, gumagamit si Claude (Anthropic) ng isa pa, isa pa ang Gemini. Kung gusto ng isang dev na subukan ang mga modelo mula sa iba't ibang provider o fallback sa pagitan nila, kailangan nilang i-configure muli ang mga SDK, baguhin ang mga endpoint, harapin ang mga hindi tugmang format. Ang mga custom na provider (FriendLI, NIM) ay may hindi karaniwang mga endpoint ng modelo. +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. -**Paano ito niresolba ng OmniRoute:** +**How OmniRoute solves it:** -- **Pinag-isang Endpoint** — Isang `http://localhost:20128/v1` ang nagsisilbing proxy para sa lahat ng 67+ provider -- **Format Translation** — Awtomatiko at transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API -- **Response Sanitization** — Tinatanggal ang mga hindi karaniwang field (`x_groq`, `usage_breakdown`, `service_tier`) na sumisira sa OpenAI SDK v1.83+ -- **Role Normalization** — Kino-convert ang `developer` → `system` para sa mga provider na hindi OpenAI; `system` → `user` para sa GLM/ERNIE -- **Think Tag Extraction** — Kinukuha ang `
-
🌐 3. "Bina-block ng aking AI provider ang aking rehiyon/bansa"
+🌐 3. "My AI provider blocks my region/country"
-Hinaharang ng mga provider tulad ng OpenAI/Codex ang pag-access mula sa ilang partikular na heyograpikong rehiyon. Nakakakuha ang mga user ng mga error tulad ng `unsupported_country_region_territory` sa panahon ng mga koneksyon sa OAuth at API. Ito ay lalo na nakakabigo para sa mga developer mula sa pagbuo ng mga bansa. +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. -**Paano ito niresolba ng OmniRoute:** +**How OmniRoute solves it:** -- **3-Level Proxy Config** — Nako-configure na proxy sa 3 antas: global (lahat ng trapiko), bawat provider (isang provider lang), at bawat koneksyon/key -- **Color-Coded Proxy Badges** — Visual indicator: 🟢 global proxy, 🟡 provider proxy, 🔵 connection proxy, palaging ipinapakita ang IP -- **OAuth Token Exchange Through Proxy** — Ang daloy ng OAuth ay dumadaan din sa proxy, na nilulutas ang `unsupported_country_region_territory` -- **Mga Pagsusuri sa Koneksyon sa pamamagitan ng Proxy** — Ginagamit ng mga pagsubok sa koneksyon ang naka-configure na proxy (wala nang direktang bypass) -- **SOCKS5 Support** — Buong SOCKS5 proxy support para sa papalabas na pagruruta -- **TLS Fingerprint Spoofing** — tulad ng browser na TLS fingerprint sa pamamagitan ng `wreq-js` para i-bypass ang pag-detect ng bot +- **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
-` prefix
-- **Free-Only Combos** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/buwan na walang downtime
-- **NVIDIA NIM Free Credits** — 1000 libreng credits na isinama
-- **Cost Optimized Strategy** — Istratehiya sa pagruruta na awtomatikong pinipili ang pinakamurang available na provider
+- **Free-Only Combos** — Chain `gc/gemini-3-flash → 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
🆓 4. "Gusto kong gumamit ng AI para sa coding ngunit wala akong pera"
+🆓 4. "I want to use AI for coding but I have no money"
-Hindi lahat ay maaaring magbayad ng $20–200/buwan para sa mga subscription sa AI. Ang mga mag-aaral, mga dev mula sa mga umuusbong na bansa, mga hobbyist, at mga freelancer ay nangangailangan ng access sa mga de-kalidad na modelo sa zero cost. +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. -**Paano ito niresolba ng OmniRoute:** +**How OmniRoute solves it:** -- **Libreng Tier Provider Built-in** — Native na suporta para sa 100% libreng provider: iFlow (8 unlimited na modelo), Qwen (3 unlimited na modelo), Kiro (Claude nang libre), Gemini CLI (180K/buwan libre) +- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free) - **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/
-
🔒 5. "Kailangan kong protektahan ang aking AI gateway mula sa hindi awtorisadong pag-access"
+🔒 5. "I need to protect my AI gateway from unauthorized access"
-Kapag inilantad ang isang gateway ng AI sa network (LAN, VPS, Docker), maaaring kumonsumo ng mga token/quota ng developer ang sinumang may address. Kung walang proteksyon, ang mga API ay mahina sa maling paggamit, agarang pag-iniksyon, at pang-aabuso. +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. -**Paano ito niresolba ng OmniRoute:** +**How OmniRoute solves it:** -- **API Key Management** — Pagbuo, pag-ikot, at saklaw ng bawat provider na may nakalaang `/dashboard/api-manager` na pahina -- **Mga Pahintulot sa Antas ng Modelo** — Limitahan ang mga API key sa mga partikular na modelo (`openai/*`, mga wildcard pattern), na may Allow All/Restrict toggle -- **API Endpoint Protection** — Mangangailangan ng key para sa `/v1/models` at i-block ang mga partikular na provider mula sa listahan -- **Auth Guard + CSRF Protection** — Lahat ng mga ruta ng dashboard ay protektado ng `withAuth` middleware + CSRF token -- **Rate Limiter** — Per-IP rate na naglilimita sa mga na-configure na window -- **IP Filtering** — Allowlist/blocklist para sa access control -- **Prompt Injection Guard** — Sanitization laban sa malisyosong prompt pattern -- **AES-256-GCM Encryption** — Ang mga kredensyal ay naka-encrypt sa pahinga +- **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. "Bumaba ang provider ko at nawala ang coding flow ko"
+🛑 6. "My provider went down and I lost my coding flow"
-Ang mga tagapagbigay ng AI ay maaaring maging hindi matatag, magbalik ng 5xx na mga error, o maabot ang mga pansamantalang limitasyon sa rate. Kung ang isang dev ay nakadepende sa isang provider, maaantala sila. Kung walang mga circuit breaker, ang mga paulit-ulit na pagsubok ay maaaring mag-crash sa application. +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. -**Paano ito niresolba ng OmniRoute:** +**How OmniRoute solves it:** -- **Circuit Breaker per-model** — Awtomatikong buksan/sarado na may mga na-configure na threshold at cooldown (Sarado/Bukas/Kalahating Bukas) +- **Circuit Breaker per-model** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks - **Exponential Backoff** — Progressive retry delays -- **Anti-Thundering Herd** — Mutex + semaphore na proteksyon laban sa kasabay na muling pagsubok na mga bagyo -- **Combo Fallback Chains** — Kung nabigo ang pangunahing provider, awtomatikong mahuhulog sa chain nang walang interbensyon -- **Combo Circuit Breaker** — Awtomatikong idi-disable ang mga nabigong provider sa loob ng combo chain +- **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 +- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain - **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
-
🔧 7. "Ang pag-configure ng bawat AI tool ay nakakapagod at paulit-ulit"
+🔧 7. "Configuring each AI tool is tedious and repetitive"
-Gumagamit ang mga developer ng Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Ang bawat tool ay nangangailangan ng ibang config (API endpoint, key, model). Ang muling pag-configure kapag lumipat ng mga provider o modelo ay isang pag-aaksaya ng oras. +Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time. -**Paano ito niresolba ng OmniRoute:** +**How OmniRoute solves it:** -- **CLI Tools Dashboard** — Nakatuon na page na may isang-click na setup para sa Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline -- **GitHub Copilot Config Generator** — Bumubuo ng `chatLanguageModels.json` para sa VS Code na may maramihang pagpili ng modelo -- **Onboarding Wizard** — May gabay na 4-step na pag-setup para sa mga unang beses na user -- **Isang endpoint, lahat ng modelo** — I-configure ang `http://localhost:20128/v1` nang isang beses, i-access ang 67+ provider +- **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 67+ providers
-
🔑 8. "Impiyerno ang pamamahala sa mga token ng OAuth mula sa maraming provider"
+🔑 8. "Managing OAuth tokens from multiple providers is hell"
-Claude Code, Codex, Gemini CLI, Copilot — lahat ay gumagamit ng OAuth 2.0 na may mga mag-e-expire na token. Kailangang muling mag-authenticate ang mga developer, harapin ang `client_secret is missing`, `redirect_uri_mismatch`, at mga pagkabigo sa mga malalayong server. Ang OAuth sa LAN/VPS ay partikular na may problema. +Claude Code, Codex, Gemini CLI, 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. -**Paano ito niresolba ng OmniRoute:** +**How OmniRoute solves it:** -- **Auto Token Refresh** — Ang mga token ng OAuth ay nagre-refresh sa background bago mag-expire -- **OAuth 2.0 (PKCE) Built-in** — Awtomatikong daloy para sa Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow -- **Multi-Account OAuth** — Maramihang account bawat provider sa pamamagitan ng pagkuha ng token ng JWT/ID -- **OAuth LAN/Remote Fix** — Pribadong IP detection para sa `redirect_uri` + manual URL mode para sa mga malalayong server -- **OAuth Behind Nginx** — Gumagamit ng `window.location.origin` para sa reverse proxy compatibility -- **Remote OAuth Guide** — Step-by-step na gabay para sa mga kredensyal ng Google Cloud sa VPS/Docker +- **Auto Token Refresh** — OAuth tokens refresh in background before expiration +- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow +- **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. "Hindi ko alam kung magkano ang ginagastos ko o kung saan"
+📊 9. "I don't know how much I'm spending or where"
-Gumagamit ang mga developer ng maraming bayad na provider ngunit walang pinag-isang pagtingin sa paggastos. Ang bawat provider ay may sariling dashboard ng pagsingil, ngunit walang pinagsama-samang view. Maaaring tumambak ang mga hindi inaasahang gastos. +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. -**Paano ito niresolba ng OmniRoute:** +**How OmniRoute solves it:** -- **Cost Analytics Dashboard** — Per-token cost tracking at pamamahala ng badyet bawat provider -- **Mga Limitasyon sa Badyet bawat Tier** — Paggastos ng kisame sa bawat tier na nagti-trigger ng awtomatikong fallback -- **Per-Model Pricing Configuration** — Nako-configure na mga presyo bawat modelo -- **Mga Istatistika ng Paggamit Bawat API Key** — Bilang ng kahilingan at timestamp na huling ginamit bawat key -- **Analytics Dashboard** — Mga stat card, chart ng paggamit ng modelo, talahanayan ng provider na may mga rate ng tagumpay at latency +- **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. "Hindi ko matukoy ang mga error at problema sa mga tawag sa AI"
+🐛 10. "I can't diagnose errors and problems in AI calls"
-Kapag nabigo ang isang tawag, hindi alam ng dev kung ito ay isang limitasyon sa rate, nag-expire na token, maling format, o error sa provider. Mga fragment na log sa iba't ibang terminal. Kung walang pagmamasid, ang pag-debug ay trial-and-error. +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. -**Paano ito niresolba ng OmniRoute:** +**How OmniRoute solves it:** -- **Unified Logs Dashboard** — 4 na tab: Request Logs, Proxy Logs, Audit Logs, Console -- **Console Log Viewer** — Real-time na terminal-style viewer na may color-coded level, auto-scroll, paghahanap, filter -- **SQLite Proxy Logs** — Mga paulit-ulit na log na nakaligtas sa pag-restart ng server -- **Translator Playground** — 4 na mode ng pag-debug: Playground (pagsasalin ng format), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time) +- **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 Proxy Logs** — Persistent logs that survive server restarts +- **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 -- **Pag-log na Nakabatay sa File na may Pag-ikot** — Kinukuha ng Console interceptor ang lahat sa log ng JSON na may pag-ikot batay sa laki +- **File-Based Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation +- **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. "Ang pag-deploy at pagpapanatili ng gateway ay kumplikado"
+🏗️ 11. "Deploying and maintaining the gateway is complex"
-Ang pag-install, pag-configure, at pagpapanatili ng AI proxy sa iba't ibang kapaligiran (lokal, VPS, Docker, cloud) ay labor-intensive. Ang mga problema tulad ng mga hardcoded na path, `EACCES` sa mga direktoryo, port conflict, at cross-platform build ay nagdaragdag ng friction. +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. -**Paano ito niresolba ng OmniRoute:** +**How OmniRoute solves it:** -- **npm global install** — `npm install -g omniroute && omniroute` — tapos na +- **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` (walang CLI tool) at `cli` (na may Claude Code, Codex, OpenClaw) -- **Electron Desktop App** — Native app para sa Windows/macOS/Linux na may system tray, auto-start, offline mode -- **Split-Port Mode** — API at Dashboard sa magkahiwalay na port para sa mga advanced na sitwasyon (reverse proxy, container networking) -- **Cloud Sync** — I-configure ang pag-synchronize sa mga device sa pamamagitan ng Cloudflare Workers -- **DB Backup** — Awtomatikong pag-backup, pagpapanumbalik, pag-export at pag-import ng lahat ng mga setting +- **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
-
🌍 12. "Ang interface ay English-only at ang aking team ay hindi nagsasalita ng English"
+🌍 12. "The interface is English-only and my team doesn't speak English"
-Ang mga koponan sa mga bansang hindi nagsasalita ng Ingles, lalo na sa Latin America, Asia, at Europe, ay nakikipagpunyagi sa mga interface na Ingles lamang. Binabawasan ng mga hadlang sa wika ang pag-aampon at pinapataas ang mga error sa pagsasaayos. +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. -**Paano ito niresolba ng OmniRoute:** +**How OmniRoute solves it:** -- **Dashboard i18n — 30 Wika** — Lahat ng 500+ key na isinalin kasama ang 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, Vietnamese -- **RTL Support** — Kanan-pakaliwa na suporta para sa Arabic at Hebrew -- **Multi-Language READMEs** — 30 kumpletong pagsasalin ng dokumentasyon -- **Language Selector** — Globe icon sa header para sa real-time na paglipat +- **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. "Kailangan ko ng higit pa sa chat — kailangan ko ng mga embed, larawan, audio"
+🔄 13. "I need more than chat — I need embeddings, images, audio"
-Ang AI ay hindi lamang pagkumpleto ng chat. Kailangan ng mga dev na bumuo ng mga larawan, mag-transcribe ng audio, gumawa ng mga pag-embed para sa RAG, mag-rerank ng mga dokumento, at katamtamang nilalaman. Ang bawat API ay may iba't ibang endpoint at format. +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. -**Paano ito niresolba ng OmniRoute:** +**How OmniRoute solves it:** -- **Mga Pag-embed** — `/v1/embeddings` na may 6 na provider at 9+ na modelo -- **Pagbuo ng Larawan** — `/v1/images/generations` na may 10 provider at 20+ modelo (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI) -- **Text-to-Video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) at SD WebUI +- **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, + mga kasalukuyang provider -- **Moderations** — `/v1/moderations` — Mga pagsusuri sa kaligtasan ng content -- **Muling pagraranggo** — `/v1/rerank` — Muling pagraranggo ng kaugnayan ng dokumento -- **Responses API** — Buong `/v1/responses` na suporta para sa Codex +- **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. "Wala akong paraan para subukan at paghambingin ang kalidad sa mga modelo"
+🧪 14. "I have no way to test and compare quality across models"
-Gustong malaman ng mga developer kung aling modelo ang pinakamainam para sa kanilang kaso ng paggamit — code, pagsasalin, pangangatwiran — ngunit mabagal ang paghahambing nang manu-mano. Walang pinagsamang mga tool sa eval ang umiiral. +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. -**Paano ito niresolba ng OmniRoute:** +**How OmniRoute solves it:** -- **LLM Evaluations** — Golden set testing na may 10 pre-loaded na case na sumasaklaw sa mga pagbati, matematika, heograpiya, pagbuo ng code, pagsunod sa JSON, pagsasalin, markdown, pagtanggi sa kaligtasan -- **4 na Istratehiya sa Pagtutugma** — `exact`, `contains`, `regex`, `custom` (JS function) -- **Translator Playground Test Bench** — Batch testing na may maraming input at inaasahang output, cross-provider na paghahambing -- **Chat Tester** — Buong round-trip na may visual response rendering -- **Live Monitor** — Real-time na stream ng lahat ng kahilingang dumadaloy sa proxy +- **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. "Kailangan kong mag-scale nang hindi nawawala ang performance"
+📈 15. "I need to scale without losing performance"
-Habang lumalaki ang dami ng kahilingan, nang walang pag-cache sa parehong mga tanong ay bumubuo ng mga dobleng gastos. Nang walang idempotency, humihiling ang duplicate sa pagpoproseso ng basura. Dapat igalang ang mga limitasyon sa rate ng bawat provider. +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. -**Paano ito niresolba ng OmniRoute:** +**How OmniRoute solves it:** -- **Semantic Cache** — Ang two-tier na cache (pirma + semantiko) ay binabawasan ang gastos at latency -- **Request Idempotency** — 5s deduplication window para sa magkaparehong mga kahilingan -- **Pagtukoy sa Limitasyon ng Rate** — RPM ng bawat provider, min na gap, at max na kasabay na pagsubaybay +- **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 - **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence -- **API Key Validation Cache** — 3-tier na cache para sa performance ng produksyon -- **Health Dashboard na may Telemetry** — p50/p95/p99 latency, cache stats, uptime +- **API Key Validation Cache** — 3-tier cache for production performance +- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
-
🤖 16. "Gusto kong kontrolin ang gawi ng modelo sa buong mundo"
+🤖 16. "I want to control model behavior globally"
-Mga developer na gusto ang lahat ng tugon sa isang partikular na wika, na may partikular na tono, o gustong limitahan ang mga token ng pangangatwiran. Ang pag-configure nito sa bawat tool/kahilingan ay hindi praktikal. +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. -**Paano ito niresolba ng OmniRoute:** +**How OmniRoute solves it:** -- **System Prompt Injection** — Inilapat ang pandaigdigang prompt sa lahat ng kahilingan -- **Thinking Budget Validation** — Reasoning token allocation control bawat kahilingan (passthrough, auto, custom, adaptive) -- **6 Mga Istratehiya sa Pagruruta** — Mga pandaigdigang diskarte na tumutukoy kung paano ipinamamahagi ang mga kahilingan -- **Wildcard Router** — Ang mga pattern ng `provider/*` ay dynamic na ruta sa anumang provider -- **Combo Enable/Disable Toggle** — I-toggle ang mga combo nang direkta mula sa dashboard -- **Toggle ng Provider** — I-enable/i-disable ang lahat ng koneksyon para sa isang provider sa isang click -- **Mga Naka-block na Provider** — Ibukod ang mga partikular na provider mula sa listahan ng `/v1/models` +- **System Prompt Injection** — Global prompt applied to all requests +- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive) +- **6 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 +- **Provider Toggle** — Enable/disable all connections for a provider with one click +- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
-
🧰 17. "Kailangan ko ng mga tool sa MCP bilang mga first-class na kakayahan ng produkto"
+🧰 17. "I need MCP tools as first-class product capabilities"
-Maraming AI gateway ang naglalantad sa MCP bilang isang nakatagong detalye ng pagpapatupad. Ang mga koponan ay nangangailangan ng isang nakikita, napapamahalaang layer ng operasyon. +Many AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer. -**Paano ito niresolba ng OmniRoute:** +**How OmniRoute solves it:** -- Lumilitaw ang MCP sa dashboard navigation at tab ng endpoint protocol -- Nakatuon na pahina ng pamamahala ng MCP na may proseso, mga tool, saklaw, at pag-audit -- Built-in na quick-start para sa `omniroute --mcp` at onboarding ng kliyente +- 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. "Kailangan ko ng A2A orchestration na may sync + stream task path"
+🧠 18. "I need A2A orchestration with sync + stream task paths"
-Ang mga daloy ng trabaho ng ahente ay nangangailangan ng parehong direktang tugon at matagal na naka-stream na pagpapatupad na may kontrol sa lifecycle. +Agent workflows need both direct replies and long-running streamed execution with lifecycle control. -**Paano ito niresolba ng OmniRoute:** +**How OmniRoute solves it:** -- A2A JSON-RPC endpoint (`POST /a2a`) na may `message/send` at `message/stream` -- SSE streaming na may terminal state propagation -- Mga task lifecycle API para sa `tasks/get` at `tasks/cancel` +- 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. "Kailangan ko ng totoong kalusugan ng proseso ng MCP, hindi nahulaan ang status"
+🛰️ 19. "I need real MCP process health, not guessed status"
-Kailangang malaman ng mga operational team kung talagang buhay ang MCP, hindi lang kung maaabot ang isang API. +Operational teams need to know if MCP is actually alive, not just whether an API is reachable. -**Paano ito niresolba ng OmniRoute:** +**How OmniRoute solves it:** -- Runtime heartbeat file na may PID, timestamp, transport, bilang ng tool, at mode ng saklaw -- MCP status API na pinagsasama ang tibok ng puso + kamakailang aktibidad -- Mga UI status card para sa pagiging bago ng proseso/uptime/heartbeat +- 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. "Kailangan ko ng auditable MCP tool execution"
+📋 20. "I need auditable MCP tool execution"
-Kapag ang mga tool ay nag-mutate ng config o nag-trigger ng mga pagkilos ng ops, ang mga team ay nangangailangan ng forensic traceability. +When tools mutate config or trigger ops actions, teams need forensic traceability. -**Paano ito niresolba ng OmniRoute:** +**How OmniRoute solves it:** -- SQLite-backed audit logging para sa mga tawag sa tool ng MCP -- Mga filter ayon sa tool, tagumpay/kabiguan, API key, at pagination -- Dashboard audit table + stats endpoints para sa automation +- 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. "Kailangan ko ng mga saklaw na pahintulot ng MCP sa bawat pagsasama"
+🔐 21. "I need scoped MCP permissions per integration"
-Ang iba't ibang mga kliyente ay dapat magkaroon ng hindi gaanong pribilehiyong pag-access sa mga kategorya ng tool. +Different clients should have least-privilege access to tool categories. -**Paano ito niresolba ng OmniRoute:** +**How OmniRoute solves it:** -- 9 na butil na saklaw ng MCP para sa kontroladong pag-access ng tool -- Pagpapatupad ng saklaw at kakayahang makita sa UI ng pamamahala ng MCP -- Ligtas na default na postura para sa operational tooling +- 9 granular MCP scopes for controlled tool access +- Scope enforcement and visibility in MCP management UI +- Safe default posture for operational tooling
-
⚙️ 22. "Kailangan ko ng mga kontrol sa pagpapatakbo nang hindi nagre-redeploy"
+⚙️ 22. "I need operational controls without redeploying"
-Ang mga koponan ay nangangailangan ng mabilis na mga pagbabago sa runtime sa panahon ng mga insidente o mga kaganapan sa gastos. +Teams need quick runtime changes during incidents or cost events. -**Paano ito niresolba ng OmniRoute:** +**How OmniRoute solves it:** -- Lumipat ng combo activation nang direkta mula sa MCP dashboard -- Ilapat ang mga profile ng katatagan mula sa paunang natukoy na mga pack ng patakaran -- I-reset ang estado ng circuit breaker mula sa parehong panel ng mga operasyon +- Switch combo activation directly from MCP dashboard +- Apply resilience profiles from pre-defined policy packs +- Reset circuit breaker state from the same operations panel
-
🔄 23. "Kailangan ko ng live A2A task lifecycle visibility at pagkansela"
+🔄 23. "I need live A2A task lifecycle visibility and cancellation"
-Kung walang lifecycle visibility, ang mga insidente ng gawain ay nagiging mahirap subukan. +Without lifecycle visibility, task incidents become hard to triage. -**Paano ito niresolba ng OmniRoute:** +**How OmniRoute solves it:** -- Listahan ng gawain/pag-filter ayon sa estado/kasanayan sa pagination -- Mag-drill-down sa metadata ng gawain, mga kaganapan, at mga artifact -- Endpoint ng pagkansela ng gawain at pagkilos ng UI na may kumpirmasyon +- 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. "Kailangan ko ng mga aktibong sukatan ng stream para sa A2A load"
+🌊 24. "I need active stream metrics for A2A load"
-Ang mga stream ng workflow ay nangangailangan ng operational insight sa concurrency at live na koneksyon. +Streaming workflows require operational insight into concurrency and live connections. -**Paano ito niresolba ng OmniRoute:** +**How OmniRoute solves it:** -- Mga aktibong stream counter na isinama sa A2A status -- Mga bilang ng huling timestamp ng gawain at bawat estado -- A2A dashboard card para sa real-time na pagsubaybay sa ops +- Active stream counters integrated into A2A status +- Last task timestamp and per-state counts +- A2A dashboard cards for real-time ops monitoring
-
🪪 25. "Kailangan ko ng karaniwang pagtuklas ng ahente para sa mga kliyente"
+🪪 25. "I need standard agent discovery for clients"
-Ang mga panlabas na kliyente at orkestra ay nangangailangan ng metadata na nababasa ng makina para sa onboarding. +External clients and orchestrators need machine-readable metadata for onboarding. -**Paano ito niresolba ng OmniRoute:** +**How OmniRoute solves it:** -- Nalantad ang Agent Card sa `/.well-known/agent.json` -- Mga kakayahan at kasanayan na ipinapakita sa management UI -- Kasama sa A2A status API ang metadata ng pagtuklas para sa automation +- Agent Card exposed at `/.well-known/agent.json` +- Capabilities and skills shown in management UI +- A2A status API includes discovery metadata for automation
-
🧭 26. "Kailangan ko ang pagtuklas ng protocol sa UX ng produkto"
+🧭 26. "I need protocol discoverability in the product UX"
-Kung hindi matuklasan ng mga user ang mga surface ng protocol, bumababa ang kalidad ng pag-aampon at suporta. +If users cannot discover protocol surfaces, adoption and support quality drop. -**Paano ito niresolba ng OmniRoute:** +**How OmniRoute solves it:** -- Mga entry sa sidebar para sa MCP at A2A -- Tab na Mga Protokol ng pahina ng Endpoint na may mabilis na pagsisimula at katayuan -- Mga link mula sa pangkalahatang-ideya hanggang sa nakalaang mga dashboard ng pamamahala +- 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. "Kailangan ko ng end-to-end protocol validation sa mga totoong kliyente"
+🧪 27. "I need end-to-end protocol validation with real clients"
-Ang mga kunwaring pagsubok ay hindi sapat upang patunayan ang pagiging tugma ng protocol bago ilabas. +Mock tests are not enough to validate protocol compatibility before release. -**Paano ito niresolba ng OmniRoute:** +**How OmniRoute solves it:** -- E2E suite na nagbo-boot ng app at gumagamit ng totoong MCP SDK client transport -- Mga pagsubok sa A2A client para sa pagtuklas, pagpapadala, pag-stream, pagkuha, at pagkansela ng mga daloy -- Cross-check assertion laban sa MCP audit at A2A tasks API +- 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. "Kailangan ko ng pinag-isang observability sa lahat ng interface"
+📡 28. "I need unified observability across all interfaces"
-Ang paghahati ng observability sa pamamagitan ng protocol ay lumilikha ng mga blind spot at mas mahabang MTTR. +Splitting observability by protocol creates blind spots and longer MTTR. -**Paano ito niresolba ng OmniRoute:** +**How OmniRoute solves it:** -- Pinag-isang mga dashboard/log/analytics sa isang produkto -- Health + audit + humiling ng telemetry sa mga layer ng OpenAI, MCP, at A2A -- Mga Operational API para sa status at automation +- Unified dashboards/logs/analytics in one product +- Health + audit + request telemetry across OpenAI, MCP, and A2A layers +- Operational APIs for status and automation
-
💼 29. "Kailangan ko ng isang runtime para sa proxy + tool + orkestrasyon ng ahente"
+💼 29. "I need one runtime for proxy + tools + agent orchestration"
-Ang pagpapatakbo ng maraming magkakahiwalay na serbisyo ay nagpapataas ng gastos sa pagpapatakbo at mga mode ng pagkabigo. +Running many separate services increases operational cost and failure modes. -**Paano ito niresolba ng OmniRoute:** +**How OmniRoute solves it:** -- OpenAI-compatible na proxy, MCP server, at A2A server sa isang stack -- Nakabahaging auth, resilience, data store, at observability -- Pare-parehong modelo ng patakaran sa lahat ng surface ng pakikipag-ugnayan +- 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
-
-### Mga Halimbawang Playbook
+### Example Playbooks (Integrated Use Cases)
-**Playbook A: I-maximize ang bayad na subscription + murang backup**
+**Playbook A: Maximize paid subscription + cheap backup**
```txt
Combo: "maximize-claude"
@@ -708,65 +719,132 @@ Combo: "always-on"
Outcome: deep fallback depth for deadline-critical workloads
```
-**Playbook D: Ahente ops sa MCP + A2A**
+**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/mcp and /dashboard/a2a
-4) Control incidents with resilience profile + task cancellation
+3) Observe via /dashboard/endpoint (MCP and A2A tabs)
+4) Toggle services via inline status controls
```
---
-## ⚡ Mabilis na Pagsisimula
+## 🆓 Start Free — Zero Configuration Cost
-**1. I-install sa buong mundo:**
+> 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 **iFlow** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |
+| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |
+| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |
+| 5 | `/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).
+
+## Mabilis na Simula
+
+### 1) Install and run
```bash
npm install -g omniroute
omniroute
```
-🎉 Magbubukas ang dashboard sa `http://localhost:20128`
+> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:
+>
+> ```bash
+> pnpm install -g omniroute
+> pnpm approve-builds -g # Select all packages → approve
+> omniroute
+> ```
-| Utos | Paglalarawan |
-| ----------------------- | --------------------------------------- |
-| `omniroute` | Simulan ang server (default port 20128) |
-| `omniroute --port 3000` | Gumamit ng custom na port |
-| `omniroute --no-open` | Huwag awtomatikong buksan ang browser |
-| `omniroute --help` | Ipakita ang tulong |
+Dashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.
-**2. Ikonekta ang isang LIBRENG provider:**
+| 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 |
-Dashboard → Mga Provider → Ikonekta ang **Claude Code** o **Antigravity** → OAuth login → Tapos na!
+Optional split-port mode:
-**3. Gamitin sa iyong CLI tool:**
-
-```
-Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Settings:
- Endpoint: http://localhost:20128/v1
- API Key: [copy from dashboard]
- Model: if/kimi-k2-thinking
+```bash
+PORT=20128 DASHBOARD_PORT=20129 omniroute
+# API: http://localhost:20128/v1
+# Dashboard: http://localhost:20129
```
-**Iyon na!** Magsimulang mag-coding gamit ang LIBRENG mga modelo ng AI.
+### 2) Connect providers and create your API key
-**Alternatibong — tumakbo mula sa pinagmulan:**
+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
+
+```txt
+Base URL: http://localhost:20128/v1
+API Key: [copy from Endpoint page]
+Model: if/kimi-k2-thinking (or any provider/model prefix)
+```
+
+Works with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.
+
+### 4) Enable and validate protocols (v2.0)
+
+**MCP (for tool-driven operations):**
+
+```bash
+omniroute --mcp
+```
+
+Then connect your MCP client over `stdio` and test tools like:
+
+- `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 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
+PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev
```
---
## 🐳 Docker
-Available ang OmniRoute bilang isang pampublikong larawan ng Docker sa [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
+OmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
-**Mabilis na pagtakbo:**
+**Quick run:**
```bash
docker run -d \
@@ -777,7 +855,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Na may environment file:**
+**With environment file:**
```bash
# Copy and edit .env first
@@ -792,7 +870,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Gumagamit ng Docker Compose:**
+**Using Docker Compose:**
```bash
# Base profile (no CLI tools)
@@ -802,257 +880,550 @@ docker compose --profile base up -d
docker compose --profile cli up -d
```
-| Larawan | Tag | Sukat | Paglalarawan |
-| ------------------------ | -------- | ------ | ------------------------------ |
-| `diegosouzapw/omniroute` | `latest` | ~250MB | Pinakabagong stable na release |
-| `diegosouzapw/omniroute` | `1.0.3` | ~250MB | Kasalukuyang bersyon |
+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.
+- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.
+- 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` | `1.0.3` | ~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
+### Mabilis na Simula
+
```bash
-npm run electron:dev # Development mode
+# 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)
+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)
---
-## 💰 Pagpepresyo sa isang Sulyap
+## 💰 Pricing at a Glance
-| Tier | Provider | Gastos | I-reset ang Quota | Pinakamahusay Para sa |
-| ------------------- | ----------------- | ------------------------ | -------------------- | ------------------------------- |
-| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/buwan | 5h + lingguhan | Naka-subscribe na |
-| | Codex (Plus/Pro) | $20-200/buwan | 5h + lingguhan | Mga user ng OpenAI |
-| | Gemini CLI | **LIBRE** | 180K/buwan + 1K/araw | Lahat! |
-| | GitHub Copilot | $10-19/buwan | Buwanang | Mga user ng GitHub |
-| **🔑 API KEY** | NVIDIA NIM | **LIBRE** (1000 credits) | Isang beses | Libreng tier na pagsubok |
-| | DeepSeek | Pay-per-use | Wala | Pinakamahusay na presyo/kalidad |
-| | Groq | Libreng tier + bayad | Limitado ang rate | Napakabilis na hinuha |
-| | xAI (Grok) | Pay-per-use | Wala | Mga modelong Grok |
-| | Mistral | Libreng tier + bayad | Limitado ang rate | European AI |
-| | OpenRouter | Pay-per-use | Wala | 100+ modelo |
-| **💰 MURA** | GLM-4.7 | $0.6/1M | Araw-araw 10AM | Backup ng badyet |
-| | MiniMax M2.1 | $0.2/1M | 5 oras na rolling | Pinaka murang opsyon |
-| | Kimi K2 | $9/buwan flat | 10M token/buwan | Nahuhulaang gastos |
-| **🆓 LIBRE** | iFlow | $0 | Walang limitasyong | 8 mga modelong libre |
-| | Qwen | $0 | Walang limitasyong | 3 mga modelong libre |
-| | Kiro | $0 | Walang limitasyong | Claude libre |
+| 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 |
+| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |
+| | 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** | iFlow | **$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 |
-**💡 Pro Tip:** Magsimula sa Gemini CLI (180K libre/buwan) + iFlow (walang limitasyong libre) combo = $0 na halaga!
+> 🆕 **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
+iFlow (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.
---
-## 💡 Mga Pangunahing Tampok
+---
-### 🧠 Core Routing at Intelligence
+## 🆓 Free Models — What You Actually Get
-| Tampok | Ano ang Ginagawa Nito |
-| ------------------------------- | -------------------------------------------------------------------------------------------- |
-| 🎯 **Smart 4-Tier Fallback** | Auto-ruta: Subscription → API Key → Mura → Libre |
-| 📊 **Real-Time Quota Tracking** | Live na bilang ng token + reset countdown bawat provider |
-| 🔄 **Format Translation** | OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro seamless + response sanitization |
-| 👥 **Suporta sa Multi-Account** | Maramihang account sa bawat provider na may matalinong pagpili |
-| 🔄 **Auto Token Refresh** | Awtomatikong nagre-refresh ang mga token ng OAuth sa muling pagsubok |
-| 🎨 **Mga Custom na Combos** | 6 na diskarte: fill-first, round-robin, p2c, random, hindi gaanong ginagamit, cost-optimized |
-| 🧩 **Mga Custom na Modelo** | Magdagdag ng anumang ID ng modelo sa anumang provider |
-| 🌐 **Wildcard Router** | Iruta ang `provider/*` na mga pattern sa anumang provider nang dynamic na |
-| 🧠 **Badyet sa Pag-iisip** | Passthrough, auto, custom, at adaptive mode para sa mga modelo ng pangangatwiran |
-| 🔀 **Model Aliases** | Auto-forward deprecated model IDs to current replacements (built-in + custom) |
-| ⚡ **Background Degradation** | Auto-route background tasks (titles, summaries) to cheaper models |
-| 💬 **System Prompt Injection** | Inilapat ang global system prompt sa lahat ng kahilingan |
-| 📄 **Responses API** | Buong OpenAI Responses API (`/v1/responses`) na suporta para sa Codex |
+> 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.
-### 🎵 Mga Multi-Modal na API
+### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)
-| Tampok | Ano ang Ginagawa Nito |
+| 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 |
+
+### 🟢 IFLOW MODELS (Free OAuth — No Credit Card)
+
+| 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 |
+
+### 🟡 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) |
+
+### 🟣 GEMINI CLI (Google OAuth)
+
+| Model | Prefix | Limit | Rate Limit |
+| ------------------------ | ------ | --------------------------- | ------------- |
+| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |
+| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |
+
+### ⚫ 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
+> iFlow (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 v2.0 is built as an operational platform, not just a relay proxy.
+
+### 🆕 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 Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |
+| 🤖 **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 (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) |
+| 🤝 **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** | 9 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 combo, apply resilience profiles, reset breakers from one control surface |
+
+### 🧠 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** | 6 balancing strategies + fallback chain control |
+| 🌐 **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) |
+| 💬 **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 |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 🖼️ **Pagbuo ng Larawan** | `/v1/images/generations` — 4 na provider, 9+ na modelo |
-| 📐 **Mga Pag-embed** | `/v1/embeddings` — 6 na provider, 9+ na modelo |
+| 🖼️ **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) |
-| 🛡️ **Mga Pag-moderate** | `/v1/moderations` — Mga pagsusuri sa kaligtasan ng nilalaman |
-| 🔀 **Reranking** | `/v1/rerank` — Muling pagraranggo ng kaugnayan ng dokumento |
+| 🔊 **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 |
-### 🛡️ Katatagan at Seguridad
+### 🛡️ Resilience, Security & Governance
-| Tampok | Ano ang Ginagawa Nito |
-| ----------------------------------------- | -------------------------------------------------------------------------------------- |
-| 🔌 **Circuit Breaker** | Awtomatikong buksan/isara ang bawat provider na may mga na-configure na threshold |
-| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |
-| 🛡️ **Anti-Thundering Herd** | Mutex + semaphore rate-limit para sa mga API key provider |
-| 🧠 **Semantic Cache** | Binabawasan ng two-tier na cache (pirma + semantiko) ang gastos at latency |
-| ⚡ **Humiling ng Idempotency** | 5s dedup window para sa mga duplicate na kahilingan |
-| 🔒 **TLS Fingerprint Spoofing** | I-bypass ang TLS-based na bot detection sa pamamagitan ng wreq-js |
-| 🔏 **CLI Fingerprint Matching** | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP** |
-| 🌐 **Pag-filter ng IP** | Allowlist/blocklist para sa API access control |
-| 📊 **Mga Nae-edit na Limitasyon sa Rate** | Configurable RPM, min gap, at max na kasabay sa antas ng system |
-| 💾 **Rate Limit Persistence** | Learned limits survive restarts via SQLite with 60s debounce + 24h staleness |
-| 🔄 **Token Refresh Resilience** | Per-provider circuit breaker (5 fails→30min) + 30s timeout per attempt |
-| 🛡 **Proteksyon sa Endpoint ng API** | Auth gating + pagharang ng provider para sa `/models` endpoint |
-| 🔒 **Proxy Visibility** | Mga color-coded na badge: 🟢 global, 🟡 provider, 🔵 per-connection na may IP display |
-| 🌐 **3-Level Proxy Config** | I-configure ang mga proxy sa global, per-provider, o per-connection level |
+| Feature | What It Does |
+| ----------------------------------- | -------------------------------------------------------------------------------------- |
+| 🔌 **Circuit Breakers** | Per-model trip/recover with threshold controls |
+| 🎯 **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 |
+| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |
+| 🔑 **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 |
-### 📊 Pagmamasid at Analytics
+### 📊 Observability & Analytics
-| Tampok | Ano ang Ginagawa Nito |
-| -------------------------------- | -------------------------------------------------------------------------------------------- |
-| 📝 **Kahilingan sa Pag-log** | Debug mode na may buong kahilingan/tugon logs |
-| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |
-| 💾 **SQLite Proxy Logs** | Ang mga paulit-ulit na proxy log ay nakaligtas sa pag-restart ng server |
-| 📊 **Analytics Dashboard** | Recharts-powered: mga stat card, chart ng paggamit ng modelo, talahanayan ng provider |
-| 📈 **Pagsubaybay sa Pag-unlad** | Mag-opt-in sa mga kaganapan sa pag-usad ng SSE para sa streaming |
-| 🧪 **Mga Pagsusuri sa LLM** | Golden set testing na may 4 na diskarte sa pagtutugma |
-| 🔍 **Humiling ng Telemetry** | p50/p95/p99 latency aggregation + X-Request-Id tracing |
-| 📋 **Dashboard ng Mga Log** | Pinag-isang 4-tab na pahina: Mga Log ng Kahilingan, Mga Proxy Log, Mga Log ng Audit, Console |
-| 🖥️ **Console Log Viewer** | Real-time na terminal-style viewer na may level filter, search, auto-scroll |
-| 📑 **File-Based Logging** | Kinukuha ng Console interceptor ang lahat ng output sa JSON log file na may pag-ikot |
-| 🏥 **Dashboard ng Kalusugan** | System uptime, circuit breaker states, lockouts, cache stats |
-| 💰 **Pagsubaybay sa Gastos** | Pamamahala ng badyet + configuration ng pagpepresyo sa bawat modelo |
+| Feature | What It Does |
+| -------------------------------- | ----------------------------------------------------- |
+| 📝 **Request + Proxy Logging** | Full request/response and proxy logging |
+| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |
+| 📋 **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 |
-### ☁️ Deployment at Pag-sync
+### ☁️ Deployment & Platform
-| Tampok | Ano ang Ginagawa Nito |
-| ----------------------------------- | ----------------------------------------------------------------------------------------------- |
-| 💾 **Cloud Sync** | I-sync ang config sa mga device sa pamamagitan ng Cloudflare Workers |
-| 🌐 **I-deploy Kahit Saan** | Localhost, VPS, Docker, Cloudflare Workers |
-| 🔑 **API Key Management** | Bumuo, paikutin, at saklawin ang mga API key sa bawat provider |
-| 🧙 **Onboarding Wizard** | 4-step guided setup para sa mga unang beses na user |
-| 🔧 **CLI Tools Dashboard** | One-click configure Claude, Codex, Cline, OpenClaw, Kilo, Antigravity |
-| 🔄 **Mga Backup ng DB** | Awtomatikong pag-backup, pagpapanumbalik, pag-export at pag-import para sa lahat ng mga setting |
-| 🌐 **Internasyonalisasyon** | Buong i18n na may next-intl — suporta sa English + Portuguese (Brazil) |
-| 🌍 **Pili ng Wika** | Globe icon sa header para sa real-time na paglipat ng wika (🇺🇸/🇧🇷) |
-| 🧹 **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 na Direktoryo ng Data** | `DATA_DIR` env var to override default `~/.omniroute` storage path |
+| Feature | What It Does |
+| ----------------------------- | --------------------------------------------------------- |
+| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |
+| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |
+| 💾 **Cloud Sync** | Configuration sync via cloud worker |
+| 🔄 **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 |
+
+### Feature Deep Dive
+
+#### Smart fallback with practical cost control
+
+```txt
+Combo: "my-coding-stack"
+ 1. cc/claude-opus-4-6
+ 2. nvidia/llama-3.3-70b
+ 3. glm/glm-4.7
+ 4. if/kimi-k2-thinking
+```
+
+When quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.
+
+#### 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)
+
+#### 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)
🚀 30. "Kailangan kong magpadala ng mga ahenteng daloy ng trabaho nang walang glue-code sprawl"
+🚀 30. "I need to ship agentic workflows without glue-code sprawl"
-Nawawalan ng bilis ang mga koponan kapag nagtatahi ng maraming ad-hoc na serbisyo at script. +Teams lose velocity when stitching multiple ad-hoc services and scripts. -**Paano ito niresolba ng OmniRoute:** +**How OmniRoute solves it:** -- Pinag-isang endpoint na diskarte para sa mga kliyente at ahente -- Mga built-in na UI sa pamamahala ng protocol at mga daanan sa pagpapatunay ng usok -- Mga pundasyong handa sa produksyon (seguridad, pag-log, katatagan, backup) +- Unified endpoint strategy for clients and agents +- Built-in protocol management UIs and smoke validation paths +- Production-ready foundations (security, logging, resilience, backup)
-` block → `reasoning_content` para sa mga modelo ng pag-iisip
-- **Structured output** — `json_schema` → Gemini's `responseMimeType`/`responseSchema`
-
-### 👥 Multi-Account Support
-
-- Magdagdag ng maramihang mga account sa bawat provider
-- Auto round-robin o priority-based na pagruruta
-- Fallback sa susunod na account kapag naabot ng isa ang quota
-
-### 🔄 Auto Token Refresh
-
-- Awtomatikong nagre-refresh ang mga token ng OAuth bago mag-expire
-- Walang kinakailangang manu-manong muling pagpapatotoo
-- Walang putol na karanasan sa lahat ng provider
-
-### 🎨 Mga Custom na Combos
-
-- Lumikha ng walang limitasyong mga kumbinasyon ng modelo
-- 6 na diskarte: fill-first, round-robin, power-of-two-choices, random, hindi gaanong ginagamit, cost-optimized
-- Magbahagi ng mga combo sa mga device na may Cloud Sync
-
-### 🏥 Dashboard ng Kalusugan
-
-- Katayuan ng system (uptime, bersyon, paggamit ng memorya)
-- Mga estado ng circuit breaker bawat provider (Sarado/Bukas/Kalahating Bukas)
-- Katayuan ng limitasyon sa rate at mga aktibong lockout
-- Mga istatistika ng cache ng lagda
-- Latency telemetry (p50/p95/p99) + prompt cache
-- I-reset ang katayuan ng kalusugan sa isang pag-click
-
-### 🔧 Palaruan ng Tagasalin
-
-Kasama sa OmniRoute ang isang malakas na built-in na Playground ng Translator na may **4 na mode** para sa pag-debug, pagsubok, at pagsubaybay sa mga pagsasalin ng API:
-
-| Mode | Paglalarawan |
-| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **💻 Palaruan** | Direktang pagsasalin ng format — i-paste ang anumang katawan ng kahilingan sa API at agad na makita kung paano ito isinasalin ng OmniRoute sa pagitan ng mga format ng provider (OpenAI ↔ Claude ↔ Gemini ↔ Responses API). May kasamang mga halimbawang template at format ng auto-detection. |
-| **💬 Chat Tester** | Magpadala ng mga totoong kahilingan sa chat sa pamamagitan ng OmniRoute at tingnan ang buong round-trip: ang iyong input, ang isinaling kahilingan, ang tugon ng provider, at ang isinaling tugon pabalik. Napakahalaga para sa pagpapatunay ng combo routing. |
-| **🧪 Test Bench** | Batch testing mode — tumukoy ng maraming test case na may iba't ibang input at inaasahang output, patakbuhin ang mga ito nang sabay-sabay, at paghambingin ang mga resulta sa mga provider at modelo. |
-| **📱 Live Monitor** | Real-time na pagsubaybay sa kahilingan — panoorin ang mga papasok na kahilingan habang dumadaloy ang mga ito sa OmniRoute, tingnan ang mga pagsasalin ng format na nangyayari nang live, at tukuyin kaagad ang mga isyu. |
-
-**Access:** Dashboard → Translator (sidebar)
-
-### 💾 Cloud Sync
-
-- I-sync ang mga provider, combo, at mga setting sa mga device
-- Awtomatikong pag-sync sa background
-- Secure na naka-encrypt na imbakan
+- `GET /api/mcp/status`
+- `GET /api/mcp/tools`
+- `GET /api/mcp/audit`
+- `GET /api/mcp/audit/stats`
-## 🧪 Mga Pagsusuri (Evals)
+📖 Mga Detalye ng Tampok
+🧩 MCP Setup (Model Context Protocol)
-### 🎯 Smart 4-Tier Fallback +Start MCP transport in stdio mode: -Gumawa ng mga combo na may awtomatikong fallback: - -``` -Combo: "my-coding-stack" - 1. cc/claude-opus-4-6 (your subscription) - 2. nvidia/llama-3.3-70b (free NVIDIA API) - 3. glm/glm-4.7 (cheap backup, $0.6/1M) - 4. if/kimi-k2-thinking (free fallback) - -→ Auto switches when quota runs out or errors occur +```bash +omniroute --mcp ``` -### 📊 Real-Time na Pagsubaybay sa Quota +Recommended validation flow: -- Pagkonsumo ng token bawat provider -- I-reset ang countdown (5 oras, araw-araw, lingguhan) -- Pagtatantya ng gastos para sa mga bayad na tier -- Mga ulat sa buwanang paggasta +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. -### 🔄 Pagsasalin ng Format +Useful APIs for automation: -Walang putol na pagsasalin sa pagitan ng mga format: - -- **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **OpenAI Responses** -- Ang iyong CLI tool ay nagpapadala ng OpenAI na format → OmniRoute nagsasalin → Provider ay tumatanggap ng katutubong format -- Gumagana sa anumang tool na sumusuporta sa mga custom na endpoint ng OpenAI -- **Response sanitization** — Tinatanggal ang mga hindi karaniwang field para sa mahigpit na OpenAI SDK compatibility -- **Pag-normalize ng tungkulin** — `developer` → `system` para sa hindi OpenAI; `system` → `user` para sa mga modelo ng GLM/ERNIE -- **Think tag extraction** — `
+
🤝 A2A Setup (Agent2Agent)
-Ang OmniRoute ay may kasamang built-in na balangkas ng pagsusuri upang subukan ang kalidad ng pagtugon ng LLM laban sa isang ginintuang hanay. I-access ito sa pamamagitan ng **Analytics → Evals** sa dashboard. +Discover the agent: -### na Set +```bash +curl http://localhost:20128/.well-known/agent.json +``` -Ang pre-loaded na "OmniRoute Golden Set" ay naglalaman ng 10 test case na sumasaklaw sa: +Send a task: -- Pagbati, matematika, heograpiya, pagbuo ng code -- Pagsunod sa format ng JSON, pagsasalin, markdown -- Pagtanggi sa kaligtasan (nakapipinsalang nilalaman), pagbibilang, lohika ng boolean +```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."}]}}' +``` -### Estratehiya sa Pagsusuri +Manage lifecycle: -| Diskarte | Paglalarawan | Halimbawa | -| ---------- | ------------------------------------------------------------ | -------------------------------- | -| `exact` | Dapat na eksaktong tumugma ang output | `"4"` | -| `contains` | Ang output ay dapat maglaman ng substring (case-insensitive) | `"Paris"` | -| `regex` | Ang output ay dapat tumugma sa regex pattern | `"1.*2.*3"` | -| `custom` | Ang custom na JS function ay nagbabalik ng true/false | `(output) => output.length > 10` | +- `GET /api/a2a/status` +- `GET /api/a2a/tasks` +- `GET /api/a2a/tasks/:id` +- `POST /api/a2a/tasks/:id/cancel` ---- +Operational UI: -## 📖 Gabay sa Pag-setup +- `/dashboard/a2a` for task/state/stream observability and smoke actions + +
-
+
+💳 Mga Tagabigay ng Subscription
+🧪 End-to-end protocol validation
+ +Validate both protocols with real clients: + +```bash +npm run test:protocols:e2e +``` + +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) @@ -1067,7 +1438,7 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Pro Tip:** Gamitin ang Opus para sa mga kumplikadong gawain, Soneto para sa bilis. Sinusubaybayan ng OmniRoute ang quota bawat modelo! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! ### OpenAI Codex (Plus/Pro) @@ -1081,7 +1452,24 @@ Models: cx/gpt-5.1-codex-max ``` -### Gemini CLI (LIBRE 180K/buwan!) +#### 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). + +### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -1093,7 +1481,7 @@ Models: gc/gemini-2.5-pro ``` -**Pinakamahusay na Halaga:** Malaking libreng tier! Gamitin ito bago ang mga bayad na tier. +**Best Value:** Huge free tier! Use this before paid tiers. ### GitHub Copilot @@ -1111,88 +1499,88 @@ Models:
-
🔑 API Key Provider
+🔑 API Key Providers
-### NVIDIA NIM (LIBRE 1000 credits!) +### NVIDIA NIM (FREE developer access — 70+ models) -1. Mag-sign up: [build.nvidia.com](https://build.nvidia.com) -2. Kumuha ng libreng API key (1000 inference credits kasama) -3. Dashboard → Magdagdag ng Provider → NVIDIA NIM: +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` -**Mga Modelo:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, at 50+ pa +**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more -**Pro Tip:** OpenAI-compatible na API — gumagana nang walang putol sa pagsasalin ng format ng OmniRoute! +**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation! ### DeepSeek -1. Mag-sign up: [platform.deepseek.com](https://platform.deepseek.com) -2. Kunin ang API key -3. Dashboard → Magdagdag ng Provider → DeepSeek +1. Sign up: [platform.deepseek.com](https://platform.deepseek.com) +2. Get API key +3. Dashboard → Add Provider → DeepSeek -**Mga Modelo:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` +**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` -### Groq (Magagamit ang Libreng Tier!) +### Groq (Free Tier Available!) -1. Mag-sign up: [console.groq.com](https://console.groq.com) -2. Kunin ang API key (kasama ang libreng tier) -3. Dashboard → Magdagdag ng Provider → Groq +1. Sign up: [console.groq.com](https://console.groq.com) +2. Get API key (free tier included) +3. Dashboard → Add Provider → Groq -**Mga Modelo:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` +**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` -**Pro Tip:** Napakabilis na inference — pinakamahusay para sa real-time na coding! +**Pro Tip:** Ultra-fast inference — best for real-time coding! -### OpenRouter (100+ Modelo) +### OpenRouter (100+ Models) -1. Mag-sign up: [openrouter.ai](https://openrouter.ai) -2. Kunin ang API key -3. Dashboard → Magdagdag ng Provider → OpenRouter +1. Sign up: [openrouter.ai](https://openrouter.ai) +2. Get API key +3. Dashboard → Add Provider → OpenRouter -**Mga Modelo:** I-access ang 100+ na modelo mula sa lahat ng pangunahing provider sa pamamagitan ng iisang API key. +**Models:** Access 100+ models from all major providers through a single API key.
-
💰 Mga Murang Provider (Backup)
+💰 Cheap Providers (Backup)
-### GLM-4.7 (Araw-araw na pag-reset, $0.6/1M) +### GLM-4.7 (Daily reset, $0.6/1M) -1. Mag-sign up: [Zhipu AI](https://open.bigmodel.cn/) -2. Kumuha ng API key mula sa Coding Plan -3. Dashboard → Magdagdag ng API Key: +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` -**Gamitin:** `glm/glm-4.7` +**Use:** `glm/glm-4.7` -**Pro Tip:** Nag-aalok ang Coding Plan ng 3× na quota sa 1/7 na halaga! I-reset araw-araw 10:00 AM. +**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. Mag-sign up: [MiniMax](https://www.minimax.io/) -2. Kunin ang API key -3. Dashboard → Magdagdag ng API Key +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key +3. Dashboard → Add API Key -**Gamitin:** `minimax/MiniMax-M2.1` +**Use:** `minimax/MiniMax-M2.1` -**Pro Tip:** Ang pinakamurang opsyon para sa mahabang konteksto (1M token)! +**Pro Tip:** Cheapest option for long context (1M tokens)! ### Kimi K2 ($9/month flat) -1. Mag-subscribe: [Moonshot AI](https://platform.moonshot.ai/) -2. Kunin ang API key -3. Dashboard → Magdagdag ng API Key +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key +3. Dashboard → Add API Key -**Gamitin:** `kimi/kimi-latest` +**Use:** `kimi/kimi-latest` -**Pro Tip:** Nakapirming $9/buwan para sa 10M token = $0.90/1M epektibong gastos! +**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
-
🆓 LIBRENG Provider (Emergency Backup)
+🆓 FREE Providers (Emergency Backup)
-### iFlow (8 LIBRENG modelo) +### iFlow (5 FREE models via OAuth) ```bash Dashboard → Connect iFlow @@ -1207,7 +1595,7 @@ Models: if/deepseek-r1 ``` -### Qwen (3 LIBRENG modelo) +### Qwen (4 FREE models via Device Code) ```bash Dashboard → Connect Qwen @@ -1219,7 +1607,7 @@ Models: qw/qwen3-coder-flash ``` -### Kiro (Claude LIBRE) +### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro @@ -1234,9 +1622,9 @@ Models:
-
---
-## 🐛 Pag-troubleshoot
+## Pag-troubleshoot
🎨 Lumikha ng mga Combo
+🎨 Create Combos
-### Halimbawa 1: I-maximize ang Subscription → Murang Backup +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -1250,7 +1638,7 @@ Models: Use in CLI: premium-coding ``` -### Halimbawa 2: Libre-Lamang (Zero na Gastos) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -1278,7 +1666,7 @@ Settings → Models → Advanced: ### Claude Code -Gamitin ang pahina ng **CLI Tools** sa dashboard para sa isang pag-click na configuration, o manu-manong i-edit ang `~/.claude/settings.json`. +Use the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually. ### Codex CLI @@ -1291,13 +1679,13 @@ codex "your prompt" ### OpenClaw -**Pagpipilian 1 — Dashboard (inirerekomenda):** +**Option 1 — Dashboard (recommended):** ``` Dashboard → CLI Tools → OpenClaw → Select Model → Apply ``` -**Pagpipilian 2 — Manwal:** I-edit ang `~/.openclaw/openclaw.json`: +**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`: ```json { @@ -1313,9 +1701,9 @@ Dashboard → CLI Tools → OpenClaw → Select Model → Apply } ``` -> **Tandaan:** Ang OpenClaw ay gumagana lamang sa lokal na OmniRoute. Gamitin ang `127.0.0.1` sa halip na `localhost` upang maiwasan ang mga isyu sa paglutas ng IPv6. +> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues. -### Cline / Magpatuloy / RooCode +### Cline / Continue / RooCode ``` Settings → API Configuration: @@ -1325,108 +1713,243 @@ Settings → API Configuration: 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. +
-
-- **Runtime**: Node.js 18–22 LTS (⚠️ Node.js 24+ ay **hindi suportado** — `better-sqlite3` native binary ay hindi tugma)
-- **Wika**: TypeScript 5.9 — **100% TypeScript** sa `src/` at `open-sse/` (v1.0.6)
+## 🛠️ Tech Stack
+
+Mag-click upang palawakin ang gabay sa pag-troubleshoot
+Click to expand troubleshooting guide
-**"Ang modelo ng wika ay hindi nagbigay ng mga mensahe"** +**"Language model did not provide messages"** -- Naubos na ang quota ng provider → Suriin ang tracker ng quota ng dashboard -- Solusyon: Gumamit ng combo fallback o lumipat sa mas murang tier +- Provider quota exhausted → Check dashboard quota tracker +- Solution: Use combo fallback or switch to cheaper tier -**Paglilimita sa rate** +**Rate limiting** -- Out na ang quota ng subscription → Fallback sa GLM/MiniMax -- Magdagdag ng combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Subscription quota out → Fallback to GLM/MiniMax +- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -**Nag-expire ang token ng OAuth** +**OAuth token expired** -- Auto-refresh ng OmniRoute -- Kung magpapatuloy ang mga isyu: Dashboard → Provider → Muling kumonekta +- Auto-refreshed by OmniRoute +- If issues persist: Dashboard → Provider → Reconnect -**Mataas na gastos** +**High costs** -- Suriin ang mga istatistika ng paggamit sa Dashboard → Mga Gastos -- Ilipat ang pangunahing modelo sa GLM/MiniMax -- Gumamit ng libreng tier (Gemini CLI, iFlow) para sa mga hindi kritikal na gawain +- Check usage stats in Dashboard → Costs +- Switch primary model to GLM/MiniMax +- Use free tier (Gemini CLI, iFlow) for non-critical tasks -**Nagbubukas ang dashboard sa maling port** +**Dashboard/API ports are wrong** -- Itakda ang `PORT=20128` at `NEXT_PUBLIC_BASE_URL=http://localhost:20128` +- `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) -**Mga error sa cloud sync** +**Cloud sync errors** -- I-verify ang `BASE_URL` na mga puntos sa iyong running instance -- I-verify ang `CLOUD_URL` na mga puntos sa iyong inaasahang cloud endpoint -- Panatilihing nakahanay ang mga value ng `NEXT_PUBLIC_*` sa mga value sa gilid ng server +- 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 -**Hindi gumagana ang unang pag-login** +**First login not working** -- Suriin ang `INITIAL_PASSWORD` sa `.env` -- Kung hindi nakatakda, ang fallback na password ay `123456` +- Check `INITIAL_PASSWORD` in `.env` +- If unset, fallback password is `123456` -**Walang mga log ng kahilingan** +**No request logs** -- Itakda ang `ENABLE_REQUEST_LOGS=true` sa `.env` +- Set `ENABLE_REQUEST_LOGS=true` in `.env` -**Ang pagsubok sa koneksyon ay nagpapakita ng "Di-wasto" para sa mga provider na katugma sa OpenAI** +**Connection test shows "Invalid" for OpenAI-compatible providers** -- Maraming provider ang hindi naglalantad ng `/models` endpoint -- Kasama sa OmniRoute v1.0.6+ ang fallback validation sa pamamagitan ng mga pagkumpleto ng chat -- Tiyaking may kasamang `/v1` suffix ang base URL +- 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 +### 🔐 OAuth on a Remote Server + -> **⚠️ MAHALAGA para sa usuários com OmniRoute sa VPS/Docker/servidor remoto** +> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server** -### OAuth +#### Why does Antigravity / Gemini CLI OAuth fail on remote servers? -Os provedores **Antigravity** at **Gemini CLI** gamit ang **Google OAuth 2.0** para sa autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo. +The **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console. -Bilang credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para sa `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (hal: `https://omniroute.meuservidor.com`), o Google rejeita a autenticação com: +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 ``` -### Solusyon: I-configure ang suas próprias credenciais OAuth +#### Solution: Configure your own OAuth credentials -Você precisa criar um **OAuth 2.0 Client ID** walang Google Cloud Console com a URI do seu servidor. +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 + +# For Gemini CLI: +GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com +GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +``` + +**6. Restart OmniRoute** + +```bash +# npm: +npm run dev + +# Docker: +docker restart omniroute +``` + +**7. Try connecting again** + +Dashboard → Providers → Antigravity (or Gemini CLI) → OAuth + +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. + +--- + +
+
---
-## 🛠️
+🇧🇷 Versão em Português
+ +#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos? + +Os provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo. + +As credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticação com: + +``` +Error 400: redirect_uri_mismatch +``` + +#### Solução: Configure suas próprias credenciais OAuth + +Você precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor. #### Passo a passo -**1. Mag-access sa Google Cloud Console** +**1. Acesse o Google Cloud Console** Abra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) **2. Crie um novo OAuth 2.0 Client ID** -- Clique em **"+ Lumikha ng Mga Kredensyal"** → **"OAuth client ID"** +- Clique em **"+ Create Credentials"** → **"OAuth client ID"** - Tipo de aplicativo: **"Web application"** -- Pangalan: escolha qualquer nome (hal: `OmniRoute Remote`) +- Nome: escolha qualquer nome (ex: `OmniRoute Remote`) -**3. Idagdag bilang Mga Awtorisadong URI sa Pag-redirect** +**3. Adicione as Authorized Redirect URIs** -Walang campo **"Mga Awtorisadong URI sa pag-redirect"**, idagdag: +No campo **"Authorized redirect URIs"**, adicione: ``` https://seu-servidor.com/callback ``` -> Substitua `seu-servidor.com` pelo domínio ou IP do seu servidor (kasama ang porta se necessário, hal: `http://45.33.32.156:20128/callback`). +> Substitua `seu-servidor.com` pelo domínio ou IP do seu servidor (inclua a porta se necessário, ex: `http://45.33.32.156:20128/callback`). -**4. I-save at kopyahin bilang kredensyal** +**4. Salve e copie as credenciais** -Após criar, o Google mostrará o **Client ID** at ** Client Secret**. +Após criar, o Google mostrará o **Client ID** e o **Client Secret**. -**5. I-configure bilang variáveis de ambiente** +**5. Configure as variáveis de ambiente** No seu `.env` (ou nas variáveis de ambiente do Docker): @@ -1453,150 +1976,145 @@ docker restart omniroute **7. Tente conectar novamente** -Dashboard → Mga Provider → Antigravity (ou Gemini CLI) → OAuth +Dashboard → Providers → Antigravity (ou Gemini CLI) → OAuth -Agora o Google redirectionará corretamente para sa `https://seu-servidor.com/callback` at a autenticação funcionará. +Agora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará. --- #### Workaround temporário (sem configurar credenciais próprias) -Se não quiser criar credenciais próprias agora, may posibilidad na magamit o fluxo **manual de URL**: +Se não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**: -1. OmniRoute abrirá a URL de authorização do Google -2. Após você authorizar, o Google tentará redirectionar para sa `localhost` (que falha no servidor remoto) -3. **Kopyahin ang isang URL completa** sa barra de endereço do seu browser (mesmo que a página não carregue) +1. O OmniRoute abrirá a URL de autorização do Google +2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto) +3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue) 4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute -5. Clique em **"Kumonekta"** +5. Clique em **"Connect"** -> Ang workaround na ito ay gumagana sa pamamagitan ng código de authorização na URL ay maaaring mag-redirect sa iyong carregado ou não. +> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.
+ Limit subskrypcji wygasa niewykorzystany co miesiąc
-- Limity szybkości zatrzymują Cię w połowie kodowania
-- Drogie interfejsy API (20-50 USD miesięcznie na dostawcę)
-- Ręczne przełączanie pomiędzy dostawcami
-
-**OmniRoute rozwiązuje ten problem:**
-
-- ✅ **Maksymalizuj liczbę subskrypcji** - Śledź limit, wykorzystaj każdy bit przed zresetowaniem
-- ✅ **Automatyczny powrót** - Subskrypcja → Klucz API → Tani → Bezpłatny, zero przestojów
-- ✅ **Wiele kont** - Praca okrężna pomiędzy kontami każdego dostawcy
-- ✅ **Uniwersalny** - Działa z Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw i dowolnym narzędziem CLI
-
----
-
-## 📧 Wsparcie
-
-> 💬 **Dołącz do naszej społeczności!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Uzyskaj pomoc, dziel się wskazówkami i bądź na bieżąco.
-
-- **Strona internetowa**: [omniroute.online](https://omniroute.online)
+- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Problemy**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Oryginalny projekt**: [9router by decolua](https://github.com/decolua/9router)
+- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 Jak to działa
+## 🔄 How It Works
```
┌─────────────┐
@@ -227,451 +236,453 @@ Result: Never stop coding, minimal cost
---
-## 🎯 Co rozwiązuje OmniRoute — 30 rzeczywistych problemów i przypadków użycia
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **Każdy programista korzystający z narzędzi AI codziennie spotyka się z tymi problemami.** OmniRoute został stworzony, aby rozwiązać je wszystkie — od przekroczeń kosztów po blokady regionalne, od zepsutych przepływów OAuth po operacje protokołów i obserwowalność przedsiębiorstwa.
+> **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.
Cota de assinatura expira sem uso todo mês
-- Limites de taxa param você no meio da programação
-- APIs caras ($20-50/mês por provedor)
-- Trocar manualmente entre provedores
-
-**OmniRoute resolve isso:**
-
-- ✅ **Maximize assinaturas** - Rastreie cotas, use tudo antes do reset
-- ✅ **Fallback automático** - Assinatura → API Key → Barato → Gratuito, zero tempo de inatividade
-- ✅ **Multi-conta** - Round-robin entre contas por provedor
-- ✅ **Universal** - Funciona com Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, qualquer ferramenta CLI
-
----
-
-## 📧 Suporte
-
-> 💬 **Participe da comunidade!** [Grupo WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Tire dúvidas, compartilhe dicas e fique atualizado.
+> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.
- **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**: [Grupo da Comunidade](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Projeto Original**: [9router por decolua](https://github.com/decolua/9router)
+- **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`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 Como Funciona
+## 🔄 How It Works
```
┌─────────────┐
-│ Sua CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
+│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
│ Tool │
└──────┬──────┘
│ http://localhost:20128/v1
↓
┌─────────────────────────────────────────┐
-│ OmniRoute (Roteador Inteligente) │
-│ • Tradução de formato (OpenAI ↔ Claude) │
-│ • Rastreamento de cota + Embeddings + Imagens │
-│ • Renovação automática de tokens │
+│ OmniRoute (Smart Router) │
+│ • Format translation (OpenAI ↔ Claude) │
+│ • Quota tracking + Embeddings + Images │
+│ • Auto token refresh │
└──────┬──────────────────────────────────┘
│
- ├─→ [Tier 1: ASSINATURA] Claude Code, Codex, Gemini CLI
- │ ↓ cota esgotada
+ ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI
+ │ ↓ quota exhausted
├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.
- │ ↓ limite de orçamento
- ├─→ [Tier 3: BARATO] GLM ($0.6/1M), MiniMax ($0.2/1M)
- │ ↓ limite de orçamento
- └─→ [Tier 4: GRATUITO] iFlow, Qwen, Kiro (ilimitado)
+ │ ↓ budget limit
+ ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)
+ │ ↓ budget limit
+ └─→ [Tier 4: FREE] iFlow, Qwen, Kiro (unlimited)
-Resultado: Nunca pare de programar, custo mínimo
+Result: Never stop coding, minimal cost
```
---
-## 🎯 O que o OmniRoute resolve — 30 dores reais e casos de uso
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **Todo desenvolvedor que usa ferramentas de IA enfrenta esses problemas diariamente.** O OmniRoute foi criado para resolver todos eles, desde estouro de custos e bloqueios regionais até operações de protocolo e observabilidade de nível produção.
+> **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.
-O OmniRoute tem **210+ funcionalidades planejadas** em múltiplas fases de desenvolvimento. Áreas principais:
+## 🛠️ Tech Stack
-| Categoria | Features Planejadas | Destaques |
-| -------------------------------- | ------------------- | --------------------------------------------------------------------------- |
-| 🧠 **Roteamento e Inteligência** | 25+ | Roteamento por menor latência, roteamento por tags, pré-verificação de cota |
-| 🔒 **Segurança e Compliance** | 20+ | Hardening SSRF, cloaking de credenciais, rate-limit por endpoint |
-| 📊 **Observabilidade** | 15+ | Integração OpenTelemetry, monitoramento de cota em tempo real |
-| 🔄 **Integrações** | 20+ | Registro dinâmico de modelos, cooldowns de provedor |
-| ⚡ **Performance** | 15+ | Cache dupla camada, prompt cache, response cache, batch API |
-| 🌐 **Ecossistema** | 10+ | WebSocket API, config hot-reload, modo comercial |
+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**: LowDB (JSON) + SQLite (domain state + proxy logs) -- **Streaming**: Mga Kaganapang Ipinadala ng Server (SSE) -- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys -- **Pagsubok**: Node.js test runner (368+ unit test) +- **Database**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions) +- **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 - ---- - -## 📖 Dokumentasyon - -| Dokumento | Paglalarawan | -| -------------------------------------------- | --------------------------------------------------- | -| [User Guide](docs/USER_GUIDE.md) | Mga provider, combo, CLI integration, deployment | -| [API Reference](docs/API_REFERENCE.md) | Lahat ng mga endpoint na may mga halimbawa | -| [Troubleshooting](docs/TROUBLESHOOTING.md) | Mga karaniwang problema at solusyon | -| [Architecture](docs/ARCHITECTURE.md) | Arkitektura ng system at mga panloob | -| [Contributing](CONTRIBUTING.md) | Pag-setup at mga alituntunin ng pag-unlad | -| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 na detalye | -| [Security Policy](SECURITY.md) | Pag-uulat ng kahinaan at mga kasanayan sa seguridad | -| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Kumpletong gabay: VM + nginx + Cloudflare setup | -| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour na may mga screenshot | - -### 📸 Preview ng Dashboard - -
-
---
-## 🗺️
+## Dokumentasyon
-Ang OmniRoute ay may **210+ feature na binalak** sa maraming yugto ng pag-unlad. Narito ang mga pangunahing lugar:
-
-| Kategorya | Mga Nakaplanong Tampok | Mga Highlight |
-| -------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------- |
-| 🧠 **Routing at Intelligence** | 25+ | Lowest-latency routing, tag-based na routing, quota preflight, P2C account selection |
-| 🔒 **Seguridad at Pagsunod** | 20+ | SSRF hardening, credential cloaking, rate-limit sa bawat endpoint, management key scoping |
-| 📊 **Pagmamasid** | 15+ | Pagsasama ng OpenTelemetry, real-time na pagsubaybay sa quota, pagsubaybay sa gastos bawat modelo |
-| 🔄 **Mga Pagsasama ng Provider** | 20+ | Dynamic na model registry, provider cooldowns, multi-account Codex, Copilot quota parsing |
-| ⚡ **Pagganap** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |
-| 🌐 **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode |
-
-### 🔜 Malapit na
-
-- 🔗 **OpenCode Integration** — Suporta ng katutubong provider para sa OpenCode AI coding IDE
-- 🔗 **TRAE Integration** — Buong suporta para sa balangkas ng pag-develop ng TRAE AI
-- 📦 **Batch API** — Asynchronous na pagproseso ng batch para sa maramihang kahilingan
-- 🎯 **Tag-Based Routing** — Mga kahilingan sa ruta batay sa mga custom na tag at metadata
-- 💰 **Diskarte sa Pinakamababang Gastos** — Awtomatikong piliin ang pinakamurang available na provider
-
-> 📝 Available ang buong detalye ng feature sa [link](docs/new-features/) (217 detalyadong spec)
+| Document | Description |
+| ---------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 16 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/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
+| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
-## 👥 Mga nag-aambag
+## 🗺️ Roadmap
+
+OmniRoute has **210+ 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, P2C account selection |
+| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |
+| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |
+| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider 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
[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
-### Paano Mag-ambag
+### How to Contribute
-1. I-fork ang repositoryo
-2. Gawin ang iyong sangay ng tampok (`git checkout -b feature/amazing-feature`)
-3. Ibigay ang iyong mga pagbabago (`git commit -m 'Add amazing feature'`)
-4. Itulak sa sangay (`git push origin feature/amazing-feature`)
-5. Magbukas ng Pull Request
+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
-Tingnan ang [CONTRIBUTING.md](CONTRIBUTING.md) para sa mga detalyadong alituntunin.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
-### Naglalabas ng Bagong Bersyon
+### Releasing a New Version
```bash
# Create a release — npm publish happens automatically
-gh release create v1.0.6 --title "v1.0.6" --generate-notes
+gh release create v2.0.0 --title "v2.0.0" --generate-notes
```
---
-## 📊 Kasaysayan ng Bituin
+## 📊 Star History
## Stargazers over time
## [](https://starchart.cc/diegosouzapw/OmniRoute)
-## 🙏 Pasasalamat
+## 🙏 Acknowledgments
-Espesyal na pasasalamat kay **[9router](https://github.com/decolua/9router)** ni **[decolua](https://github.com/decolua)** — ang orihinal na proyektong nagbigay inspirasyon sa tinidor na ito. Bumubuo ang OmniRoute sa hindi kapani-paniwalang pundasyong iyon na may mga karagdagang feature, multi-modal na API, at buong TypeScript na muling pagsulat.
+Special thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.
-Espesyal na salamat sa **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — ang orihinal na pagpapatupad ng Go na nagbigay inspirasyon sa JavaScript port na ito.
+Special thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.
---
-## 📄 Lisensya
+## Lisensya
-Lisensya ng MIT - tingnan ang [LICENSE](LICENSE) para sa mga detalye.
+MIT License - see [LICENSE](LICENSE) for details.
---
Mag-click para makita ang mga screenshot ng dashboard
- -| Pahina | Screenshot | -| ----------------------- | ------------------------------------------------- | -| **Mga Provider** |  | -| **Combos** |  | -| **Analytics** |  | -| **Kalusugan** |  | -| **Tagasalin** |  | -| **Mga Setting** |  | -| **Mga CLI Tools** |  | -| **Mga Log ng Paggamit** |  | -| **Endpoint** |  | +- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing
- Built with ❤️ para sa mga developer na nagko-code 24/7
+ Built with ❤️ for developers who code 24/7
omniroute.online
+
diff --git a/docs/i18n/phi/docs/FEATURES.md b/docs/i18n/phi/docs/FEATURES.md
new file mode 100644
index 0000000000..523d0f63fe
--- /dev/null
+++ b/docs/i18n/phi/docs/FEATURES.md
@@ -0,0 +1,145 @@
+# OmniRoute — Dashboard Features Gallery (Filipino)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/FEATURES.md) · 🇪🇸 [es](../../es/docs/FEATURES.md) · 🇫🇷 [fr](../../fr/docs/FEATURES.md) · 🇩🇪 [de](../../de/docs/FEATURES.md) · 🇮🇹 [it](../../it/docs/FEATURES.md) · 🇷🇺 [ru](../../ru/docs/FEATURES.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FEATURES.md) · 🇯🇵 [ja](../../ja/docs/FEATURES.md) · 🇰🇷 [ko](../../ko/docs/FEATURES.md) · 🇸🇦 [ar](../../ar/docs/FEATURES.md) · 🇮🇳 [in](../../in/docs/FEATURES.md) · 🇹🇭 [th](../../th/docs/FEATURES.md) · 🇻🇳 [vi](../../vi/docs/FEATURES.md) · 🇮🇩 [id](../../id/docs/FEATURES.md) · 🇲🇾 [ms](../../ms/docs/FEATURES.md) · 🇳🇱 [nl](../../nl/docs/FEATURES.md) · 🇵🇱 [pl](../../pl/docs/FEATURES.md) · 🇸🇪 [sv](../../sv/docs/FEATURES.md) · 🇳🇴 [no](../../no/docs/FEATURES.md) · 🇩🇰 [da](../../da/docs/FEATURES.md) · 🇫🇮 [fi](../../fi/docs/FEATURES.md) · 🇵🇹 [pt](../../pt/docs/FEATURES.md) · 🇷🇴 [ro](../../ro/docs/FEATURES.md) · 🇭🇺 [hu](../../hu/docs/FEATURES.md) · 🇧🇬 [bg](../../bg/docs/FEATURES.md) · 🇸🇰 [sk](../../sk/docs/FEATURES.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FEATURES.md) · 🇮🇱 [he](../../he/docs/FEATURES.md) · 🇵🇭 [phi](../../phi/docs/FEATURES.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FEATURES.md)
+
+---
+
+Visual guide to every section of the OmniRoute dashboard.
+
+---
+
+## 🔌 Providers
+
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
+
+
+
+---
+
+## 🎨 Combos
+
+Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
+
+
+
+---
+
+## 📊 Analytics
+
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
+
+
+
+---
+
+## 🏥 System Health
+
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+
+
+
+---
+
+## 🔧 Translator Playground
+
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
+
+
+
+---
+
+## 🎮 Model Playground _(v2.0.9+)_
+
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
+
+---
+
+## 🎨 Themes _(v2.0.5+)_
+
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
+
+## ⚙️ Settings
+
+Comprehensive settings panel with tabs:
+
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning
+- **Advanced** — Configuration overrides
+
+
+
+---
+
+## 🔧 CLI Tools
+
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
+
+
+
+---
+
+## 🤖 CLI Agents _(v2.0.11+)_
+
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
+
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
+
+---
+
+## 🖼️ Media _(v2.0.3+)_
+
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
+
+## 📝 Request Logs
+
+Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
+
+
+
+---
+
+## 🌐 API Endpoint
+
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
+
+
+
+---
+
+## 🔑 API Key Management
+
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
+
+---
+
+## 📋 Audit Log
+
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
+
+---
+
+## 🖥️ Desktop Application
+
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
+
+Key features:
+
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
+
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.
diff --git a/docs/i18n/pl/README.md b/docs/i18n/pl/README.md
index b648e72cca..cbf68b8431 100644
--- a/docs/i18n/pl/README.md
+++ b/docs/i18n/pl/README.md
@@ -1,24 +1,94 @@
-omniroute.online
-
-
- # 🚀 OmniRoute — darmowa bramka AI
+# 🚀 OmniRoute — The Free AI Gateway (Polski)
-### Nigdy nie przestawaj kodować. Inteligentne przekierowywanie do **BEZPŁATNYCH i tanich modeli AI** z automatycznym powrotem.
-
-_Twój uniwersalny serwer proxy API — jeden punkt końcowy, ponad 36 dostawców, zero przestojów._
-
-**Uzupełnienia czatu • Osadzania • Generowanie obrazu • Dźwięk • Zmiana rankingu • 100% TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Bezpłatny dostawca AI dla Twoich ulubionych agentów kodujących
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Połącz dowolne narzędzie IDE lub CLI oparte na sztucznej inteligencji poprzez OmniRoute — bezpłatną bramę API dla nieograniczonego kodowania._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+` tags no longer leak to clients in SSE streaming responses (#585) |
+| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with per-provider/account quota enforcement, idempotency, SHA-256 storage, and optional GitHub issue reporting |
+| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG → generic fallback chain |
+| 🔄 **Model Auto-Sync** | 24h scheduler and manual UI toggle to sync model lists for built-in and custom OpenAI-compatible providers |
+| 🌐 **OpenCode Zen/Go** | Two new providers from @kang-heewon via PR #530: free tier + subscription tier via `OpencodeExecutor` |
+| 🐛 **Gemini CLI OAuth** | Actionable error when `GEMINI_OAUTH_CLIENT_SECRET` is missing in Docker (was cryptic Google error) |
+| 🐛 **OpenCode config** | `saveOpenCodeConfig()` now correctly writes TOML to `XDG_CONFIG_HOME` |
+| 🐛 **Pinned model override** | `body.model` correctly set to `pinnedModel` on context-cache protection |
+| 🐛 **Codex/Claude loop** | `tool_result` blocks now converted to text to stop infinite loops |
+| 🐛 **Login redirect** | Login no longer freezes after skipping password setup |
+| 🐛 **Windows paths** | MSYS2/Git-Bash paths (`/c/...`) normalized to `C:\...` automatically |
+
+---
+
+## 🖼️ Main Dashboard
+
+
-📡 Wszyscy agenci łączą się przez ` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**Stop wasting money and hitting limits:**
-### 🆕 What's New in v3.0.0
+- Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**OmniRoute solves this:**
+
+- ✅ **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
+- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool
---
-[](https://www.npmjs.com/package/omniroute)
-[](https://hub.docker.com/r/diegosouzapw/omniroute)
-[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
-[](https://omniroute.online)
-[](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
+## 📧 Support
-[🌐 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)
+> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.
-🌐 **Available in:** 🇺🇸 [English](../../README.md) | 🇧🇷 [Português (Brasil)](../pt-BR/README.md) | 🇪🇸 [Español](../es/README.md) | 🇫🇷 [Français](../fr/README.md) | 🇮🇹 [Italiano](../it/README.md) | 🇷🇺 [Русский](../ru/README.md) | 🇨🇳 [中文 (简体)](../zh-CN/README.md) | 🇩🇪 [Deutsch](../de/README.md) | 🇮🇳 [हिन्दी](../in/README.md) | 🇹🇭 [ไทย](../th/README.md) | 🇺🇦 [Українська](../uk-UA/README.md) | 🇸🇦 [العربية](../ar/README.md) | 🇯🇵 [日本語](../ja/README.md) | 🇻🇳 [Tiếng Việt](../vi/README.md) | 🇧🇬 [Български](../bg/README.md) | 🇩🇰 [Dansk](../da/README.md) | 🇫🇮 [Suomi](../fi/README.md) | 🇮🇱 [עברית](../he/README.md) | 🇭🇺 [Magyar](../hu/README.md) | 🇮🇩 [Bahasa Indonesia](../id/README.md) | 🇰🇷 [한국어](../ko/README.md) | 🇲🇾 [Bahasa Melayu](../ms/README.md) | 🇳🇱 [Nederlands](../nl/README.md) | 🇳🇴 [Norsk](../no/README.md) | 🇵🇹 [Português (Portugal)](../pt/README.md) | 🇷🇴 [Română](../ro/README.md) | 🇵🇱 [Polski](../pl/README.md) | 🇸🇰 [Slovenčina](../sk/README.md) | 🇸🇪 [Svenska](../sv/README.md) | 🇵🇭 [Filipino](../phi/README.md)
-
-
-
----
-
-## 🖼️
-
-
-
- # 🚀 OmniRoute — darmowa bramka AI
+# 🚀 OmniRoute — The Free AI Gateway (Polski)
-### Nigdy nie przestawaj kodować. Inteligentne przekierowywanie do **BEZPŁATNYCH i tanich modeli AI** z automatycznym powrotem.
-
-_Twój uniwersalny serwer proxy API — jeden punkt końcowy, ponad 36 dostawców, zero przestojów._
-
-**Uzupełnienia czatu • Osadzania • Generowanie obrazu • Dźwięk • Zmiana rankingu • 100% TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Bezpłatny dostawca AI dla Twoich ulubionych agentów kodujących
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Połącz dowolne narzędzie IDE lub CLI oparte na sztucznej inteligencji poprzez OmniRoute — bezpłatną bramę API dla nieograniczonego kodowania._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+
+
+[](https://www.npmjs.com/package/omniroute)
+[](https://www.npmjs.com/package/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
+[](https://omniroute.online)
+[](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)
+
+
+
+🌐 **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)
+
+---
+
+## 🆕 What's New in v3.0.0
+
+> **Upgrading from v2.9.5?** — See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes.
+
+| Area | Change |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection remediation |
+| ✅ **Route Validation** | All 176 API routes now validated with Zod schemas + `validateBody()` — CI `check:route-validation:t06` passes |
+| 🐛 **omniModel Tag Leak** | Internal `
+
+
+
+---
+
+## 📸 Dashboard Preview
+
+
+
+
+
+---
+
+### 🤖 Free AI Provider for your favorite coding agents
+
+_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._
Click to see dashboard screenshots
+ +| Page | Screenshot | +| -------------- | ------------------------------------------------- | +| **Providers** |  | +| **Combos** |  | +| **Analytics** |  | +| **Health** |  | +| **Translator** |  | +| **Settings** |  | +| **CLI Tools** |  | +| **Usage Logs** |  | +| **Endpoints** |  | + +|
-
+
OpenClaw @@ -92,113 +162,52 @@ _Połącz dowolne narzędzie IDE lub CLI oparte na sztucznej inteligencji poprze |
http://localhost:20128/v1 lub http://cloud.omniroute.online/v1 — jedna konfiguracja, nieograniczona liczba modeli i limit
+📡 All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 — one config, unlimited models and quota
---
-### 🆕 What's New in v3.0.0
+## 🤔 Why OmniRoute?
-| Area | Change |
-| ------------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal ` Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `
-
-
-
----
-
-## 📸
-
-
-
-
-
----
-
-## 🤔 Dlaczego OmniRoute?
-
-**Przestań marnować pieniądze i przekraczać limity:**
-
-- ...
- -| # | # | -| ----- | ---------------------------------------- | -| **1** |  | -| **2** |  | -| **3** |  | -| **4** |  | -| **5** |  | -| **6** |  | -| **7** |  | -| **8** |  | -| **9** |  | - - Limit subskrypcji wygasa niewykorzystany co miesiąc
-- Limity szybkości zatrzymują Cię w połowie kodowania
-- Drogie interfejsy API (20-50 USD miesięcznie na dostawcę)
-- Ręczne przełączanie pomiędzy dostawcami
-
-**OmniRoute rozwiązuje ten problem:**
-
-- ✅ **Maksymalizuj liczbę subskrypcji** - Śledź limit, wykorzystaj każdy bit przed zresetowaniem
-- ✅ **Automatyczny powrót** - Subskrypcja → Klucz API → Tani → Bezpłatny, zero przestojów
-- ✅ **Wiele kont** - Praca okrężna pomiędzy kontami każdego dostawcy
-- ✅ **Uniwersalny** - Działa z Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw i dowolnym narzędziem CLI
-
----
-
-## 📧 Wsparcie
-
-> 💬 **Dołącz do naszej społeczności!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Uzyskaj pomoc, dziel się wskazówkami i bądź na bieżąco.
-
-- **Strona internetowa**: [omniroute.online](https://omniroute.online)
+- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Problemy**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Oryginalny projekt**: [9router by decolua](https://github.com/decolua/9router)
+- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 Jak to działa
+## 🔄 How It Works
```
┌─────────────┐
@@ -227,451 +236,453 @@ Result: Never stop coding, minimal cost
---
-## 🎯 Co rozwiązuje OmniRoute — 30 rzeczywistych problemów i przypadków użycia
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **Każdy programista korzystający z narzędzi AI codziennie spotyka się z tymi problemami.** OmniRoute został stworzony, aby rozwiązać je wszystkie — od przekroczeń kosztów po blokady regionalne, od zepsutych przepływów OAuth po operacje protokołów i obserwowalność przedsiębiorstwa.
+> **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.
-
💸 1. „Płacę za kosztowną subskrypcję, ale nadal przeszkadzają mi limity”
+💸 1. "I pay for an expensive subscription but still get interrupted by limits"
-Programiści płacą 20–200 USD miesięcznie za Claude Pro, Codex Pro lub GitHub Copilot. Nawet płacąc, limit ma pułap – 5 godzin użytkowania, limity tygodniowe lub limity stawek za minutę. W połowie sesji kodowania dostawca przestaje odpowiadać, a programista traci płynność i produktywność. +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. -**Jak rozwiązuje to OmniRoute:** +**How OmniRoute solves it:** -- **Inteligentny 4-poziomowy powrót** — Jeśli limit subskrypcji się wyczerpie, automatycznie przekierowuje do klucza API → Tani → Bezpłatny bez ręcznej interwencji -- **Śledzenie limitów w czasie rzeczywistym** — Pokazuje zużycie tokenów w czasie rzeczywistym z resetowanym odliczaniem (5 godzin, codziennie, co tydzień) -- **Obsługa wielu kont** — Wiele kont na dostawcę z funkcją automatycznego przełączania między kontami — gdy skończy się jedno, następuje przejście do następnego -- **Niestandardowe kombinacje** — Konfigurowalne łańcuchy rezerwowe z 6 strategiami równoważenia (pierwsze wypełnienie, działanie okrężne, P2C, losowe, najrzadziej używane, zoptymalizowane pod względem kosztów) -- **Przydziały biznesowe Kodeksu** — monitorowanie przydziałów przestrzeni roboczej firmy/zespołu bezpośrednio na pulpicie nawigacyjnym +- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention +- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly) +- **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 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
-` z modeli takich jak DeepSeek R1 do standardowego `reasoning_content`
-- **Wyjście strukturalne dla Gemini** — `json_schema` → `responseMimeType`/`responseSchema` automatyczna konwersja
-- **`stream` domyślnie to `false`** — Zgodność ze specyfikacją OpenAI, unikanie nieoczekiwanego SSE w pakietach SDK Python/Rust/Go
+- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 67+ 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
🔌 2. „Muszę korzystać z wielu dostawców, ale każdy ma inny interfejs API”
+🔌 2. "I need to use multiple providers but each has a different API"
-OpenAI używa jednego formatu, Claude (Anthropic) używa innego, Gemini jeszcze innego. Jeśli programista chce przetestować modele od różnych dostawców lub korzystać z nich w trybie awaryjnym, musi ponownie skonfigurować pakiety SDK, zmienić punkty końcowe i poradzić sobie z niekompatybilnymi formatami. Dostawcy niestandardowi (FriendLI, NIM) mają niestandardowe punkty końcowe modelu. +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. -**Jak rozwiązuje to OmniRoute:** +**How OmniRoute solves it:** -- **Ujednolicony punkt końcowy** — pojedynczy `http://localhost:20128/v1` służy jako serwer proxy dla wszystkich ponad 36 dostawców -- **Tłumaczenie formatu** — Automatyczne i przejrzyste: OpenAI ↔ Claude ↔ Gemini ↔ API odpowiedzi -- **Odkażanie odpowiedzi** — usuwa niestandardowe pola (`x_groq`, `usage_breakdown`, `service_tier`), które psują OpenAI SDK v1.83+ -- **Normalizacja ról** — Konwertuje `developer` → `system` dla dostawców innych niż OpenAI; `system` → `user` dla GLM/ERNIE -- **Pomyśl o ekstrakcji tagów** — wyodrębnia bloki `
-
🌐 3. „Mój dostawca AI blokuje mój region/kraj”
+🌐 3. "My AI provider blocks my region/country"
-Dostawcy tacy jak OpenAI/Codex blokują dostęp z określonych regionów geograficznych. Podczas połączeń OAuth i API użytkownicy otrzymują błędy takie jak `unsupported_country_region_territory`. Jest to szczególnie frustrujące dla programistów z krajów rozwijających się. +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. -**Jak rozwiązuje to OmniRoute:** +**How OmniRoute solves it:** -- **3-poziomowa konfiguracja serwera proxy** — Konfigurowalny serwer proxy na 3 poziomach: globalny (cały ruch), na dostawcę (tylko jeden dostawca) i na połączenie/klucz -- **Oznaczone kolorami identyfikatory proxy** — Wskaźniki wizualne: 🟢 globalny serwer proxy, 🟡 serwer proxy dostawcy, 🔵 serwer proxy połączenia, zawsze pokazujący adres IP -- **Wymiana tokenów OAuth przez serwer proxy** — Przepływ OAuth przechodzi również przez serwer proxy, co rozwiązuje problem `unsupported_country_region_territory` -- **Test połączenia przez serwer proxy** — Testy połączenia wykorzystują skonfigurowany serwer proxy (koniec z bezpośrednim obejściem) -- **Obsługa SOCKS5** — Pełna obsługa proxy SOCKS5 dla routingu wychodzącego -- **Podrabianie odcisków palców TLS** — Odcisk palca TLS podobny do przeglądarki za pośrednictwem `wreq-js` w celu ominięcia wykrywania botów +- **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
-` prefix
-- **Kombinacje dostępne wyłącznie bezpłatnie** — Łańcuch `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = 0 USD/miesiąc z zerowymi przestojami
-- **Darmowe kredyty NVIDIA NIM** — zintegrowane 1000 darmowych kredytów
-- **Strategia zoptymalizowana pod względem kosztów** — Strategia routingu, która automatycznie wybiera najtańszego dostępnego dostawcę
+- **Free-Only Combos** — Chain `gc/gemini-3-flash → 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
🆓 4. „Chcę używać AI do kodowania, ale nie mam pieniędzy”
+🆓 4. "I want to use AI for coding but I have no money"
-Nie każdy może zapłacić 20–200 USD miesięcznie za subskrypcje AI. Studenci, programiści z krajów wschodzących, hobbyści i freelancerzy potrzebują dostępu do wysokiej jakości modeli po zerowych kosztach. +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. -**Jak rozwiązuje to OmniRoute:** +**How OmniRoute solves it:** -- **Wbudowani dostawcy bezpłatnych poziomów** — Natywne wsparcie dla w 100% darmowych dostawców: iFlow (8 nielimitowanych modeli), Qwen (3 nieograniczone modele), Kiro (Claude za darmo), Gemini CLI (180 tys./miesiąc za darmo) +- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free) - **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/
-
🔒 5. „Muszę chronić moją bramę AI przed nieautoryzowanym dostępem”
+🔒 5. "I need to protect my AI gateway from unauthorized access"
-Podczas udostępniania bramy AI w sieci (LAN, VPS, Docker) każda osoba posiadająca adres może wykorzystać tokeny/przydział programisty. Bez ochrony interfejsy API są podatne na niewłaściwe użycie, natychmiastowe wstrzyknięcie i nadużycia. +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 rozwiązuje to OmniRoute:** +**How OmniRoute solves it:** -- **Zarządzanie kluczami API** — generowanie, rotacja i ustalanie zakresu dla każdego dostawcy za pomocą dedykowanej strony `/dashboard/api-manager` -- **Uprawnienia na poziomie modelu** — Ogranicz klucze API do określonych modeli (`openai/*`, wzorce symboli wieloznacznych), za pomocą przełącznika Zezwalaj na wszystko/Ogranicz -- **API Endpoint Protection** — Wymagaj klucza dla `/v1/models` i blokuj określonych dostawców na liście -- **Auth Guard + ochrona CSRF** — Wszystkie trasy panelu kontrolnego chronione oprogramowaniem pośredniczącym `withAuth` + tokenami CSRF -- **Rate Limiter** — Ograniczanie szybkości na IP z konfigurowalnymi oknami -- **Filtrowanie IP** — Lista dozwolonych/blokowanych do kontroli dostępu -- **Szybka ochrona przed wstrzyknięciem** — Oczyszczanie przed złośliwymi wzorcami podpowiedzi -- **Szyfrowanie AES-256-GCM** — Poświadczenia szyfrowane w stanie spoczynku +- **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. „Mój dostawca przestał działać i straciłem płynność kodowania”
+🛑 6. "My provider went down and I lost my coding flow"
-Dostawcy sztucznej inteligencji mogą stać się niestabilni, zwracać błędy 5xx lub przekraczać tymczasowe limity szybkości. Jeśli programista jest zależny od jednego dostawcy, jego praca jest przerywana. Bez wyłączników automatycznych wielokrotne próby mogą spowodować awarię aplikacji. +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. -**Jak rozwiązuje to OmniRoute:** +**How OmniRoute solves it:** -- **Wyłącznik automatyczny na dostawcę** — Automatyczne otwieranie/zamykanie z konfigurowalnymi progami i czasem schładzania (zamknięty/otwarty/półotwarty) -- **Wykładniczy wycofywanie** — Stopniowe opóźnienia ponownych prób -- **Anti-Thundering Herd** — Mutex + ochrona semaforów przed równoczesnymi burzami ponownych prób -- **Łańcuchy awaryjne typu Combo** — jeśli główny dostawca zawiedzie, automatycznie przejdzie przez łańcuch bez interwencji -- **Wyłącznik automatyczny** — automatycznie wyłącza niesprawnych dostawców w łańcuchu combo -- **Panel stanu** — Monitorowanie czasu pracy, stany wyłączników, blokady, statystyki pamięci podręcznej, opóźnienia p50/p95/p99 +- **Circuit Breaker per-model** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks +- **Exponential Backoff** — Progressive retry delays +- **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 +- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain +- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
-
🔧 7. „Konfigurowanie każdego narzędzia AI jest żmudne i powtarzalne”
+🔧 7. "Configuring each AI tool is tedious and repetitive"
-Programiści używają Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Każde narzędzie wymaga innej konfiguracji (punkt końcowy API, klucz, model). Ponowna konfiguracja w przypadku zmiany dostawcy lub modelu jest stratą czasu. +Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time. -**Jak rozwiązuje to OmniRoute:** +**How OmniRoute solves it:** -- ** Panel narzędzi CLI** — Dedykowana strona z konfiguracją jednym kliknięciem dla Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline -- **Generator konfiguracji GitHub Copilot** — Generuje `chatLanguageModels.json` dla kodu VS z zbiorczym wyborem modelu -- **Kreator wprowadzenia** — konfiguracja w 4 krokach dla początkujących użytkowników -- **Jeden punkt końcowy, wszystkie modele** — Skonfiguruj `http://localhost:20128/v1` raz, uzyskaj dostęp do ponad 36 dostawców +- **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 67+ providers
-
🔑 8. „Zarządzanie tokenami OAuth od wielu dostawców to piekło”
+🔑 8. "Managing OAuth tokens from multiple providers is hell"
-Claude Code, Codex, Gemini CLI, Copilot — wszystkie korzystają z OAuth 2.0 z wygasającymi tokenami. Programiści muszą stale przeprowadzać ponowne uwierzytelnianie, radzić sobie z `client_secret is missing`, `redirect_uri_mismatch` i awariami na zdalnych serwerach. Szczególnie problematyczny jest protokół OAuth w sieci LAN/VPS. +Claude Code, Codex, Gemini CLI, 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. -**Jak rozwiązuje to OmniRoute:** +**How OmniRoute solves it:** -- **Automatyczne odświeżanie tokenu** — tokeny OAuth odświeżają się w tle przed wygaśnięciem -- **Wbudowany OAuth 2.0 (PKCE)** — Automatyczny przepływ dla Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow -- **Wielokontowy OAuth** — wiele kont na dostawcę poprzez ekstrakcję tokenów JWT/ID -- **OAuth LAN/remote fix** — wykrywanie prywatnego adresu IP dla `redirect_uri` + ręczny tryb adresu URL dla serwerów zdalnych -- **OAuth Behind Nginx** — wykorzystuje `window.location.origin` w celu zapewnienia zgodności z odwrotnym proxy -- **Przewodnik po zdalnym OAuth** — szczegółowy przewodnik dotyczący danych uwierzytelniających Google Cloud na platformie VPS/Docker +- **Auto Token Refresh** — OAuth tokens refresh in background before expiration +- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow +- **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. „Nie wiem, ile i gdzie wydaję”
+📊 9. "I don't know how much I'm spending or where"
-Programiści korzystają z wielu płatnych dostawców, ale nie mają jednolitego widoku wydatków. Każdy dostawca ma własny pulpit rozliczeniowy, ale nie ma widoku skonsolidowanego. Nieoczekiwane koszty mogą się kumulować. +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. -**Jak rozwiązuje to OmniRoute:** +**How OmniRoute solves it:** -- **Panel analizy kosztów** — śledzenie kosztów według tokenu i zarządzanie budżetem dla każdego dostawcy -- **Limity budżetowe na poziom** — Pułap wydatków na poziom, który uruchamia automatyczne wycofanie -- **Konfiguracja cen dla poszczególnych modeli** — Ceny dla poszczególnych modeli można konfigurować -- **Statystyki użytkowania na klucz API** — Liczba żądań i znacznik czasu ostatniego użycia na klucz -- **Panel analityczny** — karty statystyk, wykres wykorzystania modelu, tabela dostawców ze wskaźnikami powodzenia i opóźnieniami +- **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. „Nie mogę diagnozować błędów i problemów w wywołaniach AI”
+🐛 10. "I can't diagnose errors and problems in AI calls"
-Gdy połączenie nie powiedzie się, programista nie wie, czy był to limit szybkości, wygasły token, nieprawidłowy format czy błąd dostawcy. Fragmentowane dzienniki na różnych terminalach. Bez obserwowalności debugowanie odbywa się metodą prób i błędów. +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. -**Jak rozwiązuje to OmniRoute:** +**How OmniRoute solves it:** -- **Ujednolicony pulpit nawigacyjny** — 4 karty: Dzienniki żądań, Dzienniki proxy, Dzienniki audytu, Konsola -- **Przeglądarka logów w konsoli** — Przeglądarka działająca w stylu terminala w czasie rzeczywistym z poziomami oznaczonymi kolorami, automatycznym przewijaniem, wyszukiwaniem i filtrowaniem -- **Dzienniki proxy SQLite** — trwałe dzienniki, które przetrwają ponowne uruchomienie serwera -- **Plac zabaw dla tłumaczy** — 4 tryby debugowania: Plac zabaw (tłumaczenie formatu), Tester czatu (w obie strony), Stanowisko testowe (wsadowe), Monitor na żywo (w czasie rzeczywistym) -- **Żądanie telemetrii** — opóźnienie p50/p95/p99 + śledzenie identyfikatora X-Request-Id -- **Logowanie oparte na plikach z rotacją** — Przechwytywacz konsoli przechwytuje wszystko do dziennika JSON z rotacją na podstawie rozmiaru +- **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 Proxy Logs** — Persistent logs that survive server restarts +- **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 Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation +- **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. „Wdrażanie i konserwacja bramy jest skomplikowane”
+🏗️ 11. "Deploying and maintaining the gateway is complex"
-Instalacja, konfiguracja i utrzymanie serwera proxy AI w różnych środowiskach (lokalnym, VPS, Docker, chmura) jest pracochłonne. Problemy takie jak zakodowane na stałe ścieżki, `EACCES` w katalogach, konflikty portów i kompilacje międzyplatformowe zwiększają tarcia. +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. -**Jak rozwiązuje to OmniRoute:** +**How OmniRoute solves it:** -- **npm globalna instalacja** — `npm install -g omniroute && omniroute` — gotowe -- **Docker Multi-platform** — natywny AMD64 + ARM64 (Apple Silicon, AWS Graviton, Raspberry Pi) -- **Profile Docker Compose** — `base` (bez narzędzi CLI) i `cli` (z Claude Code, Codex, OpenClaw) -- **Electron Desktop App** — Natywna aplikacja dla systemów Windows/macOS/Linux z zasobnikiem systemowym, automatycznym uruchamianiem i trybem offline -- **Tryb Split-Port** — API i pulpit nawigacyjny na oddzielnych portach dla zaawansowanych scenariuszy (odwrotne proxy, sieć kontenerowa) -- **Cloud Sync** — skonfiguruj synchronizację między urządzeniami za pośrednictwem Cloudflare Workers -- **Kopie zapasowe DB** — Automatyczne tworzenie kopii zapasowych, przywracanie, eksportowanie i importowanie wszystkich ustawień +- **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
-
🌍 12. „Interfejs jest wyłącznie w języku angielskim, a mój zespół nie mówi po angielsku”
+🌍 12. "The interface is English-only and my team doesn't speak English"
-Zespoły w krajach nieanglojęzycznych, szczególnie w Ameryce Łacińskiej, Azji i Europie, mają trudności z interfejsami dostępnymi wyłącznie w języku angielskim. Bariery językowe ograniczają wdrażanie i zwiększają liczbę błędów konfiguracyjnych. +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. -**Jak rozwiązuje to OmniRoute:** +**How OmniRoute solves it:** -- ** Panel i18n — 30 języków** — Przetłumaczono ponad 500 klawiszy, w tym arabski, bułgarski, duński, niemiecki, hiszpański, fiński, francuski, hebrajski, hindi, węgierski, indonezyjski, włoski, japoński, koreański, malajski, holenderski, norweski, polski, portugalski (PT/BR), rumuński, rosyjski, słowacki, szwedzki, tajski, ukraiński, wietnamski, chiński, filipiński, angielski -- **Obsługa RTL** — obsługa tekstu od prawej do lewej w języku arabskim i hebrajskim -- **Wielojęzyczne pliki README** — 30 kompletnych tłumaczeń dokumentacji -- **Wybór języka** — Ikona kuli ziemskiej w nagłówku umożliwiająca przełączanie w czasie rzeczywistym +- **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. „Potrzebuję czegoś więcej niż czatu — potrzebuję osadzania, obrazów i dźwięku”
+🔄 13. "I need more than chat — I need embeddings, images, audio"
-Sztuczna inteligencja to nie tylko ukończenie czatu. Twórcy muszą generować obrazy, transkrybować dźwięk, tworzyć osadzania dla RAG, zmieniać rangę dokumentów i moderować treści. Każdy interfejs API ma inny punkt końcowy i format. +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. -**Jak rozwiązuje to OmniRoute:** +**How OmniRoute solves it:** -- **Osadzania** — `/v1/embeddings` z 6 dostawcami i ponad 9 modelami -- **Generowanie obrazu** — `/v1/images/generations` z 10 dostawcami i ponad 20 modelami (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI) -- **Tekst na wideo** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) i SD WebUI -- **Tekst na muzykę** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen) -- **Transkrypcja audio** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3 -- **Zamiana tekstu na mowę** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, Inworld, Cartesia, PlayHT, + obecni dostawcy -- **Moderacje** — `/v1/moderations` — Sprawdzanie bezpieczeństwa treści -- **Reranking** — `/v1/rerank` — Zmiana rankingu trafności dokumentu -- **Responses API** — Pełna obsługa `/v1/responses` dla Codexu +- **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. „Nie mam możliwości przetestowania i porównania jakości pomiędzy modelami”
+🧪 14. "I have no way to test and compare quality across models"
-Programiści chcą wiedzieć, który model jest najlepszy dla ich przypadku użycia — kodu, tłumaczenia, rozumowania — ale ręczne porównywanie jest powolne. Nie istnieją żadne zintegrowane narzędzia eval. +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. -**Jak rozwiązuje to OmniRoute:** +**How OmniRoute solves it:** -- **Oceny LLM** — Testowanie złotego zestawu z 10 fabrycznie załadowanymi skrzynkami obejmującymi pozdrowienia, matematykę, geografię, generowanie kodu, zgodność z JSON, tłumaczenie, przeceny, odmowy ze względów bezpieczeństwa -- **4 strategie dopasowania** — `exact`, `contains`, `regex`, `custom` (funkcja JS) -- **Stolik testowy dla tłumaczy** — Testowanie wsadowe z wieloma danymi wejściowymi i oczekiwanymi wynikami, porównanie różnych dostawców -- **Tester czatu** — Pełna podróż w obie strony z renderowaniem odpowiedzi wizualnych -- **Live Monitor** — Strumień w czasie rzeczywistym wszystkich żądań przepływających przez serwer proxy +- **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. „Muszę skalować bez utraty wydajności”
+📈 15. "I need to scale without losing performance"
-W miarę wzrostu liczby żądań bez buforowania tych samych pytań generowane są podwójne koszty. Bez idempotencji zduplikowane żądania przetwarzania odpadów. Należy przestrzegać limitów stawek dla poszczególnych dostawców. +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. -**Jak rozwiązuje to OmniRoute:** +**How OmniRoute solves it:** -- **Semantyczna pamięć podręczna** — Dwuwarstwowa pamięć podręczna (podpis + semantyka) zmniejsza koszty i opóźnienia -- **Request Idempotency** — okno deduplikacji 5 s dla identycznych żądań -- **Wykrywanie limitów szybkości** — RPM na dostawcę, minimalna przerwa i maksymalne jednoczesne śledzenie -- **Edytowalne limity szybkości** — Konfigurowalne ustawienia domyślne w Ustawieniach → Odporność z trwałością -- **API Key Validation Cache** — 3-warstwowa pamięć podręczna zapewniająca wydajność produkcyjną -- **Panel kontrolny stanu z telemetrią** — opóźnienia p50/p95/p99, statystyki pamięci podręcznej, czas pracy +- **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 +- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence +- **API Key Validation Cache** — 3-tier cache for production performance +- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
-
🤖 16. „Chcę kontrolować zachowanie modelu globalnie”
+🤖 16. "I want to control model behavior globally"
-Deweloperzy, którzy chcą wszystkich odpowiedzi w określonym języku, w określonym tonie lub chcą ograniczyć tokeny rozumowania. Konfigurowanie tego w każdym narzędziu/żądaniu jest niepraktyczne. +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. -**Jak rozwiązuje to OmniRoute:** +**How OmniRoute solves it:** -- **Wstrzykiwanie monitu systemowego** — monit globalny stosowany do wszystkich żądań -- **Przemyślana walidacja budżetu** — Kontrola alokacji tokenów rozumowania na każde żądanie (przejściowe, automatyczne, niestandardowe, adaptacyjne) -- **6 Strategii routingu** — Globalne strategie określające sposób dystrybucji żądań -- **Wildcard Router** — wzorce `provider/*` są przesyłane dynamicznie do dowolnego dostawcy -- **Przełączanie kombinacji włącz/wyłącz** — przełączaj kombinacje bezpośrednio z pulpitu nawigacyjnego -- **Przełączanie dostawcy** — Włącz/wyłącz wszystkie połączenia dla dostawcy jednym kliknięciem -- **Zablokowani dostawcy** — Wyklucz określonych dostawców z listy `/v1/models` +- **System Prompt Injection** — Global prompt applied to all requests +- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive) +- **6 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 +- **Provider Toggle** — Enable/disable all connections for a provider with one click +- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
-
🧰 17. „Potrzebuję narzędzi MCP jako produktów najwyższej klasy”
+🧰 17. "I need MCP tools as first-class product capabilities"
-Wiele bram AI ujawnia MCP jedynie jako ukryty szczegół implementacji. Zespoły potrzebują widocznej, zarządzalnej warstwy operacyjnej. +Many AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer. -**Jak rozwiązuje to OmniRoute:** +**How OmniRoute solves it:** -- MCP pojawia się w panelu nawigacji na desce rozdzielczej i w zakładce protokołu punktu końcowego -- Dedykowana strona zarządzania MCP z procesem, narzędziami, zakresami i audytem -- Wbudowany szybki start dla `omniroute --mcp` i dołączania klientów +- 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. „Potrzebuję orkiestracji A2A ze ścieżkami zadań synchronizacji i strumieniowania”
+🧠 18. "I need A2A orchestration with sync + stream task paths"
-Przepływy pracy agentów wymagają zarówno bezpośrednich odpowiedzi, jak i długotrwałego wykonywania strumieniowego z kontrolą cyklu życia. +Agent workflows need both direct replies and long-running streamed execution with lifecycle control. -**Jak rozwiązuje to OmniRoute:** +**How OmniRoute solves it:** -- Punkt końcowy A2A JSON-RPC (`POST /a2a`) z `message/send` i `message/stream` -- Przesyłanie strumieniowe SSE z propagacją stanu terminala - — Interfejsy API cyklu życia zadań dla `tasks/get` i `tasks/cancel` +- 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. „Potrzebuję prawdziwego stanu procesu MCP, a nie zgadniętego statusu”
+🛰️ 19. "I need real MCP process health, not guessed status"
-Zespoły operacyjne muszą wiedzieć, czy MCP rzeczywiście żyje, a nie tylko, czy można uzyskać dostęp do interfejsu API. +Operational teams need to know if MCP is actually alive, not just whether an API is reachable. -**Jak rozwiązuje to OmniRoute:** +**How OmniRoute solves it:** -- Plik pulsu środowiska wykonawczego z PID, znacznikami czasu, transportem, liczbą narzędzi i trybem zakresu -- API statusu MCP łączące puls + ostatnią aktywność -- Karty stanu interfejsu użytkownika dotyczące świeżości procesów/czasu pracy/bicia serca +- 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. „Potrzebuję wykonania narzędzia MCP z możliwością audytu”
+📋 20. "I need auditable MCP tool execution"
-Gdy narzędzia modyfikują konfigurację lub uruchamiają działania operacyjne, zespoły potrzebują identyfikowalności kryminalistycznej. +When tools mutate config or trigger ops actions, teams need forensic traceability. -**Jak rozwiązuje to OmniRoute:** +**How OmniRoute solves it:** -- Wspierane przez SQLite rejestrowanie audytu dla wywołań narzędzi MCP -- Filtruje według narzędzia, sukcesu/porażki, klucza API i paginacji -- Tabela audytu pulpitu nawigacyjnego + punkty końcowe statystyk dla automatyzacji +- 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. „Potrzebuję uprawnień MCP o określonym zakresie na integrację”
+🔐 21. "I need scoped MCP permissions per integration"
-Różni klienci powinni mieć najniższy dostęp do kategorii narzędzi. +Different clients should have least-privilege access to tool categories. -**Jak rozwiązuje to OmniRoute:** +**How OmniRoute solves it:** -- 9 szczegółowych zakresów MCP zapewniających kontrolowany dostęp do narzędzi -- Egzekwowanie zakresu i widoczność w interfejsie zarządzania MCP -- Bezpieczna domyślna pozycja dla narzędzi operacyjnych +- 9 granular MCP scopes for controlled tool access +- Scope enforcement and visibility in MCP management UI +- Safe default posture for operational tooling
-
⚙️ 22. „Potrzebuję kontroli operacyjnej bez ponownego wdrażania”
+⚙️ 22. "I need operational controls without redeploying"
-Zespoły potrzebują szybkich zmian w czasie działania podczas incydentów lub zdarzeń kosztowych. +Teams need quick runtime changes during incidents or cost events. -**Jak rozwiązuje to OmniRoute:** +**How OmniRoute solves it:** -- Aktywacja kombinacji przełączników bezpośrednio z pulpitu nawigacyjnego MCP -- Zastosuj profile odporności ze wstępnie zdefiniowanych pakietów zasad -- Zresetuj stan wyłącznika automatycznego z tego samego panelu operacyjnego +- Switch combo activation directly from MCP dashboard +- Apply resilience profiles from pre-defined policy packs +- Reset circuit breaker state from the same operations panel
-
🔄 23. „Potrzebuję widoczności i anulowania cyklu życia zadania A2A na żywo”
+🔄 23. "I need live A2A task lifecycle visibility and cancellation"
-Bez widoczności cyklu życia zdarzenia związane z zadaniami stają się trudne do segregacji. +Without lifecycle visibility, task incidents become hard to triage. -**Jak rozwiązuje to OmniRoute:** +**How OmniRoute solves it:** -- Lista zadań/filtrowanie według stanu/umiejętności z paginacją -- Szczegółowa analiza metadanych zadań, zdarzeń i artefaktów -- Punkt końcowy anulowania zadania i akcja interfejsu użytkownika z potwierdzeniem +- 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. „Potrzebuję metryk aktywnego strumienia dla obciążenia A2A”
+🌊 24. "I need active stream metrics for A2A load"
-Przepływy pracy związane z przesyłaniem strumieniowym wymagają operacyjnego wglądu w współbieżność i połączenia na żywo. +Streaming workflows require operational insight into concurrency and live connections. -**Jak rozwiązuje to OmniRoute:** +**How OmniRoute solves it:** -- Aktywne liczniki strumieni zintegrowane ze statusem A2A -- Znacznik czasu ostatniego zadania i liczba stanów -- Karty pulpitu A2A do monitorowania operacji w czasie rzeczywistym +- Active stream counters integrated into A2A status +- Last task timestamp and per-state counts +- A2A dashboard cards for real-time ops monitoring
-
🪪 25. „Potrzebuję standardowego wyszukiwania agentów dla klientów”
+🪪 25. "I need standard agent discovery for clients"
-Zewnętrzni klienci i koordynatorzy potrzebują metadanych do odczytu maszynowego na potrzeby wdrożenia. +External clients and orchestrators need machine-readable metadata for onboarding. -**Jak rozwiązuje to OmniRoute:** +**How OmniRoute solves it:** -- Karta agenta ujawniona pod adresem `/.well-known/agent.json` -- Możliwości i umiejętności pokazane w interfejsie zarządzania -- Interfejs API stanu A2A zawiera metadane wykrywania do automatyzacji +- Agent Card exposed at `/.well-known/agent.json` +- Capabilities and skills shown in management UI +- A2A status API includes discovery metadata for automation
-
🧭 26. „Potrzebuję możliwości wykrycia protokołu w UX produktu”
+🧭 26. "I need protocol discoverability in the product UX"
-Jeśli użytkownicy nie mogą odkryć powierzchni protokołu, spada jakość przyjęcia i wsparcia. +If users cannot discover protocol surfaces, adoption and support quality drop. -**Jak rozwiązuje to OmniRoute:** +**How OmniRoute solves it:** -- Wpisy na pasku bocznym dla MCP i A2A -- Strona punktu końcowego, zakładka Protokoły z szybkim startem i statusem -- Linki z przeglądu do dedykowanych pulpitów zarządzania +- 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. „Potrzebuję kompleksowej weryfikacji protokołu z prawdziwymi klientami”
+🧪 27. "I need end-to-end protocol validation with real clients"
-Testy próbne nie wystarczą do sprawdzenia zgodności protokołu przed wydaniem. +Mock tests are not enough to validate protocol compatibility before release. -**Jak rozwiązuje to OmniRoute:** +**How OmniRoute solves it:** -- Pakiet E2E, który uruchamia aplikację i wykorzystuje prawdziwy transport klienta MCP SDK -- Testy klienta A2A pod kątem wykrywania, wysyłania, przesyłania strumieniowego, pobierania i anulowania przepływów -- Sprawdzaj twierdzenia względem interfejsów API audytu MCP i zadań A2A +- 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. „Potrzebuję ujednoliconej obserwowalności na wszystkich interfejsach”
+📡 28. "I need unified observability across all interfaces"
-Podział obserwowalności według protokołu tworzy martwe punkty i wydłuża MTTR. +Splitting observability by protocol creates blind spots and longer MTTR. -**Jak rozwiązuje to OmniRoute:** +**How OmniRoute solves it:** -- Ujednolicone dashboardy/dzienniki/analizy w jednym produkcie -- Stan + audyt + telemetria żądań w warstwach OpenAI, MCP i A2A -- Operacyjne interfejsy API dla statusu i automatyzacji +- Unified dashboards/logs/analytics in one product +- Health + audit + request telemetry across OpenAI, MCP, and A2A layers +- Operational APIs for status and automation
-
💼 29. „Potrzebuję jednego środowiska wykonawczego dla serwera proxy + narzędzi + orkiestracji agenta”
+💼 29. "I need one runtime for proxy + tools + agent orchestration"
-Uruchamianie wielu oddzielnych usług zwiększa koszty operacyjne i tryby awarii. +Running many separate services increases operational cost and failure modes. -**Jak rozwiązuje to OmniRoute:** +**How OmniRoute solves it:** -- Serwer proxy zgodny z OpenAI, serwer MCP i serwer A2A w jednym stosie -- Wspólne uwierzytelnianie, odporność, magazyn danych i obserwowalność -- Spójny model polityki na wszystkich płaszczyznach interakcji +- 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
-
-### Przykładowe podręczniki (zintegrowane przypadki użycia)
+### Example Playbooks (Integrated Use Cases)
-**Poradnik A: maksymalizuj płatną subskrypcję + tanią kopię zapasową**
+**Playbook A: Maximize paid subscription + cheap backup**
```txt
Combo: "maximize-claude"
@@ -683,7 +694,7 @@ Monthly cost: $20 + small backup spend
Outcome: higher quality, near-zero interruption
```
-**Poradnik B: stos kodowania o zerowym koszcie**
+**Playbook B: Zero-cost coding stack**
```txt
Combo: "free-forever"
@@ -695,7 +706,7 @@ Monthly cost: $0
Outcome: stable free coding workflow
```
-**Poradnik C: łańcuch awaryjny działający 24 godziny na dobę, 7 dni w tygodniu**
+**Playbook C: 24/7 always-on fallback chain**
```txt
Combo: "always-on"
@@ -708,65 +719,132 @@ Combo: "always-on"
Outcome: deep fallback depth for deadline-critical workloads
```
-**Poradnik D: Operacje agenta z MCP + A2A**
+**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/mcp and /dashboard/a2a
-4) Control incidents with resilience profile + task cancellation
+3) Observe via /dashboard/endpoint (MCP and A2A tabs)
+4) Toggle services via inline status controls
```
---
-## ⚡ Szybki start
+## 🆓 Start Free — Zero Configuration Cost
-**1. Zainstaluj globalnie:**
+> 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 **iFlow** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |
+| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |
+| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |
+| 5 | `/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
```bash
npm install -g omniroute
omniroute
```
-🎉 Panel otwiera się o `http://localhost:20128`
+> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:
+>
+> ```bash
+> pnpm install -g omniroute
+> pnpm approve-builds -g # Select all packages → approve
+> omniroute
+> ```
-| Polecenie | Opis |
-| ----------------------- | --------------------------------------- |
-| `omniroute` | Uruchom serwer (domyślny port 20128) |
-| `omniroute --port 3000` | Użyj niestandardowego portu |
-| `omniroute --no-open` | Nie otwieraj automatycznie przeglądarki |
-| `omniroute --help` | Pokaż pomoc |
+Dashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.
-**2. Połącz się z DARMOWYM dostawcą:**
+| 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 |
-Panel kontrolny → Dostawcy → Połącz **Kod Claude** lub **Antygrawitacja** → Logowanie OAuth → Gotowe!
+Optional split-port mode:
-**3. Użyj w swoim narzędziu CLI:**
-
-```
-Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Settings:
- Endpoint: http://localhost:20128/v1
- API Key: [copy from dashboard]
- Model: if/kimi-k2-thinking
+```bash
+PORT=20128 DASHBOARD_PORT=20129 omniroute
+# API: http://localhost:20128/v1
+# Dashboard: http://localhost:20129
```
-**To wszystko!** Zacznij kodować za pomocą DARMOWYCH modeli AI.
+### 2) Connect providers and create your API key
-**Alternatywa — uruchamiana ze źródła:**
+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
+
+```txt
+Base URL: http://localhost:20128/v1
+API Key: [copy from Endpoint page]
+Model: if/kimi-k2-thinking (or any provider/model prefix)
+```
+
+Works with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.
+
+### 4) Enable and validate protocols (v2.0)
+
+**MCP (for tool-driven operations):**
+
+```bash
+omniroute --mcp
+```
+
+Then connect your MCP client over `stdio` and test tools like:
+
+- `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 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
+PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev
```
---
-## 🐳 Doker
+## 🐳 Docker
-OmniRoute jest dostępny jako publiczny obraz Dockera na [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
+OmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
-**Szybki bieg:**
+**Quick run:**
```bash
docker run -d \
@@ -777,7 +855,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Z plikiem środowiska:**
+**With environment file:**
```bash
# Copy and edit .env first
@@ -792,7 +870,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Korzystanie z funkcji Docker Compose:**
+**Using Docker Compose:**
```bash
# Base profile (no CLI tools)
@@ -802,257 +880,552 @@ docker compose --profile base up -d
docker compose --profile cli up -d
```
-| Obraz | Oznacz | Rozmiar | Opis |
-| ------------------------ | -------- | ------- | ------------------------- |
-| `diegosouzapw/omniroute` | `latest` | ~250 MB | Najnowsza stabilna wersja |
-| `diegosouzapw/omniroute` | `1.0.3` | ~250 MB | Aktualna wersja |
+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.
+- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.
+- 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` | `1.0.3` | ~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
-npm run electron:dev # Development mode
+# 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)
+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)
---
-## 💰 Ceny w skrócie
+## 💰 Pricing at a Glance
-| Poziom | Dostawca | Koszt | Reset przydziału | Najlepsze dla |
-| ------------------ | ------------------- | ----------------------------- | ----------------------------- | -------------------------------- |
-| **💳 SUBSKRYPCJA** | Claude Code (Pro) | 20 USD/mies. | 5h + tygodniowo | Już subskrybujesz |
-| | Kodeks (Plus/Pro) | 20-200 $/mies. | 5h + tygodniowo | Użytkownicy OpenAI |
-| | Bliźnięta CLI | **BEZPŁATNE** | 180 tys./mies. + 1 tys./dzień | Wszyscy! |
-| | Drugi pilot GitHuba | 10–19 USD/mies. | Miesięczne | Użytkownicy GitHuba |
-| **🔑 KLUCZ API** | NVIDIA NIM | **BEZPŁATNE** (1000 kredytów) | Jednorazowe | Bezpłatne testowanie poziomów |
-| | DeepSeek | Płatność za użycie | Brak | Najlepsza cena/jakość |
-| | Groq | Poziom bezpłatny + płatny | Stawka ograniczona | Ultraszybkie wnioskowanie |
-| | xAI (Grok) | Płatność za użycie | Brak | Modele Groka |
-| | Mistral | Poziom bezpłatny + płatny | Stawka ograniczona | Europejska sztuczna inteligencja |
-| | OtwórzRouter | Płatność za użycie | Brak | Ponad 100 modeli |
-| **💰 TANIO** | GLM-4.7 | 0,6 USD/1 mln | Codziennie 10:00 | Kopia zapasowa budżetu |
-| | MiniMax M2.1 | 0,2 USD/1 mln | 5-godzinne toczenie | Najtańsza opcja |
-| | Kimi K2 | 9 USD miesięcznie | 10 mln tokenów/mies. | Przewidywalny koszt |
-| **🆓 DARMOWE** | iFlow | 0 dolarów | Nieograniczony | 8 modeli za darmo |
-| | Qwen | 0 dolarów | Nieograniczony | 3 modele za darmo |
-| | Kiro | 0 dolarów | Nieograniczony | Claude wolny |
+| 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 |
+| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |
+| | 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** | iFlow | **$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 |
-**💡 Wskazówka dla profesjonalistów:** Zacznij od zestawu Gemini CLI (180 tys. za darmo/miesiąc) + iFlow (bez ograniczeń za darmo) = koszt 0 USD!
+> 🆕 **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
+iFlow (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.
---
-## 💡 Kluczowe funkcje
+---
-### 🧠 Routing i inteligencja rdzenia
+## 🆓 Free Models — What You Actually Get
-| Funkcja | Co to robi |
-| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| 🎯 **Inteligentny 4-poziomowy powrót** | Auto-trasa: Subskrypcja → Klucz API → Tanie → Bezpłatne |
-| 📊 **Śledzenie limitów w czasie rzeczywistym** | Liczba tokenów na żywo + odliczanie resetowania dla każdego dostawcy |
-| 🔄 **Tłumaczenie formatu** | OpenAI ↔ Claude ↔ Bliźnięta ↔ Kursor ↔ Kiro bezproblemowo + oczyszczanie odpowiedzi |
-| 👥 **Obsługa wielu kont** | Wiele kont na dostawcę z inteligentnym wyborem |
-| 🔄 **Automatyczne odświeżanie tokena** | Tokeny OAuth odświeżają się automatycznie przy ponownej próbie |
-| 🎨 **Niestandardowe kombinacje** | 6 strategii: najpierw wypełnij, okrężnie, p2c, losowa, najrzadziej używana, zoptymalizowana pod względem kosztów |
-| 🧩 **Modele niestandardowe** | Dodaj dowolny identyfikator modelu do dowolnego dostawcy |
-| 🌐 **Router z dziką kartą** | Dynamicznie kieruj `provider/*` wzorce do dowolnego dostawcy |
-| 🧠 **Myślący budżet** | Tryby przekazywania, automatyczne, niestandardowe i adaptacyjne dla modeli wnioskowania |
-| 🔀 **Model Aliases** | Auto-forward deprecated model IDs to current replacements (built-in + custom) |
-| ⚡ **Background Degradation** | Auto-route background tasks (titles, summaries) to cheaper models |
-| 💬 **Wstrzyknięcie monitu systemowego** | Globalny monit systemowy stosowany do wszystkich żądań |
-| 📄 **API odpowiedzi** | Pełna obsługa OpenAI Responses API (`/v1/responses`) dla Codexu |
+> 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.
-### 🎵 Wielomodalne interfejsy API
+### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)
-| Funkcja | Co to robi |
-| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 🖼️ **Generowanie obrazu** | `/v1/images/generations` — 4 dostawców, ponad 9 modeli |
-| 📐 **Osadzenia** | `/v1/embeddings` — 6 dostawców, ponad 9 modeli |
-| 🎤 **Transkrypcja audio** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |
-| 🔊 **Zamiana tekstu na mowę** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) |
-| 🛡️ **Moderacje** | `/v1/moderations` — Kontrola bezpieczeństwa treści |
-| 🔀 **Ponowna pozycja** | `/v1/rerank` — Zmiana rankingu trafności dokumentu |
+| 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 |
-### 🛡️ Odporność i bezpieczeństwo
+### 🟢 IFLOW MODELS (Free OAuth — No Credit Card)
-| Funkcja | Co to robi |
-| --------------------------------------------- | ------------------------------------------------------------------------------------------- |
-| 🔌 **Wyłącznik** | Automatyczne otwieranie/zamykanie dla każdego dostawcy z konfigurowalnymi progami |
-| 🛡️ **Stado Przeciw Gromom** | Mutex + limit szybkości semaforów dla dostawców kluczy API |
-| 🧠 **Pamięć podręczna semantyczna** | Dwuwarstwowa pamięć podręczna (podpis + semantyka) zmniejsza koszty i opóźnienia |
-| ⚡ **Poproś o idempotencję** | Okno deduplikacji 5s dla zduplikowanych żądań |
-| 🔒 **Podrabianie odcisków palców TLS** | Pomiń wykrywanie botów opartych na TLS poprzez wreq-js |
-| 🌐 **Filtrowanie IP** | Lista dozwolonych/blokowanych dla kontroli dostępu API |
-| 📊 **Edytowalne limity stawek** | Konfigurowalne obroty, minimalna przerwa i maksymalna równowaga na poziomie systemu |
-| 💾 **Rate Limit Persistence** | Learned limits survive restarts via SQLite with 60s debounce + 24h staleness |
-| 🔄 **Token Refresh Resilience** | Per-provider circuit breaker (5 fails→30min) + 30s timeout per attempt |
-| 🛡 **Ochrona punktu końcowego API** | Bramkowanie uwierzytelniania + blokowanie dostawcy dla punktu końcowego `/models` |
-| 🔒 **Widoczność proxy** | Oznaczone kolorami plakietki: 🟢 globalny, 🟡 dostawca, 🔵 na połączenie z wyświetlaczem IP |
-| 🌐 **3-poziomowa konfiguracja serwera proxy** | Skonfiguruj serwery proxy na poziomie globalnym, dla dostawcy lub dla połączenia |
+| 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 |
-### 📊 Obserwacja i analityka
+### 🟡 QWEN MODELS (Device Code Auth)
-| Funkcja | Co to robi |
-| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| 📝 **Poproś o zalogowanie** | Tryb debugowania z pełnymi dziennikami żądań/odpowiedzi |
-| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |
-| 💾 **Dzienniki proxy SQLite** | Trwałe dzienniki proxy przetrwają ponowne uruchomienie serwera |
-| 📊 **Panel analityczny** | Oparte na Recharts: karty statystyk, wykres wykorzystania modelu, tabela dostawców |
-| 📈 **Śledzenie postępów** | Zapisz się na wydarzenia postępu SSE dla transmisji strumieniowej |
-| 🧪 **Oceny LLM** | Testowanie złotego seta z 4 strategiami meczowymi |
-| 🔍 **Poproś o telemetrię** | Agregacja opóźnień p50/p95/p99 + śledzenie X-Request-Id |
-| 📋 **Panel logów** | Ujednolicona strona z czterema zakładkami: Dzienniki żądań, Dzienniki proxy, Dzienniki audytu, Konsola |
-| 🖥️ **Przeglądarka logów konsoli** | Przeglądarka przypominająca terminal w czasie rzeczywistym z filtrem poziomów, wyszukiwaniem i automatycznym przewijaniem |
-| 📑 **Rejestrowanie oparte na plikach** | Przechwytywacz konsoli przechwytuje wszystkie dane wyjściowe do pliku dziennika JSON z rotacją |
-| 🏥 **Panel zdrowia** | Czas pracy systemu, stany wyłączników, blokady, statystyki pamięci podręcznej |
-| 💰 **Śledzenie kosztów** | Zarządzanie budżetem + konfiguracja cen dla poszczególnych modeli |
+| 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) |
-### ☁️ Wdrożenie i synchronizacja
+### 🟣 GEMINI CLI (Google OAuth)
-| Funkcja | Co to robi |
-| ------------------------------------ | ------------------------------------------------------------------------------------------------------- |
-| 💾 **Synchronizacja z chmurą** | Synchronizuj konfigurację między urządzeniami za pośrednictwem Cloudflare Workers |
-| 🌐 **Wdrażaj gdziekolwiek** | Localhost, VPS, Docker, Pracownicy Cloudflare |
-| 🔑 **Zarządzanie kluczami API** | Generuj, obracaj i ustalaj zakres kluczy API dla każdego dostawcy |
-| 🧙 **Kreator wdrażania** | Konfiguracja z przewodnikiem w 4 krokach dla początkujących użytkowników |
-| 🔧 **Panel narzędzi CLI** | Jednym kliknięciem skonfiguruj Claude, Codex, Cline, OpenClaw, Kilo, Antigravity |
-| 🔄 **Kopie zapasowe DB** | Automatyczne tworzenie kopii zapasowych, przywracanie, eksportowanie i importowanie wszystkich ustawień |
-| 🌐 **Internacjonalizacja** | Pełny i18n z next-intl — obsługa języka angielskiego i portugalskiego (Brazylia) |
-| 🌍 **Wybór języka** | Ikona kuli ziemskiej w nagłówku umożliwiająca zmianę języka w czasie rzeczywistym (🇺🇸/🇧🇷) |
-| 🧹 **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 |
-| 📂 **Niestandardowy katalog danych** | `DATA_DIR` env var, aby zastąpić domyślną ścieżkę przechowywania `~/.omniroute` |
+| Model | Prefix | Limit | Rate Limit |
+| ------------------------ | ------ | --------------------------- | ------------- |
+| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |
+| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |
+
+### ⚫ 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
+> iFlow (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 v2.0 is built as an operational platform, not just a relay proxy.
+
+### 🆕 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 Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |
+| 🤖 **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 (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) |
+| 🤝 **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** | 9 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 combo, apply resilience profiles, reset breakers from one control surface |
+
+### 🧠 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** | 6 balancing strategies + fallback chain control |
+| 🌐 **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) |
+| 💬 **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 |
+| ----------------------------------- | -------------------------------------------------------------------------------------- |
+| 🔌 **Circuit Breakers** | Per-model trip/recover with threshold controls |
+| 🎯 **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 |
+| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |
+| 🔑 **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 |
+
+### 📊 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 |
+| 📋 **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 |
+
+### ☁️ Deployment & Platform
+
+| Feature | What It Does |
+| ----------------------------- | --------------------------------------------------------- |
+| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |
+| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |
+| 💾 **Cloud Sync** | Configuration sync via cloud worker |
+| 🔄 **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 |
+
+### Feature Deep Dive
+
+#### Smart fallback with practical cost control
+
+```txt
+Combo: "my-coding-stack"
+ 1. cc/claude-opus-4-6
+ 2. nvidia/llama-3.3-70b
+ 3. glm/glm-4.7
+ 4. if/kimi-k2-thinking
+```
+
+When quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.
+
+#### 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)
+
+#### 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)
🚀 30. „Muszę dostarczać agentowe przepływy pracy bez konieczności rozrzucania kodu kleju”
+🚀 30. "I need to ship agentic workflows without glue-code sprawl"
-Zespoły tracą prędkość podczas łączenia wielu usług i skryptów ad hoc. +Teams lose velocity when stitching multiple ad-hoc services and scripts. -**Jak rozwiązuje to OmniRoute:** +**How OmniRoute solves it:** -- Ujednolicona strategia dotycząca punktów końcowych dla klientów i agentów -- Wbudowane interfejsy zarządzania protokołami i ścieżki sprawdzania dymu -- Podstawy gotowe do produkcji (bezpieczeństwo, logowanie, odporność, kopie zapasowe) +- Unified endpoint strategy for clients and agents +- Built-in protocol management UIs and smoke validation paths +- Production-ready foundations (security, logging, resilience, backup)
-` bloki → `reasoning_content` dla modeli myślących
-- **Ustrukturyzowane dane wyjściowe** — `json_schema` → Gemini `responseMimeType`/`responseSchema`
-
-### 👥 Obsługa wielu kont
-
-- Dodaj wiele kont na dostawcę
-- Automatyczne routing okrężny lub oparty na priorytetach
-- Powrót do następnego konta, gdy jedno osiągnie limit
-
-### 🔄 Automatyczne odświeżanie tokena
-
-- Tokeny OAuth są automatycznie odświeżane przed wygaśnięciem
-- Nie ma potrzeby ręcznego ponownego uwierzytelniania
-- Jednolite doświadczenie u wszystkich dostawców
-
-### 🎨 Niestandardowe kombinacje
-
-- Twórz nieograniczone kombinacje modeli
-- 6 strategii: najpierw wypełnij, okrężnie, siła dwóch wyborów, losowa, najrzadziej używana, zoptymalizowana pod względem kosztów
-- Udostępniaj kombinacje na różnych urządzeniach dzięki Cloud Sync
-
-### 🏥 Panel zdrowia
-
-- Stan systemu (czas działania, wersja, wykorzystanie pamięci)
-- Stany wyłączników według dostawcy (zamknięty/otwarty/półotwarty)
-- Stan limitu szybkości i aktywne blokady
-- Statystyki pamięci podręcznej podpisów
-- Telemetria opóźnień (p50/p95/p99) + pamięć podręczna podpowiedzi
-- Zresetuj stan zdrowia jednym kliknięciem
-
-### 🔧 Plac zabaw dla tłumaczy
-
-OmniRoute zawiera potężny, wbudowany plac zabaw dla tłumaczy z **4 trybami** do debugowania, testowania i monitorowania tłumaczeń API:
-
-| Tryb | Opis |
-| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **💻 Plac zabaw** | Bezpośrednie tłumaczenie formatu — wklej dowolną treść żądania API i od razu zobacz, jak OmniRoute tłumaczy ją pomiędzy formatami dostawców (OpenAI ↔ Claude ↔ Gemini ↔ Responses API). Zawiera przykładowe szablony i automatyczne wykrywanie formatu. |
-| **💬 Tester czatu** | Wysyłaj prawdziwe prośby o czat za pośrednictwem OmniRoute i zobacz pełny przebieg: Twoje dane wejściowe, przetłumaczone żądanie, odpowiedź dostawcy i przetłumaczona odpowiedź z powrotem. Nieocenione przy sprawdzaniu routingu combo. |
-| **🧪 Stanowisko testowe** | Tryb testowania wsadowego — zdefiniuj wiele przypadków testowych z różnymi danymi wejściowymi i oczekiwanymi wynikami, uruchom je wszystkie na raz i porównaj wyniki u różnych dostawców i modeli. |
-| **📱 Monitorowanie na żywo** | Monitorowanie żądań w czasie rzeczywistym — obserwuj przychodzące żądania przepływające przez OmniRoute, obserwuj na żywo tłumaczenia formatów i natychmiast identyfikuj problemy. |
-
-**Dostęp:** Panel → Tłumacz (pasek boczny)
-
-### 💾 Synchronizacja z chmurą
-
-- Synchronizuj dostawców, kombinacje i ustawienia na różnych urządzeniach
-- Automatyczna synchronizacja w tle
-- Bezpieczne szyfrowane przechowywanie
+- `GET /api/mcp/status`
+- `GET /api/mcp/tools`
+- `GET /api/mcp/audit`
+- `GET /api/mcp/audit/stats`
-## 🧪 Oceny (Ewaluacje)
+📖 Szczegóły funkcji
+🧩 MCP Setup (Model Context Protocol)
-### 🎯 Inteligentny 4-poziomowy powrót awaryjny +Start MCP transport in stdio mode: -Twórz kombinacje z automatycznym cofaniem: - -``` -Combo: "my-coding-stack" - 1. cc/claude-opus-4-6 (your subscription) - 2. nvidia/llama-3.3-70b (free NVIDIA API) - 3. glm/glm-4.7 (cheap backup, $0.6/1M) - 4. if/kimi-k2-thinking (free fallback) - -→ Auto switches when quota runs out or errors occur +```bash +omniroute --mcp ``` -### 📊 Śledzenie limitów w czasie rzeczywistym +Recommended validation flow: -- Zużycie tokenów na dostawcę -- Zresetuj odliczanie (5-godzinne, dzienne, tygodniowe) -- Szacowanie kosztów dla płatnych poziomów -- Miesięczne raporty wydatków +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. -### 🔄 Tłumaczenie formatu +Useful APIs for automation: -Płynne tłumaczenie pomiędzy formatami: - -- **OpenAI** ↔ **Claude** ↔ **Bliźnięta** ↔ **Odpowiedzi OpenAI** -- Twoje narzędzie CLI wysyła format OpenAI → OmniRoute tłumaczy → Dostawca otrzymuje format natywny -- Działa z każdym narzędziem obsługującym niestandardowe punkty końcowe OpenAI -- **Oczyszczanie odpowiedzi** — Usuwa niestandardowe pola w celu zapewnienia ścisłej zgodności z OpenAI SDK -- **Normalizacja ról** — `developer` → `system` dla innych niż OpenAI; `system` → `user` dla modeli GLM/ERNIE -- **Pomyśl o ekstrakcji tagów** — `
+
🤝 A2A Setup (Agent2Agent)
-OmniRoute zawiera wbudowaną platformę ewaluacyjną do testowania jakości odpowiedzi LLM na podstawie złotego zestawu. Uzyskaj do niego dostęp poprzez **Analytics → Evals** na pulpicie nawigacyjnym. +Discover the agent: -### Wbudowany złoty zestaw +```bash +curl http://localhost:20128/.well-known/agent.json +``` -Fabrycznie załadowany „Złoty zestaw OmniRoute” zawiera 10 przypadków testowych obejmujących: +Send a task: -- Pozdrowienia, matematyka, geografia, generowanie kodu -- Zgodność z formatem JSON, tłumaczenie, przecena -- Odmowa bezpieczeństwa (szkodliwa treść), liczenie, logika boolowska +```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."}]}}' +``` -### Strategie oceny +Manage lifecycle: -| Strategia | Opis | Przykład | -| ---------- | ----------------------------------------------------------------------- | -------------------------------- | -| `exact` | Dane wyjściowe muszą dokładnie odpowiadać | `"4"` | -| `contains` | Dane wyjściowe muszą zawierać podciąg (wielkość liter nie ma znaczenia) | `"Paris"` | -| `regex` | Dane wyjściowe muszą pasować do wzorca wyrażenia regularnego | `"1.*2.*3"` | -| `custom` | Niestandardowa funkcja JS zwraca wartość prawda/fałsz | `(output) => output.length > 10` | +- `GET /api/a2a/status` +- `GET /api/a2a/tasks` +- `GET /api/a2a/tasks/:id` +- `POST /api/a2a/tasks/:id/cancel` ---- +Operational UI: -## 📖 Przewodnik konfiguracji +- `/dashboard/a2a` for task/state/stream observability and smoke actions + +
-
+
+💳 Dostawcy subskrypcji
+🧪 End-to-end protocol validation
-### Kod Claude’a (Pro/Max) +Validate both protocols with real clients: + +```bash +npm run test:protocols:e2e +``` + +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) ```bash Dashboard → Providers → Connect Claude Code @@ -1065,9 +1438,9 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Wskazówka dla profesjonalistów:** używaj Opus do skomplikowanych zadań, a Sonnet do szybkości. OmniRoute śledzi limit na model! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! -### Kodeks OpenAI (Plus/Pro) +### OpenAI Codex (Plus/Pro) ```bash Dashboard → Providers → Connect Codex @@ -1079,7 +1452,24 @@ Models: cx/gpt-5.1-codex-max ``` -### Gemini CLI (DARMOWE 180 tys./miesiąc!) +#### 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). + +### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -1091,9 +1481,9 @@ Models: gc/gemini-2.5-pro ``` -**Najlepsza wartość:** Ogromny darmowy poziom! Użyj tego przed płatnymi poziomami. +**Best Value:** Huge free tier! Use this before paid tiers. -### Drugi pilot GitHuba +### GitHub Copilot ```bash Dashboard → Providers → Connect GitHub @@ -1109,88 +1499,88 @@ Models:
-
🔑 Dostawcy kluczy API
+🔑 API Key Providers
-### NVIDIA NIM (DARMOWE 1000 kredytów!) +### NVIDIA NIM (FREE developer access — 70+ models) -1. Zarejestruj się: [build.nvidia.com](https://build.nvidia.com) -2. Uzyskaj bezpłatny klucz API (w cenie 1000 kredytów) -3. Panel kontrolny → Dodaj dostawcę → NVIDIA NIM: - - Klucz API: `nvapi-your-key` +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` -**Modele:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct` i ponad 50 innych +**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more -**Wskazówka dla profesjonalistów:** API zgodne z OpenAI — działa bezproblemowo z tłumaczeniem formatu OmniRoute! +**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation! ### DeepSeek -1. Zarejestruj się: [platform.deepseek.com](https://platform.deepseek.com) -2. Zdobądź klucz API -3. Panel kontrolny → Dodaj dostawcę → DeepSeek +1. Sign up: [platform.deepseek.com](https://platform.deepseek.com) +2. Get API key +3. Dashboard → Add Provider → DeepSeek -**Modele:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` +**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` -### Groq (dostępny bezpłatny poziom!) +### Groq (Free Tier Available!) -1. Zarejestruj się: [console.groq.com](https://console.groq.com) -2. Uzyskaj klucz API (w cenie bezpłatna warstwa) -3. Panel kontrolny → Dodaj dostawcę → Groq +1. Sign up: [console.groq.com](https://console.groq.com) +2. Get API key (free tier included) +3. Dashboard → Add Provider → Groq -**Modele:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` +**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` -**Wskazówka dla profesjonalistów:** Ultraszybkie wnioskowanie — najlepsze do kodowania w czasie rzeczywistym! +**Pro Tip:** Ultra-fast inference — best for real-time coding! -### OpenRouter (ponad 100 modeli) +### OpenRouter (100+ Models) -1. Zarejestruj się: [openrouter.ai](https://openrouter.ai) -2. Zdobądź klucz API -3. Panel kontrolny → Dodaj dostawcę → OpenRouter +1. Sign up: [openrouter.ai](https://openrouter.ai) +2. Get API key +3. Dashboard → Add Provider → OpenRouter -**Modele:** Uzyskaj dostęp do ponad 100 modeli wszystkich głównych dostawców za pomocą jednego klucza API. +**Models:** Access 100+ models from all major providers through a single API key.
-
💰 Tani dostawcy (kopia zapasowa)
+💰 Cheap Providers (Backup)
-### GLM-4.7 (reset dzienny, 0,6 USD/1 mln) +### GLM-4.7 (Daily reset, $0.6/1M) -1. Zarejestruj się: [Zhipu AI](https://open.bigmodel.cn/) -2. Uzyskaj klucz API z planu kodowania -3. Panel → Dodaj klucz API: - - Dostawca: `glm` - - Klucz API: `your-key` +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` -**Użyj:** `glm/glm-4.7` +**Use:** `glm/glm-4.7` -**Wskazówka dla profesjonalistów:** Plan kodowania oferuje 3× limit przy cenie 1/7! Resetuj codziennie o 10:00. +**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -### MiniMax M2.1 (reset 5 godz., 0,20 USD/1 mln) +### MiniMax M2.1 (5h reset, $0.20/1M) -1. Zarejestruj się: [MiniMax](https://www.minimax.io/) -2. Zdobądź klucz API -3. Panel → Dodaj klucz API +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key +3. Dashboard → Add API Key -**Użyj:** `minimax/MiniMax-M2.1` +**Use:** `minimax/MiniMax-M2.1` -**Wskazówka dla profesjonalistów:** Najtańsza opcja dla długiego kontekstu (1 milion tokenów)! +**Pro Tip:** Cheapest option for long context (1M tokens)! -### Kimi K2 (9 USD miesięcznie) +### Kimi K2 ($9/month flat) -1. Subskrybuj: [Moonshot AI](https://platform.moonshot.ai/) -2. Zdobądź klucz API -3. Panel → Dodaj klucz API +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key +3. Dashboard → Add API Key -**Użyj:** `kimi/kimi-latest` +**Use:** `kimi/kimi-latest` -**Wskazówka dla profesjonalistów:** Naprawiono 9 USD miesięcznie za 10 mln tokenów = efektywny koszt 0,90 USD/1 mln! +**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
-
🆓 BEZPŁATNI dostawcy (awaryjna kopia zapasowa)
+🆓 FREE Providers (Emergency Backup)
-### iFlow (8 DARMOWYCH modeli) +### iFlow (5 FREE models via OAuth) ```bash Dashboard → Connect iFlow @@ -1205,7 +1595,7 @@ Models: if/deepseek-r1 ``` -### Qwen (3 DARMOWE modele) +### Qwen (4 FREE models via Device Code) ```bash Dashboard → Connect Qwen @@ -1217,7 +1607,7 @@ Models: qw/qwen3-coder-flash ``` -### Kiro (Claude ZA DARMO) +### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro @@ -1232,9 +1622,9 @@ Models:
-
🎨 Utwórz kombinacje
+🎨 Create Combos
-### Przykład 1: Maksymalizuj subskrypcję → Tania kopia zapasowa +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -1248,7 +1638,7 @@ Models: Use in CLI: premium-coding ``` -### Przykład 2: Tylko bezpłatny (zero kosztów) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -1263,9 +1653,9 @@ Cost: $0 forever!
-
---
-## 🐛 Rozwiązywanie problemów
+## Rozwiązywanie problemów
🔧 Integracja z CLI
+🔧 CLI Integration
-### IDE kursora +### Cursor IDE ``` Settings → Models → Advanced: @@ -1274,11 +1664,11 @@ Settings → Models → Advanced: Model: cc/claude-opus-4-6 ``` -### Kod Claude’a +### Claude Code -Użyj strony **Narzędzia CLI** w panelu kontrolnym, aby dokonać konfiguracji jednym kliknięciem, lub edytuj ręcznie `~/.claude/settings.json`. +Use the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually. -### Interfejs wiersza polecenia Kodeksu +### Codex CLI ```bash export OPENAI_BASE_URL="http://localhost:20128" @@ -1289,13 +1679,13 @@ codex "your prompt" ### OpenClaw -**Opcja 1 — Panel kontrolny (zalecany):** +**Option 1 — Dashboard (recommended):** ``` Dashboard → CLI Tools → OpenClaw → Select Model → Apply ``` -**Opcja 2 — Ręcznie:** Edytuj `~/.openclaw/openclaw.json`: +**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`: ```json { @@ -1311,9 +1701,9 @@ Dashboard → CLI Tools → OpenClaw → Select Model → Apply } ``` -> **Uwaga:** OpenClaw działa tylko z lokalnym OmniRoute. Użyj `127.0.0.1` zamiast `localhost`, aby uniknąć problemów z rozdzielczością IPv6. +> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues. -### Kliknij / Kontynuuj / RooCode +### Cline / Continue / RooCode ``` Settings → API Configuration: @@ -1323,110 +1713,245 @@ Settings → API Configuration: 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. +
-
-- **Środowisko wykonawcze**: Node.js 18–22 LTS (⚠️ Node.js 24+ jest **nieobsługiwany** — `better-sqlite3` natywne pliki binarne są niekompatybilne)
-- **Język**: TypeScript 5.9 — **100% TypeScript** w `src/` i `open-sse/` (v1.0.6)
-- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4
-- **Baza danych**: LowDB (JSON) + SQLite (stan domeny + logi proxy)
-- **Streaming**: zdarzenia wysyłane przez serwer (SSE)
-- **Auth**: OAuth 2.0 (PKCE) + JWT + klucze API
-- **Testowanie**: Uruchomienie testu Node.js (ponad 368 testów jednostkowych)
-- **CI/CD**: Akcje GitHub (automatyczne publikowanie npm + Docker Hub w momencie wydania)
-- **Strona internetowa**: [omniroute.online](https://omniroute.online)
-- **Pakiet**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
-- **Doker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
-- **Odporność**: wyłącznik automatyczny, wykładnicze wycofywanie, stado przeciwgrzmotowe, fałszowanie TLS
-
----
-
-## 📖 Dokumentacja
-
-| Dokument | Opis |
-| -------------------------------------------- | ----------------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Dostawcy, kombinacje, integracja CLI, wdrożenie |
-| [API Reference](docs/API_REFERENCE.md) | Wszystkie punkty końcowe z przykładami |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Typowe problemy i rozwiązania |
-| [Architecture](docs/ARCHITECTURE.md) | Architektura systemu i elementy wewnętrzne |
-| [Contributing](CONTRIBUTING.md) | Konfiguracja i wytyczne dotyczące programowania |
-| [OpenAPI Spec](docs/openapi.yaml) | Specyfikacja OpenAPI 3.0 |
-| [Security Policy](SECURITY.md) | Zgłaszanie luk w zabezpieczeniach i praktyki bezpieczeństwa |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Kompletny przewodnik: konfiguracja VM + nginx + Cloudflare |
-| [Features Gallery](docs/FEATURES.md) | Wizualna wycieczka po panelu ze zrzutami ekranu |
-
-### 📸 Podgląd panelu
+## 🛠️ Tech Stack
Kliknij, aby rozwinąć przewodnik rozwiązywania problemów
+Click to expand troubleshooting guide
-**„Model językowy nie dostarczał komunikatów”** +**"Language model did not provide messages"** -- Wyczerpany limit dostawcy → Sprawdź moduł śledzenia limitów na pulpicie nawigacyjnym -- Rozwiązanie: użyj kombinacji zastępczej lub przejdź na tańszy poziom +- Provider quota exhausted → Check dashboard quota tracker +- Solution: Use combo fallback or switch to cheaper tier -**Ograniczenie szybkości** +**Rate limiting** -- Limit subskrypcji wyczerpany → Powrót do GLM/MiniMax -- Dodaj kombinację: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Subscription quota out → Fallback to GLM/MiniMax +- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -**Token OAuth wygasł** +**OAuth token expired** -- Automatyczne odświeżanie przez OmniRoute -- Jeśli problemy nadal występują: Panel kontrolny → Dostawca → Połącz ponownie +- Auto-refreshed by OmniRoute +- If issues persist: Dashboard → Provider → Reconnect -**Wysokie koszty** +**High costs** -- Sprawdź statystyki użytkowania w Panelu → Koszty -- Zmień model podstawowy na GLM/MiniMax -- Korzystaj z bezpłatnej warstwy (Gemini CLI, iFlow) do zadań niekrytycznych +- Check usage stats in Dashboard → Costs +- Switch primary model to GLM/MiniMax +- Use free tier (Gemini CLI, iFlow) for non-critical tasks -** Panel otwiera się na złym porcie ** +**Dashboard/API ports are wrong** -- Ustaw `PORT=20128` i `NEXT_PUBLIC_BASE_URL=http://localhost:20128` +- `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) -**Błędy synchronizacji z chmurą** +**Cloud sync errors** -- Sprawdź, czy `BASE_URL` wskazuje na działającą instancję -- Sprawdź, czy `CLOUD_URL` wskazuje na oczekiwany punkt końcowy w chmurze -- Zachowaj wyrównanie wartości `NEXT_PUBLIC_*` z wartościami po stronie serwera +- 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 -**Pierwsze logowanie nie działa** +**First login not working** -- Sprawdź `INITIAL_PASSWORD` w `.env` -- Jeśli nieustawione, hasło zastępcze to `123456` +- Check `INITIAL_PASSWORD` in `.env` +- If unset, fallback password is `123456` -**Brak dzienników żądań** +**No request logs** -- Ustaw `ENABLE_REQUEST_LOGS=true` w `.env` +- Set `ENABLE_REQUEST_LOGS=true` in `.env` -**Test połączenia pokazuje „Nieprawidłowy” dla dostawców kompatybilnych z OpenAI** +**Connection test shows "Invalid" for OpenAI-compatible providers** -- Wielu dostawców nie udostępnia punktu końcowego `/models` -- OmniRoute v1.0.6+ zawiera weryfikację awaryjną poprzez uzupełnianie czatu -- Upewnij się, że podstawowy adres URL zawiera przyrostek `/v1` +- 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 na serwerze zdalnym (zdalna konfiguracja OAuth) +### 🔐 OAuth on a Remote Server + -> **⚠️ WAŻNE dla zwykłych usług OmniRoute w VPS/Docker/serwidor zdalny** +> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server** -#### OAuth +#### Why does Antigravity / Gemini CLI OAuth fail on remote servers? -Sprawdzone **Antigravity** i **Gemini CLI** używane **Google OAuth 2.0** dla autentyczności. O Google, jeśli potrzebujesz `redirect_uri`, aby nie zmieniać protokołu OAuth seja **exatamente** uma das URI pre-cadastradas no Google Cloud Console to aplicativo. +The **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console. -Jako uwierzytelnienie OAuth zostało wydane przez OmniRoute w cadastradas **apenas dla `localhost`**. Możesz uzyskać dostęp do OmniRoute na serwerze zdalnym (np.: `https://omniroute.meuservidor.com`), lub Google rejeita a autenticação com: +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 ``` -### Rozwiązanie: Skonfiguruj suas próprias credenciais OAuth +#### Solution: Configure your own OAuth credentials -Precyzyjne żądanie **Identyfikator klienta OAuth 2.0** nie Google Cloud Console poprzez URI do tego serwera. +You need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI. -#### Passo za passo +#### Step-by-step -**1. Dostęp do konsoli Google Cloud** +**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 + +# For Gemini CLI: +GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com +GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +``` + +**6. Restart OmniRoute** + +```bash +# npm: +npm run dev + +# Docker: +docker restart omniroute +``` + +**7. Try connecting again** + +Dashboard → Providers → Antigravity (or Gemini CLI) → OAuth + +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. + +--- + +
+
---
-## 🛠️
+🇧🇷 Versão em Português
+ +#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos? + +Os provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo. + +As credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticação com: + +``` +Error 400: redirect_uri_mismatch +``` + +#### Solução: Configure suas próprias credenciais OAuth + +Você precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor. + +#### Passo a passo + +**1. Acesse o Google Cloud Console** Abra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) -**2. Wezwij nowy identyfikator klienta OAuth 2.0** +**2. Crie um novo OAuth 2.0 Client ID** -- Kliknij **"+ Utwórz dane uwierzytelniające"** → **"Identyfikator klienta OAuth"** -- Typ aplikacji: **"Aplikacja internetowa"** -- Nazwa: escolha qualquer nom (np.: `OmniRoute Remote`) +- Clique em **"+ Create Credentials"** → **"OAuth client ID"** +- Tipo de aplicativo: **"Web application"** +- Nome: escolha qualquer nome (ex: `OmniRoute Remote`) -**3. Adicione jako autoryzowane identyfikatory URI przekierowań** +**3. Adicione as Authorized Redirect URIs** -Bez komentarza **„Autoryzowane identyfikatory URI przekierowań”**, rada: +No campo **"Authorized redirect URIs"**, adicione: ``` https://seu-servidor.com/callback ``` -> Substitua `seu-servidor.com` pelo domínio lub IP do seu servidor (w tym porta se necessário, np.: `http://45.33.32.156:20128/callback`). +> Substitua `seu-servidor.com` pelo domínio ou IP do seu servidor (inclua a porta se necessário, ex: `http://45.33.32.156:20128/callback`). -**4. Zapisz i skopiuj jako poświadczenie** +**4. Salve e copie as credenciais** -Após criar, o Google mostrará o **Identyfikator klienta** i o **Tajemnica klienta**. +Após criar, o Google mostrará o **Client ID** e o **Client Secret**. -**5. Skonfiguruj jako variáveis de ambiente** +**5. Configure as variáveis de ambiente** -Nie seu `.env` (lub nas variáveis de ambiente do Docker): +No seu `.env` (ou nas variáveis de ambiente do Docker): ```bash # Para Antigravity: @@ -1439,7 +1964,7 @@ GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret ``` -**6. Reinicie lub OmniRoute** +**6. Reinicie o OmniRoute** ```bash # Se usando npm: @@ -1451,151 +1976,145 @@ docker restart omniroute **7. Tente conectar novamente** -Panel kontrolny → Dostawcy → Antygrawitacja (lub Gemini CLI) → OAuth +Dashboard → Providers → Antigravity (ou Gemini CLI) → OAuth -Agora o Google redirecionará corretamente dla `https://seu-servidor.com/callback` i autentyczna funkcja. +Agora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará. --- -### Obejście tymczasowe (sem configurar credenciais prróprias) +#### Workaround temporário (sem configurar credenciais próprias) -Jeśli chcesz uzyskać dostęp do **podręcznika URL**: +Se não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**: -1. OmniRoute abrirá adres URL autoryzacji w Google +1. O OmniRoute abrirá a URL de autorização do Google 2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto) -3. **Skopiuj kompletny adres URL** da barra de endereço do seu przeglądarki (wiadomość que a página não carregue) +3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue) 4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute -5. Kliknij je **„Połącz”** +5. Clique em **"Connect"** -> To obejście funkcji porque o kodigo de autorização na URL é válido niezależny do przekierowania ter carregado ou não. +> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.
-
---
-## 🗺️
+## Dokumentacja
-OmniRoute ma **ponad 210 funkcji zaplanowanych** w wielu fazach rozwoju. Oto kluczowe obszary:
-
-| Kategoria | Planowane funkcje | Najważniejsze |
-| -------------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |
-| 🧠 **Routing i inteligencja** | 25+ | Routing z najmniejszym opóźnieniem, routing oparty na tagach, wstępna inspekcja przydziału, wybór konta P2C |
-| 🔒 **Bezpieczeństwo i zgodność** | 20+ | Wzmocnienie SSRF, maskowanie poświadczeń, limit szybkości na punkt końcowy, zakres kluczy zarządzania |
-| 📊 **Obserwowalność** | 15+ | Integracja OpenTelemetry, monitorowanie kwot w czasie rzeczywistym, śledzenie kosztów według modelu |
-| 🔄 **Integracja dostawców** | 20+ | Rejestr modeli dynamicznych, czasy odnowienia dostawcy, Kodeks dla wielu kont, analiza przydziału Copilot |
-| ⚡ **Wydajność** | 15+ | Podwójna warstwa pamięci podręcznej, pamięć podręczna podpowiedzi, pamięć podręczna odpowiedzi, utrzymywanie transmisji strumieniowej, wsadowe API |
-| 🌐 **Ekosystem** | 10+ | WebSocket API, ładowanie konfiguracji na gorąco, rozproszony magazyn konfiguracji, tryb komercyjny |
-
-### 🔜 Już wkrótce
-
-- 🔗 **Integracja OpenCode** — natywna obsługa dostawców dla IDE kodowania OpenCode AI
-- 🔗 **Integracja z TRAE** — Pełne wsparcie dla platformy rozwojowej TRAE AI
-- 📦 **Batch API** — Asynchroniczne przetwarzanie wsadowe dla żądań masowych
-- 🎯 **Routing oparty na tagach** — Kieruj żądania na podstawie niestandardowych tagów i metadanych
-- 💰 **Strategia najniższych kosztów** — Automatycznie wybierz najtańszego dostępnego dostawcę
-
-> 📝 Pełna specyfikacja funkcji dostępna w [link](docs/new-features/) (217 szczegółowych specyfikacji)
+| Document | Description |
+| ---------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 16 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/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
+| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
-## 👥 Współtwórcy
+## 🗺️ Roadmap
+
+OmniRoute has **210+ 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, P2C account selection |
+| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |
+| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |
+| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider 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
[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
-### Jak wnieść swój wkład
+### How to Contribute
-1. Forkuj repozytorium
-2. Utwórz gałąź funkcji (`git checkout -b feature/amazing-feature`)
-3. Zatwierdź zmiany (`git commit -m 'Add amazing feature'`)
-4. Wciśnij do oddziału (`git push origin feature/amazing-feature`)
-5. Otwórz żądanie ściągnięcia
+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
-Szczegółowe wytyczne można znaleźć w [CONTRIBUTING.md](CONTRIBUTING.md).
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
-### Wydanie nowej wersji
+### Releasing a New Version
```bash
# Create a release — npm publish happens automatically
-gh release create v1.0.6 --title "v1.0.6" --generate-notes
+gh release create v2.0.0 --title "v2.0.0" --generate-notes
```
---
-## 📊 Historia gwiazd
+## 📊 Star History
## Stargazers over time
## [](https://starchart.cc/diegosouzapw/OmniRoute)
-## 🙏 Podziękowania
+## 🙏 Acknowledgments
-Specjalne podziękowania dla **[9router](https://github.com/decolua/9router)** autorstwa **[decolua](https://github.com/decolua)** — oryginalnego projektu, który zainspirował ten widelec. OmniRoute opiera się na tym niesamowitym fundamencie dzięki dodatkowym funkcjom, wielomodalnym interfejsom API i pełnemu przepisaniu TypeScriptu.
+Special thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.
-Specjalne podziękowania dla **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — oryginalnej implementacji Go, która zainspirowała ten port JavaScript.
+Special thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.
---
-## 📄 Licencja
+## Licencja
-Licencja MIT — szczegółowe informacje można znaleźć w [LICENSE](LICENSE).
+MIT License - see [LICENSE](LICENSE) for details.
---
Kliknij, aby zobaczyć zrzuty ekranu panelu kontrolnego
+Click to expand tech stack details
-| Strona | Zrzut ekranu | -| ------------------------- | ------------------------------------------------- | -| **Dostawcy** |  | -| **Kombinacje** |  | -| **Analiza** |  | -| **Zdrowie** |  | -| **Tłumacz** |  | -| **Ustawienia** |  | -| **Narzędzia CLI** |  | -| **Dzienniki użytkowania** |  | -| **Punkt końcowy** |  | +- **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**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions) +- **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
- Zbudowany z ❤️ dla programistów, którzy kodują 24 godziny na dobę, 7 dni w tygodniu
+ Built with ❤️ for developers who code 24/7
omniroute.online
+
diff --git a/docs/i18n/pl/docs/FEATURES.md b/docs/i18n/pl/docs/FEATURES.md
new file mode 100644
index 0000000000..d5b54bf992
--- /dev/null
+++ b/docs/i18n/pl/docs/FEATURES.md
@@ -0,0 +1,145 @@
+# OmniRoute — Dashboard Features Gallery (Polski)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/FEATURES.md) · 🇪🇸 [es](../../es/docs/FEATURES.md) · 🇫🇷 [fr](../../fr/docs/FEATURES.md) · 🇩🇪 [de](../../de/docs/FEATURES.md) · 🇮🇹 [it](../../it/docs/FEATURES.md) · 🇷🇺 [ru](../../ru/docs/FEATURES.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FEATURES.md) · 🇯🇵 [ja](../../ja/docs/FEATURES.md) · 🇰🇷 [ko](../../ko/docs/FEATURES.md) · 🇸🇦 [ar](../../ar/docs/FEATURES.md) · 🇮🇳 [in](../../in/docs/FEATURES.md) · 🇹🇭 [th](../../th/docs/FEATURES.md) · 🇻🇳 [vi](../../vi/docs/FEATURES.md) · 🇮🇩 [id](../../id/docs/FEATURES.md) · 🇲🇾 [ms](../../ms/docs/FEATURES.md) · 🇳🇱 [nl](../../nl/docs/FEATURES.md) · 🇵🇱 [pl](../../pl/docs/FEATURES.md) · 🇸🇪 [sv](../../sv/docs/FEATURES.md) · 🇳🇴 [no](../../no/docs/FEATURES.md) · 🇩🇰 [da](../../da/docs/FEATURES.md) · 🇫🇮 [fi](../../fi/docs/FEATURES.md) · 🇵🇹 [pt](../../pt/docs/FEATURES.md) · 🇷🇴 [ro](../../ro/docs/FEATURES.md) · 🇭🇺 [hu](../../hu/docs/FEATURES.md) · 🇧🇬 [bg](../../bg/docs/FEATURES.md) · 🇸🇰 [sk](../../sk/docs/FEATURES.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FEATURES.md) · 🇮🇱 [he](../../he/docs/FEATURES.md) · 🇵🇭 [phi](../../phi/docs/FEATURES.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FEATURES.md)
+
+---
+
+Visual guide to every section of the OmniRoute dashboard.
+
+---
+
+## 🔌 Providers
+
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
+
+
+
+---
+
+## 🎨 Combos
+
+Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
+
+
+
+---
+
+## 📊 Analytics
+
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
+
+
+
+---
+
+## 🏥 System Health
+
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+
+
+
+---
+
+## 🔧 Translator Playground
+
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
+
+
+
+---
+
+## 🎮 Model Playground _(v2.0.9+)_
+
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
+
+---
+
+## 🎨 Themes _(v2.0.5+)_
+
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
+
+## ⚙️ Settings
+
+Comprehensive settings panel with tabs:
+
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning
+- **Advanced** — Configuration overrides
+
+
+
+---
+
+## 🔧 CLI Tools
+
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
+
+
+
+---
+
+## 🤖 CLI Agents _(v2.0.11+)_
+
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
+
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
+
+---
+
+## 🖼️ Media _(v2.0.3+)_
+
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
+
+## 📝 Request Logs
+
+Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
+
+
+
+---
+
+## 🌐 API Endpoint
+
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
+
+
+
+---
+
+## 🔑 API Key Management
+
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
+
+---
+
+## 📋 Audit Log
+
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
+
+---
+
+## 🖥️ Desktop Application
+
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
+
+Key features:
+
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
+
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.
diff --git a/docs/i18n/pt-BR/README.md b/docs/i18n/pt-BR/README.md
index 047330588d..89c47c048b 100644
--- a/docs/i18n/pt-BR/README.md
+++ b/docs/i18n/pt-BR/README.md
@@ -1,24 +1,94 @@
-omniroute.online
-
-
- # 🚀 OmniRoute — O Gateway de IA Gratuito
+# 🚀 OmniRoute — The Free AI Gateway (Português (Brasil))
-### Nunca pare de programar. Roteamento inteligente para **modelos de IA GRATUITOS e baratos** com fallback automático.
-
-_Seu proxy de API universal — um endpoint, 36+ provedores, zero tempo de inatividade._
-
-**Chat Completions • Embeddings • Geração de Imagem • Vídeo • Música • Áudio • Reranking • 100% TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Provedor de IA Gratuito para seus agentes de programação favoritos
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Conecte qualquer IDE ou ferramenta CLI com IA através do OmniRoute — gateway de API gratuito para programação ilimitada._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+` tags no longer leak to clients in SSE streaming responses (#585) |
+| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with per-provider/account quota enforcement, idempotency, SHA-256 storage, and optional GitHub issue reporting |
+| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG → generic fallback chain |
+| 🔄 **Model Auto-Sync** | 24h scheduler and manual UI toggle to sync model lists for built-in and custom OpenAI-compatible providers |
+| 🌐 **OpenCode Zen/Go** | Two new providers from @kang-heewon via PR #530: free tier + subscription tier via `OpencodeExecutor` |
+| 🐛 **Gemini CLI OAuth** | Actionable error when `GEMINI_OAUTH_CLIENT_SECRET` is missing in Docker (was cryptic Google error) |
+| 🐛 **OpenCode config** | `saveOpenCodeConfig()` now correctly writes TOML to `XDG_CONFIG_HOME` |
+| 🐛 **Pinned model override** | `body.model` correctly set to `pinnedModel` on context-cache protection |
+| 🐛 **Codex/Claude loop** | `tool_result` blocks now converted to text to stop infinite loops |
+| 🐛 **Login redirect** | Login no longer freezes after skipping password setup |
+| 🐛 **Windows paths** | MSYS2/Git-Bash paths (`/c/...`) normalized to `C:\...` automatically |
+
+---
+
+## 🖼️ Main Dashboard
+
+
-📡 Todos os agentes se conectam via ` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**Stop wasting money and hitting limits:**
-### 🆕 What's New in v3.0.0
+- Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**OmniRoute solves this:**
+
+- ✅ **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
+- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool
---
-[](https://www.npmjs.com/package/omniroute)
-[](https://hub.docker.com/r/diegosouzapw/omniroute)
-[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
-[](https://omniroute.online)
-[](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
+## 📧 Support
-[🌐 Website](https://omniroute.online) • [🚀 Início Rápido](#-início-rápido) • [💡 Funcionalidades](#-funcionalidades-principais) • [📖 Docs](#-documentação) • [💰 Preços](#-preços-resumidos)
-
-🌐 **Available in:** 🇺🇸 [English](../../README.md) | 🇧🇷 [Português (Brasil)](../pt-BR/README.md) | 🇪🇸 [Español](../es/README.md) | 🇫🇷 [Français](../fr/README.md) | 🇮🇹 [Italiano](../it/README.md) | 🇷🇺 [Русский](../ru/README.md) | 🇨🇳 [中文 (简体)](../zh-CN/README.md) | 🇩🇪 [Deutsch](../de/README.md) | 🇮🇳 [हिन्दी](../in/README.md) | 🇹🇭 [ไทย](../th/README.md) | 🇺🇦 [Українська](../uk-UA/README.md) | 🇸🇦 [العربية](../ar/README.md) | 🇯🇵 [日本語](../ja/README.md) | 🇻🇳 [Tiếng Việt](../vi/README.md) | 🇧🇬 [Български](../bg/README.md) | 🇩🇰 [Dansk](../da/README.md) | 🇫🇮 [Suomi](../fi/README.md) | 🇮🇱 [עברית](../he/README.md) | 🇭🇺 [Magyar](../hu/README.md) | 🇮🇩 [Bahasa Indonesia](../id/README.md) | 🇰🇷 [한국어](../ko/README.md) | 🇲🇾 [Bahasa Melayu](../ms/README.md) | 🇳🇱 [Nederlands](../nl/README.md) | 🇳🇴 [Norsk](../no/README.md) | 🇵🇹 [Português (Portugal)](../pt/README.md) | 🇷🇴 [Română](../ro/README.md) | 🇵🇱 [Polski](../pl/README.md) | 🇸🇰 [Slovenčina](../sk/README.md) | 🇸🇪 [Svenska](../sv/README.md) | 🇵🇭 [Filipino](../phi/README.md)
-
-
-
----
-
-## 🖼️
-
-
-
- # 🚀 OmniRoute — O Gateway de IA Gratuito
+# 🚀 OmniRoute — The Free AI Gateway (Português (Brasil))
-### Nunca pare de programar. Roteamento inteligente para **modelos de IA GRATUITOS e baratos** com fallback automático.
-
-_Seu proxy de API universal — um endpoint, 36+ provedores, zero tempo de inatividade._
-
-**Chat Completions • Embeddings • Geração de Imagem • Vídeo • Música • Áudio • Reranking • 100% TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Provedor de IA Gratuito para seus agentes de programação favoritos
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Conecte qualquer IDE ou ferramenta CLI com IA através do OmniRoute — gateway de API gratuito para programação ilimitada._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+
+
+[](https://www.npmjs.com/package/omniroute)
+[](https://www.npmjs.com/package/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
+[](https://omniroute.online)
+[](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)
+
+
+
+🌐 **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)
+
+---
+
+## 🆕 What's New in v3.0.0
+
+> **Upgrading from v2.9.5?** — See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes.
+
+| Area | Change |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection remediation |
+| ✅ **Route Validation** | All 176 API routes now validated with Zod schemas + `validateBody()` — CI `check:route-validation:t06` passes |
+| 🐛 **omniModel Tag Leak** | Internal `
+
+
+
+---
+
+## 📸 Dashboard Preview
+
+
+
+
+
+---
+
+### 🤖 Free AI Provider for your favorite coding agents
+
+_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._
Click to see dashboard screenshots
+ +| Page | Screenshot | +| -------------- | ------------------------------------------------- | +| **Providers** |  | +| **Combos** |  | +| **Analytics** |  | +| **Health** |  | +| **Translator** |  | +| **Settings** |  | +| **CLI Tools** |  | +| **Usage Logs** |  | +| **Endpoints** |  | + +|
-
+
OpenClaw @@ -92,586 +162,527 @@ _Conecte qualquer IDE ou ferramenta CLI com IA através do OmniRoute — gateway |
http://localhost:20128/v1 ou http://cloud.omniroute.online/v1 — uma configuração, modelos e cota ilimitados
+📡 All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 — one config, unlimited models and quota
---
-### 🆕 What's New in v3.0.0
+## 🤔 Why OmniRoute?
-| Area | Change |
-| ------------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal ` Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `
-
-
-
----
-
-## 📸
-
-
-
-
-
----
-
-## 🤔 Por que OmniRoute?
-
-**Pare de desperdiçar dinheiro e bater em limites:**
-
-- ...
- -| # | # | -| ----- | ---------------------------------------- | -| **1** |  | -| **2** |  | -| **3** |  | -| **4** |  | -| **5** |  | -| **6** |  | -| **7** |  | -| **8** |  | -| **9** |  | - - Cota de assinatura expira sem uso todo mês
-- Limites de taxa param você no meio da programação
-- APIs caras ($20-50/mês por provedor)
-- Trocar manualmente entre provedores
-
-**OmniRoute resolve isso:**
-
-- ✅ **Maximize assinaturas** - Rastreie cotas, use tudo antes do reset
-- ✅ **Fallback automático** - Assinatura → API Key → Barato → Gratuito, zero tempo de inatividade
-- ✅ **Multi-conta** - Round-robin entre contas por provedor
-- ✅ **Universal** - Funciona com Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, qualquer ferramenta CLI
-
----
-
-## 📧 Suporte
-
-> 💬 **Participe da comunidade!** [Grupo WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Tire dúvidas, compartilhe dicas e fique atualizado.
+> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.
- **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**: [Grupo da Comunidade](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Projeto Original**: [9router por decolua](https://github.com/decolua/9router)
+- **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`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 Como Funciona
+## 🔄 How It Works
```
┌─────────────┐
-│ Sua CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
+│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
│ Tool │
└──────┬──────┘
│ http://localhost:20128/v1
↓
┌─────────────────────────────────────────┐
-│ OmniRoute (Roteador Inteligente) │
-│ • Tradução de formato (OpenAI ↔ Claude) │
-│ • Rastreamento de cota + Embeddings + Imagens │
-│ • Renovação automática de tokens │
+│ OmniRoute (Smart Router) │
+│ • Format translation (OpenAI ↔ Claude) │
+│ • Quota tracking + Embeddings + Images │
+│ • Auto token refresh │
└──────┬──────────────────────────────────┘
│
- ├─→ [Tier 1: ASSINATURA] Claude Code, Codex, Gemini CLI
- │ ↓ cota esgotada
+ ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI
+ │ ↓ quota exhausted
├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.
- │ ↓ limite de orçamento
- ├─→ [Tier 3: BARATO] GLM ($0.6/1M), MiniMax ($0.2/1M)
- │ ↓ limite de orçamento
- └─→ [Tier 4: GRATUITO] iFlow, Qwen, Kiro (ilimitado)
+ │ ↓ budget limit
+ ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)
+ │ ↓ budget limit
+ └─→ [Tier 4: FREE] iFlow, Qwen, Kiro (unlimited)
-Resultado: Nunca pare de programar, custo mínimo
+Result: Never stop coding, minimal cost
```
---
-## 🎯 O que o OmniRoute resolve — 30 dores reais e casos de uso
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **Todo desenvolvedor que usa ferramentas de IA enfrenta esses problemas diariamente.** O OmniRoute foi criado para resolver todos eles, desde estouro de custos e bloqueios regionais até operações de protocolo e observabilidade de nível produção.
+> **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.
-
💸 1. "Pago uma assinatura cara e ainda sou interrompido por limites"
+💸 1. "I pay for an expensive subscription but still get interrupted by limits"
-Desenvolvedores pagam de $20 a $200/mês por Claude Pro, Codex Pro ou GitHub Copilot. Mesmo pagando, há teto de cota, limite de 5h, limites semanais ou por minuto. No meio da sessão de coding, o provedor para de responder e o desenvolvedor perde fluxo e produtividade. +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. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- **Fallback Inteligente em 4 Tiers** — Se a cota de assinatura acabar, redireciona automaticamente para API Key → Barato → Gratuito sem intervenção manual -- **Rastreamento de Cota em Tempo Real** — Exibe consumo de tokens ao vivo com contagem regressiva de reset (5h, diário, semanal) -- **Suporte Multi-Conta** — Várias contas por provedor com round-robin automático; quando uma esgota, passa para a próxima -- **Combos Personalizados** — Cadeias de fallback customizáveis com 6 estratégias (fill-first, round-robin, P2C, aleatório, least-used, cost-optimized) -- **Cotas Business do Codex** — Monitoramento de cota de workspace Business/Team direto no dashboard +- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention +- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly) +- **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 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
-` de modelos como DeepSeek R1 para `reasoning_content` padronizado
-- **Saída Estruturada no Gemini** — Conversão automática de `json_schema` → `responseMimeType`/`responseSchema`
-- **`stream` padrão `false`** — Alinha com a especificação OpenAI e evita SSE inesperado em SDKs Python/Rust/Go
+- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 67+ 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
🔌 2. "Preciso usar múltiplos provedores, mas cada um tem uma API diferente"
+🔌 2. "I need to use multiple providers but each has a different API"
-OpenAI usa um formato, Claude (Anthropic) usa outro, Gemini usa outro. Se o dev quer testar modelos de provedores diferentes ou fazer fallback entre eles, precisa reconfigurar SDKs, trocar endpoints e lidar com formatos incompatíveis. Provedores customizados (FriendLI, NIM) também têm endpoints não padronizados. +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. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- **Endpoint Unificado** — Um único `http://localhost:20128/v1` serve como proxy para 36+ provedores -- **Tradução de Formato** — Conversão automática e transparente: OpenAI ↔ Claude ↔ Gemini ↔ Responses API -- **Sanitização de Resposta** — Remove campos fora do padrão (`x_groq`, `usage_breakdown`, `service_tier`) que quebram OpenAI SDK v1.83+ -- **Normalização de Roles** — Converte `developer` → `system` para provedores não-OpenAI; `system` → `user` para GLM/ERNIE -- **Extração de Tags Think** — Extrai blocos `
-
🌐 3. "Meu provedor de IA bloqueia minha região/país"
+🌐 3. "My AI provider blocks my region/country"
-Provedores como OpenAI/Codex bloqueiam acesso em determinadas regiões. Usuários recebem erros como `unsupported_country_region_territory` durante OAuth e conexões de API. Isso é especialmente frustrante para desenvolvedores de países emergentes. +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. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- **Config de Proxy em 3 Níveis** — Proxy configurável em nível global (todo tráfego), por provedor e por conexão/chave -- **Badges de Proxy por Cor** — Indicadores visuais: 🟢 proxy global, 🟡 proxy do provedor, 🔵 proxy da conexão, sempre mostrando o IP -- **Troca de Token OAuth via Proxy** — O fluxo OAuth também passa pelo proxy, resolvendo `unsupported_country_region_territory` -- **Teste de Conexão via Proxy** — Testes usam o proxy configurado (sem bypass direto) -- **Suporte SOCKS5** — Suporte completo a proxy SOCKS5 para roteamento de saída -- **Spoofing de Impressão TLS** — Fingerprint TLS estilo navegador via `wreq-js` para contornar detecção de bot +- **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
-` prefix
-- **Combos Apenas Gratuitos** — Cadeia `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/mês com zero downtime
-- **Créditos Gratuitos NVIDIA NIM** — 1000 créditos free integrados
-- **Estratégia Cost Optimized** — Estratégia que escolhe automaticamente o provedor mais barato disponível
+- **Free-Only Combos** — Chain `gc/gemini-3-flash → 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
🆓 4. "Quero usar IA para programar, mas não tenho dinheiro"
+🆓 4. "I want to use AI for coding but I have no money"
-Nem todo mundo pode pagar $20–200/mês em assinaturas de IA. Estudantes, devs de países emergentes, hobistas e freelancers precisam de acesso a modelos de qualidade com custo zero. +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. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- **Provedores Gratuitos nativos** — Suporte nativo a provedores 100% free: iFlow (8 modelos ilimitados), Qwen (3 ilimitados), Kiro (Claude grátis), Gemini CLI (180K/mês grátis) +- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free) - **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/
-
🔒 5. "Preciso proteger meu gateway de IA contra acesso não autorizado"
+🔒 5. "I need to protect my AI gateway from unauthorized access"
-Ao expor um gateway de IA na rede (LAN, VPS, Docker), qualquer pessoa com o endereço pode consumir tokens/cota do desenvolvedor. Sem proteção, as APIs ficam vulneráveis a uso indevido, prompt injection e abuso. +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. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- **Gestão de API Keys** — Geração, rotação e escopo por provedor com página dedicada em `/dashboard/api-manager` -- **Permissões por Modelo** — Restringe chaves a modelos específicos (`openai/*`, padrões wildcard), com toggle Allow All/Restrict -- **Proteção de Endpoint de API** — Exige chave para `/v1/models` e bloqueia provedores específicos da listagem -- **Auth Guard + CSRF Protection** — Todas as rotas do dashboard protegidas com middleware `withAuth` + tokens CSRF -- **Rate Limiter** — Limite por IP com janelas configuráveis -- **Filtragem por IP** — Allowlist/blocklist para controle de acesso -- **Proteção contra Prompt Injection** — Sanitização contra padrões maliciosos -- **Criptografia AES-256-GCM** — Credenciais criptografadas em repouso +- **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. "Meu provedor caiu e eu perdi meu fluxo de programação"
+🛑 6. "My provider went down and I lost my coding flow"
-Provedores de IA podem ficar instáveis, retornar erro 5xx ou atingir limites temporários de taxa. Se o dev depende de um único provedor, ele é interrompido. Sem circuit breaker, retries repetidos podem derrubar a aplicação. +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. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- **Circuit Breaker por modelo** — Abre/fecha automaticamente com limiares e cooldown configuráveis (Closed/Open/Half-Open) -- **Exponential Backoff** — Atrasos progressivos de retry -- **Anti-Thundering Herd** — Proteção com mutex + semáforo contra tempestade de retries concorrentes -- **Cadeias de Fallback em Combo** — Se o primário falhar, avança automaticamente na cadeia sem intervenção -- **Circuit Breaker de Combo** — Desativa automaticamente provedores com falha dentro da cadeia -- **Health Dashboard** — Monitoramento de uptime, estados de breaker, lockouts, estatísticas de cache e latência p50/p95/p99 +- **Circuit Breaker per-model** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks +- **Exponential Backoff** — Progressive retry delays +- **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 +- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain +- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
-
🔧 7. "Configurar cada ferramenta de IA é tedioso e repetitivo"
+🔧 7. "Configuring each AI tool is tedious and repetitive"
-Desenvolvedores usam Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Cada ferramenta pede configuração diferente (endpoint, chave, modelo). Reconfigurar ao trocar de provedor ou modelo é perda de tempo. +Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- **Dashboard de Ferramentas CLI** — Página dedicada com setup em 1 clique para Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity e Cline -- **Gerador de Config do GitHub Copilot** — Gera `chatLanguageModels.json` para VS Code com seleção em lote de modelos -- **Onboarding Wizard** — Fluxo guiado de 4 etapas para novos usuários -- **Um endpoint para todos os modelos** — Configure `http://localhost:20128/v1` uma vez e acesse 36+ provedores +- **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 67+ providers
-
🔑 8. "Gerenciar tokens OAuth de múltiplos provedores é um caos"
+🔑 8. "Managing OAuth tokens from multiple providers is hell"
-Claude Code, Codex, Gemini CLI e Copilot usam OAuth 2.0 com tokens que expiram. Devs precisam reautenticar o tempo todo e lidar com erros como `client_secret is missing`, `redirect_uri_mismatch` e falhas em servidores remotos. OAuth em LAN/VPS é especialmente problemático. +Claude Code, Codex, Gemini CLI, 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. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- **Auto Token Refresh** — Tokens OAuth renovados em background antes da expiração -- **OAuth 2.0 (PKCE) nativo** — Fluxo automático para Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen e iFlow -- **OAuth Multi-Conta** — Múltiplas contas por provedor via extração de JWT/ID token -- **Correções OAuth LAN/Remoto** — Detecção de IP privado para `redirect_uri` + modo manual de URL para servidores remotos -- **OAuth atrás de Nginx** — Usa `window.location.origin` para compatibilidade com reverse proxy -- **Guia de OAuth Remoto** — Passo a passo para credenciais Google Cloud em VPS/Docker +- **Auto Token Refresh** — OAuth tokens refresh in background before expiration +- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow +- **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. "Não sei quanto estou gastando nem onde"
+📊 9. "I don't know how much I'm spending or where"
-Desenvolvedores usam vários provedores pagos, mas não têm visão unificada de gastos. Cada provedor tem seu dashboard de billing, sem consolidação. Custos inesperados podem se acumular. +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. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- **Dashboard de Analytics de Custo** — Rastreamento de custo por token e gestão de orçamento por provedor -- **Limites de Orçamento por Tier** — Teto de gasto por tier que aciona fallback automático -- **Configuração de Preço por Modelo** — Preços configuráveis por modelo -- **Estatísticas de Uso por API Key** — Contagem de requests e timestamp de último uso por chave -- **Analytics Dashboard** — Cards, gráfico de uso por modelo e tabela de provedores com taxa de sucesso e latência +- **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. "Não consigo diagnosticar erros e problemas nas chamadas de IA"
+🐛 10. "I can't diagnose errors and problems in AI calls"
-Quando uma chamada falha, o dev não sabe se foi rate limit, token expirado, formato incorreto ou erro do provedor. Logs ficam fragmentados em terminais diferentes. Sem observabilidade, debug vira tentativa e erro. +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. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- **Dashboard de Logs Unificado** — 4 abas: Request Logs, Proxy Logs, Audit Logs e Console -- **Visualizador de Console** — Viewer em tempo real estilo terminal com níveis por cor, auto-scroll, busca e filtros -- **Proxy Logs em SQLite** — Logs persistentes que sobrevivem a reinícios do servidor -- **Playground do Tradutor** — 4 modos de debug: Playground (tradução), Chat Tester (round-trip), Test Bench (lote), Live Monitor (tempo real) -- **Telemetria de Request** — Latência p50/p95/p99 + rastreamento por X-Request-Id -- **Logging em Arquivo com Rotação** — Interceptador de console grava tudo em JSON com rotação por tamanho +- **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 Proxy Logs** — Persistent logs that survive server restarts +- **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 Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation +- **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. "Implantar e manter o gateway é complexo"
+🏗️ 11. "Deploying and maintaining the gateway is complex"
-Instalar, configurar e manter um proxy de IA em ambientes diferentes (local, VPS, Docker, cloud) exige muito trabalho. Problemas como caminhos hardcoded, `EACCES` em diretórios, conflito de portas e build cross-platform aumentam a fricção. +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. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- **Instalação global via npm** — `npm install -g omniroute && omniroute` e pronto -- **Docker Multi-Platform** — AMD64 + ARM64 nativo (Apple Silicon, AWS Graviton, Raspberry Pi) -- **Perfis Docker Compose** — `base` (sem ferramentas CLI) e `cli` (com Claude Code, Codex, OpenClaw) -- **App Desktop Electron** — App nativo para Windows/macOS/Linux com bandeja, auto-start e modo offline -- **Modo de Porta Separada** — API e Dashboard em portas distintas para cenários avançados (reverse proxy, rede de containers) -- **Cloud Sync** — Sincronização de configuração entre dispositivos via Cloudflare Workers -- **Backups de DB** — Backup automático, restauração, export e import de todas as configurações +- **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
-
🌍 12. "A interface é só em inglês e meu time não fala inglês"
+🌍 12. "The interface is English-only and my team doesn't speak English"
-Times em países não anglófonos, especialmente na América Latina, Ásia e Europa, sofrem com interfaces só em inglês. A barreira de idioma reduz adoção e aumenta erros de configuração. +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. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- **i18n do Dashboard — 30 idiomas** — Mais de 500 chaves traduzidas, incluindo árabe, búlgaro, dinamarquês, alemão, espanhol, finlandês, francês, hebraico, hindi, húngaro, indonésio, italiano, japonês, coreano, malaio, holandês, norueguês, polonês, português (PT/BR), romeno, russo, eslovaco, sueco, tailandês, ucraniano, vietnamita, chinês, filipino e inglês -- **Suporte RTL** — Suporte right-to-left para árabe e hebraico -- **READMEs multilíngues** — 30 traduções completas de documentação -- **Seletor de Idioma** — Ícone de globo no header para troca em tempo real +- **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. "Preciso de mais do que chat: embeddings, imagens, áudio"
+🔄 13. "I need more than chat — I need embeddings, images, audio"
-IA não é só chat completion. Devs precisam gerar imagens, transcrever áudio, criar embeddings para RAG, reranquear documentos e moderar conteúdo. Cada API tem endpoint e formato diferentes. +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. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- **Embeddings** — `/v1/embeddings` com 6 provedores e 9+ modelos -- **Geração de Imagem** — `/v1/images/generations` com 10 provedores e 20+ modelos (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI) -- **Texto para Vídeo** — `/v1/videos/generations` com ComfyUI (AnimateDiff, SVD) e SD WebUI -- **Texto para Música** — `/v1/music/generations` com ComfyUI (Stable Audio Open, MusicGen) -- **Transcrição de Áudio** — `/v1/audio/transcriptions` com Whisper + Nvidia NIM, HuggingFace e Qwen3 -- **Texto para Fala (TTS)** — `/v1/audio/speech` com ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise e Qwen3 -- **Moderações** — `/v1/moderations` para checagens de segurança de conteúdo -- **Reranking** — `/v1/rerank` para relevância de documentos -- **Responses API** — Suporte completo a `/v1/responses` para Codex +- **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. "Não tenho como testar e comparar qualidade entre modelos"
+🧪 14. "I have no way to test and compare quality across models"
-Desenvolvedores querem saber qual modelo é melhor para cada caso de uso (código, tradução, raciocínio), mas comparar manualmente é lento. Não existem ferramentas integradas de avaliação na maioria das stacks. +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. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- **Avaliações de LLM** — Golden set com 10 casos pré-carregados cobrindo saudação, matemática, geografia, geração de código, conformidade JSON, tradução, markdown e recusa de conteúdo inseguro -- **4 Estratégias de Match** — `exact`, `contains`, `regex`, `custom` (função JS) -- **Test Bench do Playground do Tradutor** — Testes em lote com múltiplas entradas/saídas esperadas e comparação entre provedores -- **Chat Tester** — Round-trip completo com renderização visual da resposta -- **Live Monitor** — Stream em tempo real de todas as requisições que passam pelo proxy +- **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. "Preciso escalar sem perder performance"
+📈 15. "I need to scale without losing performance"
-À medida que o volume cresce, sem cache as mesmas perguntas geram custos duplicados. Sem idempotência, requisições duplicadas desperdiçam processamento. Também é necessário respeitar rate limits por provedor. +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. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- **Cache Semântico** — Cache em duas camadas (assinatura + semântico) para reduzir custo e latência -- **Idempotência de Request** — Janela de deduplicação de 5s para requisições idênticas -- **Detecção de Rate Limit** — Rastreamento por provedor de RPM, intervalo mínimo e concorrência máxima -- **Rate Limits Editáveis** — Padrões configuráveis em Settings → Resilience com persistência -- **Cache de Validação de API Key** — Cache em 3 camadas para performance em produção -- **Health Dashboard com Telemetria** — Latência p50/p95/p99, estatísticas de cache e uptime +- **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 +- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence +- **API Key Validation Cache** — 3-tier cache for production performance +- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
-
🤖 16. "Quero controlar o comportamento dos modelos globalmente"
+🤖 16. "I want to control model behavior globally"
-Desenvolvedores podem querer todas as respostas em um idioma específico, com tom específico ou com limite de tokens de raciocínio. Configurar isso em cada ferramenta/requisição é impraticável. +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. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- **Injeção de System Prompt** — Prompt global aplicado a todas as requisições -- **Validação de Thinking Budget** — Controle de alocação de tokens de raciocínio por requisição (passthrough, auto, custom, adaptive) -- **6 Estratégias de Roteamento** — Estratégias globais que definem como as requisições são distribuídas -- **Wildcard Router** — Padrões `provider/*` roteiam dinamicamente para qualquer provedor -- **Toggle de Combo** — Ativa/desativa combos diretamente no dashboard -- **Toggle de Provedor** — Ativa/desativa todas as conexões de um provedor com um clique -- **Provedores Bloqueados** — Exclui provedores específicos da listagem de `/v1/models` +- **System Prompt Injection** — Global prompt applied to all requests +- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive) +- **6 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 +- **Provider Toggle** — Enable/disable all connections for a provider with one click +- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
-
🧰 17. "Preciso de ferramentas MCP como capacidades de primeira classe do produto"
+🧰 17. "I need MCP tools as first-class product capabilities"
-Muitos gateways de IA expõem MCP apenas como detalhe de implementação oculto. Times precisam de uma camada operacional visível e gerenciável. +Many AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- MCP aparece no menu do dashboard e na aba de protocolos em Endpoint -- Página dedicada de gestão MCP com processo, ferramentas, escopos e auditoria -- Quick-start embutido para `omniroute --mcp` e onboarding de clientes +- 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. "Preciso de orquestração A2A com caminhos síncronos + streaming"
+🧠 18. "I need A2A orchestration with sync + stream task paths"
-Fluxos de agentes precisam de respostas diretas e também de execuções longas com streaming e controle de ciclo de vida. +Agent workflows need both direct replies and long-running streamed execution with lifecycle control. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- Endpoint A2A JSON-RPC (`POST /a2a`) com `message/send` e `message/stream` -- Streaming SSE com propagação de estado terminal -- APIs de ciclo de vida de tarefas para `tasks/get` e `tasks/cancel` +- 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. "Preciso de saúde real do processo MCP, não status estimado"
+🛰️ 19. "I need real MCP process health, not guessed status"
-Times operacionais precisam saber se o MCP está realmente ativo, não apenas se uma API está respondendo. +Operational teams need to know if MCP is actually alive, not just whether an API is reachable. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- Arquivo de heartbeat em runtime com PID, timestamps, transporte, quantidade de ferramentas e modo de escopo -- API de status MCP combinando heartbeat + atividade recente -- Cards de status na UI para processo/uptime/frescor do heartbeat +- 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. "Preciso de execução auditável das ferramentas MCP"
+📋 20. "I need auditable MCP tool execution"
-Quando ferramentas alteram configuração ou disparam ações operacionais, os times precisam de rastreabilidade forense. +When tools mutate config or trigger ops actions, teams need forensic traceability. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- Auditoria de chamadas MCP baseada em SQLite -- Filtros por ferramenta, sucesso/falha, chave de API e paginação -- Tabela de auditoria no dashboard + endpoints de métricas para automação +- 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. "Preciso de permissões MCP por escopo para cada integração"
+🔐 21. "I need scoped MCP permissions per integration"
-Clientes diferentes devem operar com privilégio mínimo por categoria de ferramenta. +Different clients should have least-privilege access to tool categories. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- 9 escopos MCP granulares para controle de acesso às ferramentas -- Aplicação de escopo e visibilidade na UI de gestão MCP -- Postura segura por padrão para operações sensíveis +- 9 granular MCP scopes for controlled tool access +- Scope enforcement and visibility in MCP management UI +- Safe default posture for operational tooling
-
⚙️ 22. "Preciso de controles operacionais sem redeploy"
+⚙️ 22. "I need operational controls without redeploying"
-Times precisam de mudanças rápidas em runtime durante incidentes e picos de custo. +Teams need quick runtime changes during incidents or cost events. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- Troca de ativação de combo direto no dashboard de MCP -- Aplicação de perfis de resiliência via pacotes de política prontos -- Reset de circuit breaker no mesmo painel operacional +- Switch combo activation directly from MCP dashboard +- Apply resilience profiles from pre-defined policy packs +- Reset circuit breaker state from the same operations panel
-
🔄 23. "Preciso de visibilidade ao vivo do ciclo de vida A2A e cancelamento"
+🔄 23. "I need live A2A task lifecycle visibility and cancellation"
-Sem visibilidade de lifecycle, incidentes de tarefas ficam difíceis de investigar e corrigir. +Without lifecycle visibility, task incidents become hard to triage. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- Listagem/filtragem de tarefas por estado/skill com paginação -- Drill-down de metadados, eventos e artefatos da tarefa -- Endpoint de cancelamento + ação de UI com confirmação +- 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. "Preciso de métricas de streams ativos para carga A2A"
+🌊 24. "I need active stream metrics for A2A load"
-Fluxos em streaming exigem visão operacional de concorrência e conexões ativas. +Streaming workflows require operational insight into concurrency and live connections. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- Contadores de streams ativos integrados ao status A2A -- Timestamp da última tarefa e contagens por estado -- Cards no dashboard A2A para monitoramento operacional em tempo real +- Active stream counters integrated into A2A status +- Last task timestamp and per-state counts +- A2A dashboard cards for real-time ops monitoring
-
🪪 25. "Preciso de descoberta padrão de agente para clientes"
+🪪 25. "I need standard agent discovery for clients"
-Clientes externos e orquestradores precisam de metadados legíveis por máquina para onboarding automático. +External clients and orchestrators need machine-readable metadata for onboarding. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- Agent Card exposto em `/.well-known/agent.json` -- Capacidades e skills exibidas na UI de gestão -- API de status A2A inclui metadados de descoberta para automação +- Agent Card exposed at `/.well-known/agent.json` +- Capabilities and skills shown in management UI +- A2A status API includes discovery metadata for automation
-
🧭 26. "Preciso de descobribilidade de protocolos na experiência do produto"
+🧭 26. "I need protocol discoverability in the product UX"
-Se os usuários não encontram superfícies de protocolo, adoção e qualidade de suporte caem. +If users cannot discover protocol surfaces, adoption and support quality drop. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- Entradas MCP e A2A na sidebar -- Aba Protocolos em Endpoint com quick-start e status -- Links do overview para dashboards dedicados de gestão +- 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. "Preciso de validação end-to-end de protocolo com clientes reais"
+🧪 27. "I need end-to-end protocol validation with real clients"
-Testes mockados não bastam para validar compatibilidade de protocolo antes do release. +Mock tests are not enough to validate protocol compatibility before release. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- Suíte E2E que sobe a aplicação e usa transporte real do SDK MCP -- Testes de cliente A2A para discovery, send, stream, get e cancel -- Cross-check das validações com APIs de auditoria MCP e tarefas A2A +- 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. "Preciso de observabilidade unificada em todas as interfaces"
+📡 28. "I need unified observability across all interfaces"
-Separar observabilidade por protocolo cria pontos cegos e aumenta o MTTR. +Splitting observability by protocol creates blind spots and longer MTTR. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- Dashboards/logs/analytics unificados no mesmo produto -- Saúde + auditoria + telemetria de requisição em OpenAI, MCP e A2A -- APIs operacionais de status para automação +- Unified dashboards/logs/analytics in one product +- Health + audit + request telemetry across OpenAI, MCP, and A2A layers +- Operational APIs for status and automation
-
💼 29. "Preciso de um runtime único para proxy + tools + orquestração de agentes"
+💼 29. "I need one runtime for proxy + tools + agent orchestration"
-Manter vários serviços separados aumenta custo operacional e modos de falha. +Running many separate services increases operational cost and failure modes. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- Proxy OpenAI-compatible, servidor MCP e servidor A2A na mesma stack -- Autenticação, resiliência, armazenamento e observabilidade compartilhados -- Modelo de políticas consistente em todas as superfícies de interação +- 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
-
-### Exemplos de Playbooks (Casos de Uso Integrados)
+### Example Playbooks (Integrated Use Cases)
-**Playbook A: Maximizar assinatura paga + backup barato**
+**Playbook A: Maximize paid subscription + cheap backup**
```txt
Combo: "maximize-claude"
@@ -679,11 +690,11 @@ Combo: "maximize-claude"
2. glm/glm-4.7
3. if/kimi-k2-thinking
-Custo mensal: $20 + pequeno gasto de backup
-Resultado: qualidade maior, interrupção quase zero
+Monthly cost: $20 + small backup spend
+Outcome: higher quality, near-zero interruption
```
-**Playbook B: Stack de programação com custo zero**
+**Playbook B: Zero-cost coding stack**
```txt
Combo: "free-forever"
@@ -691,58 +702,149 @@ Combo: "free-forever"
2. if/kimi-k2-thinking
3. qw/qwen3-coder-plus
-Custo mensal: $0
-Resultado: fluxo de coding gratuito e estável
+Monthly cost: $0
+Outcome: stable free coding workflow
```
-## ⚡ Início Rápido
+**Playbook C: 24/7 always-on fallback chain**
-**1. Instale globalmente:**
+```txt
+Combo: "always-on"
+ 1. cc/claude-opus-4-6
+ 2. cx/gpt-5.2-codex
+ 3. glm/glm-4.7
+ 4. minimax/MiniMax-M2.1
+ 5. if/kimi-k2-thinking
+
+Outcome: deep fallback depth for deadline-critical workloads
+```
+
+**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
+```
+
+---
+
+## 🆓 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 **iFlow** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |
+| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |
+| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |
+| 5 | `/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).
+
+## Início Rápido
+
+### 1) Install and run
```bash
npm install -g omniroute
omniroute
```
-🎉 Dashboard abre em `http://localhost:20128`
+> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:
+>
+> ```bash
+> pnpm install -g omniroute
+> pnpm approve-builds -g # Select all packages → approve
+> omniroute
+> ```
-| Comando | Descrição |
-| ----------------------- | ------------------------------------- |
-| `omniroute` | Iniciar servidor (porta padrão 20128) |
-| `omniroute --port 3000` | Usar porta personalizada |
-| `omniroute --no-open` | Não abrir navegador automaticamente |
-| `omniroute --help` | Mostrar ajuda |
+Dashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.
-**2. Conecte um provedor GRATUITO:**
+| 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 |
-Dashboard → Provedores → Conectar **Claude Code** ou **Antigravity** → Login OAuth → Pronto!
+Optional split-port mode:
-**3. Use na sua ferramenta CLI:**
-
-```
-Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Configurações:
- Endpoint: http://localhost:20128/v1
- API Key: [copie do dashboard]
- Model: if/kimi-k2-thinking
+```bash
+PORT=20128 DASHBOARD_PORT=20129 omniroute
+# API: http://localhost:20128/v1
+# Dashboard: http://localhost:20129
```
-**Pronto!** Comece a programar com modelos de IA GRATUITOS.
+### 2) Connect providers and create your API key
-**Alternativa — rodar a partir do código-fonte:**
+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
+
+```txt
+Base URL: http://localhost:20128/v1
+API Key: [copy from Endpoint page]
+Model: if/kimi-k2-thinking (or any provider/model prefix)
+```
+
+Works with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.
+
+### 4) Enable and validate protocols (v2.0)
+
+**MCP (for tool-driven operations):**
+
+```bash
+omniroute --mcp
+```
+
+Then connect your MCP client over `stdio` and test tools like:
+
+- `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 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
+PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev
```
---
## 🐳 Docker
-OmniRoute está disponível como imagem Docker pública no [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
+OmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
-**Execução rápida:**
+**Quick run:**
```bash
docker run -d \
@@ -753,10 +855,10 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Com arquivo de ambiente:**
+**With environment file:**
```bash
-# Copie e edite o .env primeiro
+# Copy and edit .env first
cp .env.example .env
docker run -d \
@@ -768,348 +870,627 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Usando Docker Compose:**
+**Using Docker Compose:**
```bash
-# Perfil base (sem ferramentas CLI)
+# Base profile (no CLI tools)
docker compose --profile base up -d
-# Perfil CLI (Claude Code, Codex, OpenClaw integrados)
+# CLI profile (Claude Code, Codex, OpenClaw built-in)
docker compose --profile cli up -d
```
-| Imagem | Tag | Tamanho | Descrição |
-| ------------------------ | -------- | ------- | --------------------- |
-| `diegosouzapw/omniroute` | `latest` | ~250MB | Última versão estável |
-| `diegosouzapw/omniroute` | `1.0.6` | ~250MB | Versão atual |
+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.
+- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.
+- 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` | `1.0.3` | ~250MB | Current version |
---
----
+## 🖥️ Desktop App — Offline & Always-On
-## 🖥️
+> 🆕 **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.
-> 🆕 **NOVO!** O OmniRoute agora está disponível como **aplicativo desktop nativo** para Windows, macOS e Linux.
+Run OmniRoute as a standalone desktop app — no terminal, no browser, no internet required for local models. The Electron-based app includes:
-Execute o OmniRoute como um aplicativo desktop autônomo — sem terminal, sem navegador, sem internet necessária para modelos locais. O app baseado em Electron inclui:
-
-- 🖥️ **Janela Nativa** — Janela dedicada com integração à bandeja do sistema
-- 🔄 **Iniciar Automaticamente** — Inicie o OmniRoute ao fazer login no sistema
-- 🔔 **Notificações Nativas** — Receba alertas sobre esgotamento de cota ou problemas
-- ⚡ **Instalação com Um Clique** — NSIS (Windows), DMG (macOS), AppImage (Linux)
-- 🌐 **Modo Offline** — Funciona totalmente offline com servidor embarcado
+- 🖥️ **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
### Início Rápido
```bash
-# Modo desenvolvimento
+# Development mode
npm run electron:dev
-# Compilar para sua plataforma
-npm run electron:build # Plataforma atual
+# 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)
```
-### Bandeja do Sistema
+### System Tray
-Quando minimizado, o OmniRoute fica na bandeja do sistema com ações rápidas:
+When minimized, OmniRoute lives in your system tray with quick actions:
-- Abrir dashboard
-- Alterar porta do servidor
-- Sair do aplicativo
+- Open dashboard
+- Change server port
+- Quit application
-📖 Documentação completa: [`electron/README.md`](electron/README.md)
+📖 Full documentation: [`electron/README.md`](electron/README.md)
---
-## 💰 Preços Resumidos
+## 💰 Pricing at a Glance
-| Tier | Provedor | Custo | Reset de Cota | Melhor Para |
-| ----------------- | ----------------- | ---------------------------- | ----------------- | ------------------------------ |
-| **💳 ASSINATURA** | Claude Code (Pro) | $20/mês | 5h + semanal | Já é assinante |
-| | Codex (Plus/Pro) | $20-200/mês | 5h + semanal | Usuários OpenAI |
-| | Gemini CLI | **GRATUITO** | 180K/mês + 1K/dia | Todos! |
-| | GitHub Copilot | $10-19/mês | Mensal | Usuários GitHub |
-| **🔑 API KEY** | NVIDIA NIM | **GRATUITO** (1000 créditos) | Único | Testes gratuitos |
-| | DeepSeek | Por uso | Nenhum | Melhor preço/qualidade |
-| | Groq | Tier gratuito + pago | Limitado | Inferência ultra-rápida |
-| | xAI (Grok) | Por uso | Nenhum | Modelos Grok |
-| | Mistral | Tier gratuito + pago | Limitado | IA Europeia |
-| | OpenRouter | Por uso | Nenhum | 100+ modelos |
-| **💰 BARATO** | GLM-4.7 | $0.6/1M | Diário 10h | Backup econômico |
-| | MiniMax M2.1 | $0.2/1M | Rotativo 5h | Opção mais barata |
-| | Kimi K2 | $9/mês fixo | 10M tokens/mês | Custo previsível |
-| **🆓 GRATUITO** | iFlow | $0 | Ilimitado | 8 modelos gratuitos |
-| | Qwen | $0 | Ilimitado | 3 modelos gratuitos |
-| | Kiro | $0 | Ilimitado | Claude gratuito |
-| | LongCat 🆕 | **$0** (50M tok/dia 🔥) | 1 req/s | Maior cota grátis do mundo |
-| | Pollinations 🆕 | **$0** (sem chave API) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama |
-| | Cloudflare AI 🆕 | **$0** (10K Neurons/dia) | ~150 resp/dia | 50+ modelos, edge global |
-| | Scaleway AI 🆕 | **$0** (1M tokens total) | Limitado por taxa | EU/GDPR, Qwen3 235B, Llama 70B |
+| 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 |
+| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |
+| | 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** | iFlow | **$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 |
-**💡 Dica Pro:** Comece com Gemini CLI (180K grátis/mês) + iFlow (ilimitado grátis) = $0 de custo!
+> 🆕 **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
+iFlow (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.
---
-## 💡 Funcionalidades Principais
+---
-### 🧭 Gestão MCP + A2A (Camada Operacional)
+## 🆓 Free Models — What You Actually Get
-A maioria dos gateways de IA expõe MCP/A2A apenas como endpoints “escondidos”. O OmniRoute traz operação de primeira classe para os dois protocolos:
+> 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.
-- **Descoberta na interface** — Entradas `MCP` e `A2A` na sidebar e aba `Protocolos` na página de Endpoint com quick-start e cartões de status.
-- **Painel operacional MCP** (`/dashboard/mcp`) — Status real do processo por heartbeat, inventário de ferramentas/scopes, auditoria com filtros e controles operacionais (trocar combo, aplicar perfil de resiliência, resetar breakers).
-- **Painel operacional A2A** (`/dashboard/a2a`) — Visão do agent card, ciclo de vida de tarefas por estado, contagem de streams ativos, drill-down/cancelamento de tasks e smoke tests de `message/send` e `message/stream`.
-- **APIs de monitoramento** — Endpoints `/api/mcp/*` e `/api/a2a/*` para status, tasks, auditoria e automações externas.
+### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)
-Por que isso é relevante:
+| 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 |
-- **Um runtime, três papéis**: router/proxy OpenAI-compatible + servidor de ferramentas MCP + servidor agente A2A.
-- **Governança unificada**: autenticação, auditoria e controles de resiliência compartilhados.
-- **Operação confiável**: times conseguem validar, monitorar e depurar comportamento dos protocolos sem sair do produto.
+### 🟢 IFLOW MODELS (Free OAuth — No Credit Card)
-### 🧠 Roteamento e Inteligência
+| 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 |
-| Funcionalidade | O que Faz |
-| ----------------------------------------- | ---------------------------------------------------------------------------------- |
-| 🎯 **Fallback Inteligente 4 Tiers** | Auto-roteamento: Assinatura → API Key → Barato → Gratuito |
-| 📊 **Rastreamento de Cota em Tempo Real** | Contagem de tokens ao vivo + countdown de reset por provedor |
-| 🔄 **Tradução de Formato** | OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro transparente |
-| 👥 **Suporte Multi-Conta** | Múltiplas contas por provedor com seleção inteligente |
-| 🔄 **Renovação Automática de Token** | Tokens OAuth renovam automaticamente com retry |
-| 🎨 **Combos Personalizados** | 6 estratégias: fill-first, round-robin, p2c, random, least-used, cost-optimized |
-| 🧩 **Modelos Personalizados** | Adicione qualquer ID de modelo a qualquer provedor |
-| 🌐 **Roteador Wildcard** | Roteie padrões `provider/*` para qualquer provedor dinamicamente |
-| 🧠 **Budget de Raciocínio** | Modos passthrough, auto, custom e adaptativo para modelos de raciocínio |
-| � **Aliases de Modelo** | Redireciona IDs de modelos depreciados para substitutos atuais (built-in + custom) |
-| ⚡ **Degradação em Background** | Redireciona tarefas em background (títulos, resumos) para modelos mais baratos |
-| �💬 **Injeção de System Prompt** | System prompt global aplicado em todas as requisições |
-| 📄 **API Responses** | Suporte completo à API Responses da OpenAI (`/v1/responses`) para Codex |
+### 🟡 QWEN MODELS (Device Code Auth)
-### 🎵 APIs Multi-Modal
+| 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) |
-| Funcionalidade | O que Faz |
-| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 🖼️ **Geração de Imagem** | `/v1/images/generations` — 10 provedores, 20+ modelos (cloud + local) |
-| 📐 **Embeddings** | `/v1/embeddings` — 6 provedores, 9+ modelos |
-| 🎤 **Transcrição de Áudio** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |
-| 🔊 **Texto para Fala** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) |
-| 🎬 **Geração de Vídeo** | `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD), SD WebUI |
-| 🎵 **Geração de Música** | `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen) |
-| 🛡️ **Moderações** | `/v1/moderations` — Verificações de segurança |
-| 🔀 **Reranking** | `/v1/rerank` — Reranking de relevância de documentos |
+### 🟣 GEMINI CLI (Google OAuth)
-### 🛡️ Resiliência e Segurança
+| Model | Prefix | Limit | Rate Limit |
+| ------------------------ | ------ | --------------------------- | ------------- |
+| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |
+| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |
-| Funcionalidade | O que Faz |
-| ----------------------------------- | ----------------------------------------------------------------------------- |
-| 🔌 **Circuit Breaker** | Trip/recover por modelo com limites configuráveis |
-| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |
-| 🛡️ **Anti-Thundering Herd** | Mutex + semáforo rate-limit para provedores com API key |
-| 🧠 **Cache Semântico** | Cache de duas camadas (assinatura + semântico) reduz custo e latência |
-| ⚡ **Idempotência de Requisição** | Janela de dedup de 5s para requisições duplicadas |
-| 🔒 **Spoofing de Fingerprint TLS** | Bypass de detecção de bot via TLS com wreq-js |
-| 🌐 **Filtragem de IP** | Allowlist/blocklist para controle de acesso à API |
-| 📊 **Rate Limits Editáveis** | RPM, gap mínimo e concorrência máxima configuráveis |
-| 💾 **Persistência de Rate Limits** | Limites aprendidos persistem via SQLite com debounce de 60s + 24h de validade |
-| 🔄 **Resiliência de Token Refresh** | Circuit breaker por provedor (5 falhas→30min) + timeout de 30s por tentativa |
-| 🛡 **Proteção de Endpoint API** | Gateway de Auth + bloqueio de provedores para o endpoint `/models` |
-| 🔒 **Visibilidade de Proxy** | Badges coloridos: 🟢 global, 🟡 provedor, 🔵 por-conexão com exibição de IP |
-| 🌐 **Proxy em 3 Níveis** | Configure proxies em nível global, por provedor ou por conexão |
+### ⚫ NVIDIA NIM (Free API Key — build.nvidia.com)
-### 📊 Observabilidade e Analytics
+| Tier | Daily Limit | Rate Limit | Notes |
+| ---------- | ------------ | ----------- | ------------------------------------------------------ |
+| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 |
-| Funcionalidade | O que Faz |
-| -------------------------------- | --------------------------------------------------------------------- |
-| 📝 **Logs de Requisição** | Modo debug com logs completos de request/response |
-| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |
-| 💾 **Logs SQLite** | Logs de proxy persistentes sobrevivem a reinicializações |
-| 📊 **Dashboard de Analytics** | Recharts: cards de estatísticas, gráfico de uso, tabela de provedores |
-| 📈 **Rastreamento de Progresso** | Eventos de progresso SSE opt-in para streaming |
-| 🧪 **Avaliações de LLM** | Testes com conjunto golden e 4 estratégias de match |
-| 🔍 **Telemetria de Requisição** | Agregação de latência p50/p95/p99 + rastreamento X-Request-Id |
-| 📋 **Logs + Cotas** | Páginas dedicadas para navegação de logs e rastreamento de cotas |
-| 🏥 **Dashboard de Saúde** | Uptime, estados de circuit breaker, lockouts, stats de cache |
-| 💰 **Rastreamento de Custo** | Gestão de orçamento + configuração de preços por modelo |
+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`
-### ☁️ Deploy e Sincronização
+### ⚪ CEREBRAS (Free API Key — inference.cerebras.ai)
-| Funcionalidade | O que Faz |
-| --------------------------------- | --------------------------------------------------------------------------------- |
-| 💾 **Cloud Sync** | Sincronize configurações entre dispositivos via Cloudflare Workers |
-| 🌐 **Deploy em Qualquer Lugar** | Localhost, VPS, Docker, Cloudflare Workers |
-| 🔑 **Gestão de API Keys** | Gere, rotacione e defina escopo de API keys por provedor |
-| 🧙 **Assistente de Configuração** | Setup guiado em 4 etapas para novos usuários |
-| 🔧 **Dashboard CLI Tools** | Configuração em um clique para Claude, Codex, Cline, OpenClaw, Kilo, Antigravity |
-| 🔄 **Backups de DB** | Backup, restauração, exportação e importação automática de todas as configurações |
-| 🌐 **Internacionalização** | i18n completo com next-intl — suporte a 30 idiomas com RTL |
-| 🌍 **Seletor de Idioma** | Ícone de globo no cabeçalho para troca entre 30 idiomas em tempo real |
-| 🧹 **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 |
-| 📂 **Diretório de Dados Custom** | Variável `DATA_DIR` para sobrescrever o caminho padrão `~/.omniroute` |
+| 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
+> iFlow (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 v2.0 is built as an operational platform, not just a relay proxy.
+
+### 🆕 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 Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |
+| 🤖 **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 (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) |
+| 🤝 **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** | 9 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 combo, apply resilience profiles, reset breakers from one control surface |
+
+### 🧠 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** | 6 balancing strategies + fallback chain control |
+| 🌐 **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) |
+| 💬 **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 |
+| ----------------------------------- | -------------------------------------------------------------------------------------- |
+| 🔌 **Circuit Breakers** | Per-model trip/recover with threshold controls |
+| 🎯 **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 |
+| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |
+| 🔑 **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 |
+
+### 📊 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 |
+| 📋 **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 |
+
+### ☁️ Deployment & Platform
+
+| Feature | What It Does |
+| ----------------------------- | --------------------------------------------------------- |
+| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |
+| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |
+| 💾 **Cloud Sync** | Configuration sync via cloud worker |
+| 🔄 **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 |
+
+### Feature Deep Dive
+
+#### Smart fallback with practical cost control
+
+```txt
+Combo: "my-coding-stack"
+ 1. cc/claude-opus-4-6
+ 2. nvidia/llama-3.3-70b
+ 3. glm/glm-4.7
+ 4. if/kimi-k2-thinking
+```
+
+When quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.
+
+#### 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)
+
+#### 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)
🚀 30. "Preciso entregar workflows agênticos sem sprawl de glue code"
+🚀 30. "I need to ship agentic workflows without glue-code sprawl"
-Times perdem velocidade quando precisam costurar múltiplos serviços e scripts ad hoc. +Teams lose velocity when stitching multiple ad-hoc services and scripts. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- Estratégia de endpoint unificada para clientes e agentes -- UIs de gestão de protocolo e fluxos de validação/smoke embutidos -- Base pronta para produção (segurança, logging, resiliência e backup) +- Unified endpoint strategy for clients and agents +- Built-in protocol management UIs and smoke validation paths +- Production-ready foundations (security, logging, resilience, backup)
-
----
+📖 Detalhes das Funcionalidades
+🧩 MCP Setup (Model Context Protocol)
-### 🎯 Fallback Inteligente 4 Tiers +Start MCP transport in stdio mode: -Crie combos com fallback automático: - -``` -Combo: "my-coding-stack" - 1. cc/claude-opus-4-6 (sua assinatura) - 2. nvidia/llama-3.3-70b (API NVIDIA gratuita) - 3. glm/glm-4.7 (backup barato, $0.6/1M) - 4. if/kimi-k2-thinking (fallback gratuito) - -→ Troca automaticamente quando a cota acaba ou erros ocorrem +```bash +omniroute --mcp ``` -### 📊 Rastreamento de Cota em Tempo Real +Recommended validation flow: -- Consumo de tokens por provedor -- Countdown de reset (5 horas, diário, semanal) -- Estimativa de custo para tiers pagos -- Relatórios de gastos mensais +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. -### 🔄 Tradução de Formato +Useful APIs for automation: -Tradução transparente entre formatos: - -- **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **OpenAI Responses** -- Sua ferramenta CLI envia formato OpenAI → OmniRoute traduz → Provedor recebe formato nativo -- Funciona com qualquer ferramenta que suporte endpoints OpenAI customizados - -### 👥 Suporte Multi-Conta - -- Adicione múltiplas contas por provedor -- Round-robin automático ou roteamento por prioridade -- Fallback para próxima conta quando uma atinge a cota - -### 🔄 Renovação Automática de Token - -- Tokens OAuth renovam automaticamente antes de expirar -- Sem necessidade de re-autenticação manual -- Experiência transparente em todos os provedores - -### 🎨 Combos Personalizados - -- Crie combinações ilimitadas de modelos -- 6 estratégias: fill-first, round-robin, power-of-two-choices, random, least-used, cost-optimized -- Compartilhe combos entre dispositivos com Cloud Sync - -### 🏥 Dashboard de Saúde - -- Status do sistema (uptime, versão, uso de memória) -- Estados de circuit breaker por provedor (Closed/Open/Half-Open) -- Status de rate limit e lockouts ativos -- Estatísticas de cache de assinatura -- Telemetria de latência (p50/p95/p99) + cache de prompt -- Reset de saúde com um clique - -### 🔧 Playground do Tradutor - -O OmniRoute inclui um poderoso Playground de Tradução integrado com **4 modos** para debug, teste e monitoramento de traduções de API: - -| Modo | Descrição | -| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **💻 Playground** | Tradução direta entre formatos — cole qualquer corpo de requisição e veja instantaneamente como o OmniRoute traduz entre formatos (OpenAI ↔ Claude ↔ Gemini ↔ Responses API). Inclui templates de exemplo e auto-detecção de formato. | -| **💬 Chat Tester** | Envie requisições reais pelo OmniRoute e veja a viagem completa: sua entrada, a requisição traduzida, a resposta do provedor, e a resposta traduzida de volta. Inestimável para validar roteamento de combos. | -| **🧪 Test Bench** | Modo de teste em lote — defina múltiplos casos de teste com diferentes entradas e saídas esperadas, execute todos de uma vez, e compare resultados entre provedores e modelos. | -| **📱 Live Monitor** | Monitoramento de requisições em tempo real — acompanhe requisições entrando conforme fluem pelo OmniRoute, veja traduções de formato acontecendo ao vivo, e identifique problemas instantaneamente. | - -**Acesso:** Dashboard → Translator (barra lateral) - -### 💾 Cloud Sync - -- Sincronize provedores, combos e configurações entre dispositivos -- Sincronização automática em background -- Armazenamento criptografado seguro +- `GET /api/mcp/status` +- `GET /api/mcp/tools` +- `GET /api/mcp/audit` +- `GET /api/mcp/audit/stats`
+
🤝 A2A Setup (Agent2Agent)
-## 🧪 Avaliações (Evals) +Discover the agent: -OmniRoute inclui um framework de avaliação integrado para testar a qualidade de respostas de LLM contra um conjunto golden. Acesse via **Analytics → Evals** no dashboard. +```bash +curl http://localhost:20128/.well-known/agent.json +``` -### Conjunto Golden Integrado +Send a task: -O "OmniRoute Golden Set" pré-carregado contém 10 casos de teste cobrindo: +```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."}]}}' +``` -- Saudações, matemática, geografia, geração de código -- Conformidade de formato JSON, tradução, markdown -- Recusa de segurança (conteúdo prejudicial), contagem, lógica booleana +Manage lifecycle: -### Estratégias de Avaliação +- `GET /api/a2a/status` +- `GET /api/a2a/tasks` +- `GET /api/a2a/tasks/:id` +- `POST /api/a2a/tasks/:id/cancel` -| Estratégia | Descrição | Exemplo | -| ---------- | ---------------------------------------------- | -------------------------------- | -| `exact` | Saída deve corresponder exatamente | `"4"` | -| `contains` | Saída deve conter substring (case-insensitive) | `"Paris"` | -| `regex` | Saída deve corresponder ao padrão regex | `"1.*2.*3"` | -| `custom` | Função JS customizada retorna true/false | `(output) => output.length > 10` | +Operational UI: ---- +- `/dashboard/a2a` for task/state/stream observability and smoke actions -## 📖 Guia de Configuração +
-
+
+💳 Provedores por Assinatura
+🧪 End-to-end protocol validation
+ +Validate both protocols with real clients: + +```bash +npm run test:protocols:e2e +``` + +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) ```bash -Dashboard → Provedores → Conectar Claude Code -→ Login OAuth → Renovação automática de token -→ Rastreamento de cota 5h + semanal +Dashboard → Providers → Connect Claude Code +→ OAuth login → Auto token refresh +→ 5-hour + weekly quota tracking -Modelos: +Models: cc/claude-opus-4-6 cc/claude-sonnet-4-5-20250929 cc/claude-haiku-4-5-20251001 ``` -**Dica Pro:** Use Opus para tarefas complexas, Sonnet para velocidade. OmniRoute rastreia cota por modelo! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! ### OpenAI Codex (Plus/Pro) ```bash -Dashboard → Provedores → Conectar Codex -→ Login OAuth (porta 1455) -→ Reset 5h + semanal +Dashboard → Providers → Connect Codex +→ OAuth login (port 1455) +→ 5-hour + weekly reset -Modelos: +Models: cx/gpt-5.2-codex cx/gpt-5.1-codex-max ``` -### Gemini CLI (GRATUITO 180K/mês!) +#### 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). + +### Gemini CLI (FREE 180K/month!) ```bash -Dashboard → Provedores → Conectar Gemini CLI +Dashboard → Providers → Connect Gemini CLI → Google OAuth -→ 180K completions/mês + 1K/dia +→ 180K completions/month + 1K/day -Modelos: +Models: gc/gemini-3-flash-preview gc/gemini-2.5-pro ``` -**Melhor Valor:** Tier gratuito enorme! Use antes dos tiers pagos. +**Best Value:** Huge free tier! Use this before paid tiers. ### GitHub Copilot ```bash -Dashboard → Provedores → Conectar GitHub +Dashboard → Providers → Connect GitHub → OAuth via GitHub -→ Reset mensal (1º do mês) +→ Monthly reset (1st of month) -Modelos: +Models: gh/gpt-5 gh/claude-4.5-sonnet gh/gemini-3-pro @@ -1118,95 +1499,95 @@ Modelos:
-
🔑 Provedores por API Key
+🔑 API Key Providers
-### NVIDIA NIM (GRATUITO 1000 créditos!) +### NVIDIA NIM (FREE developer access — 70+ models) -1. Cadastre-se: [build.nvidia.com](https://build.nvidia.com) -2. Obtenha API key gratuita (1000 créditos de inferência incluídos) -3. Dashboard → Adicionar Provedor → NVIDIA NIM: +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` -**Modelos:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, e 50+ mais +**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more -**Dica Pro:** API compatível com OpenAI — funciona perfeitamente com a tradução de formato do OmniRoute! +**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation! ### DeepSeek -1. Cadastre-se: [platform.deepseek.com](https://platform.deepseek.com) -2. Obtenha API key -3. Dashboard → Adicionar Provedor → DeepSeek +1. Sign up: [platform.deepseek.com](https://platform.deepseek.com) +2. Get API key +3. Dashboard → Add Provider → DeepSeek -**Modelos:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` +**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` -### Groq (Tier Gratuito Disponível!) +### Groq (Free Tier Available!) -1. Cadastre-se: [console.groq.com](https://console.groq.com) -2. Obtenha API key (tier gratuito incluído) -3. Dashboard → Adicionar Provedor → Groq +1. Sign up: [console.groq.com](https://console.groq.com) +2. Get API key (free tier included) +3. Dashboard → Add Provider → Groq -**Modelos:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` +**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` -**Dica Pro:** Inferência ultra-rápida — melhor para programação em tempo real! +**Pro Tip:** Ultra-fast inference — best for real-time coding! -### OpenRouter (100+ Modelos) +### OpenRouter (100+ Models) -1. Cadastre-se: [openrouter.ai](https://openrouter.ai) -2. Obtenha API key -3. Dashboard → Adicionar Provedor → OpenRouter +1. Sign up: [openrouter.ai](https://openrouter.ai) +2. Get API key +3. Dashboard → Add Provider → OpenRouter -**Modelos:** Acesse 100+ modelos de todos os principais provedores através de uma única API key. +**Models:** Access 100+ models from all major providers through a single API key.
-
💰 Provedores Baratos (Backup)
+💰 Cheap Providers (Backup)
-### GLM-4.7 (Reset diário, $0.6/1M) +### GLM-4.7 (Daily reset, $0.6/1M) -1. Cadastre-se: [Zhipu AI](https://open.bigmodel.cn/) -2. Obtenha API key do Plano Coding -3. Dashboard → Adicionar API Key: - - Provedor: `glm` +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` -**Dica Pro:** Plano Coding oferece 3× cota a 1/7 do custo! Reset diário 10:00 AM. +**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -### MiniMax M2.1 (Reset 5h, $0.20/1M) +### MiniMax M2.1 (5h reset, $0.20/1M) -1. Cadastre-se: [MiniMax](https://www.minimax.io/) -2. Obtenha API key -3. Dashboard → Adicionar API Key +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key +3. Dashboard → Add API Key **Use:** `minimax/MiniMax-M2.1` -**Dica Pro:** Opção mais barata para contexto longo (1M tokens)! +**Pro Tip:** Cheapest option for long context (1M tokens)! -### Kimi K2 ($9/mês fixo) +### Kimi K2 ($9/month flat) -1. Assine: [Moonshot AI](https://platform.moonshot.ai/) -2. Obtenha API key -3. Dashboard → Adicionar API Key +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key +3. Dashboard → Add API Key **Use:** `kimi/kimi-latest` -**Dica Pro:** $9/mês fixo por 10M tokens = $0.90/1M de custo efetivo! +**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
-
🆓 Provedores GRATUITOS (Backup de Emergência)
+🆓 FREE Providers (Emergency Backup)
-### iFlow (8 modelos GRATUITOS) +### iFlow (5 FREE models via OAuth) ```bash -Dashboard → Conectar iFlow -→ Login OAuth iFlow -→ Uso ilimitado +Dashboard → Connect iFlow +→ iFlow OAuth login +→ Unlimited usage -Modelos: +Models: if/kimi-k2-thinking if/qwen3-coder-plus if/glm-4.7 @@ -1214,125 +1595,78 @@ Modelos: if/deepseek-r1 ``` -### Qwen (3 modelos GRATUITOS) +### Qwen (4 FREE models via Device Code) ```bash -Dashboard → Conectar Qwen -→ Autorização por código de dispositivo -→ Uso ilimitado +Dashboard → Connect Qwen +→ Device code authorization +→ Unlimited usage -Modelos: +Models: qw/qwen3-coder-plus qw/qwen3-coder-flash ``` -### Kiro (Claude GRATUITO) +### Kiro (Claude FREE) ```bash -Dashboard → Conectar Kiro -→ AWS Builder ID ou Google/GitHub -→ Uso ilimitado +Dashboard → Connect Kiro +→ AWS Builder ID or Google/GitHub +→ Unlimited usage -Modelos: +Models: kr/claude-sonnet-4.5 kr/claude-haiku-4.5 ``` -### LongCat AI (GRATUITO 50M tokens/dia!) 🆕 - -1. Cadastre-se: [longcat.chat](https://longcat.chat) com e-mail ou telefone -2. Gere uma chave de API gratuita -3. Dashboard → Adicionar Provedor → LongCat - -**Modelos:** - -- `lc/LongCat-Flash-Lite` — **50M tokens/dia** 💥 (maior cota gratuita do mundo!) -- `lc/LongCat-Flash-Chat` — 500K tokens/dia -- `lc/LongCat-Flash-Thinking` — 500K tokens/dia (raciocínio) - -> 100% gratuito durante o beta público. Reset diário à meia-noite UTC. - -### Pollinations AI (SEM CHAVE NECESSÁRIA!) 🆕 - -1. Adicione o provedor Pollinations no Dashboard -2. Deixe o campo de chave API vazio (ou coloque qualquer string) -3. Comece a usar imediatamente! - -**Modelos via `pol/`:** `openai` (GPT-5), `claude`, `gemini`, `deepseek`, `llama` (Llama 4) - -> Sem cadastro, sem chave, sem cartão de crédito. 1 req/15s ilimitado. - -### Cloudflare Workers AI (GRATUITO 10K Neurons/dia!) 🆕 - -1. Cadastre-se: [dash.cloudflare.com](https://dash.cloudflare.com) -2. Gere um API Token em Profile → API Tokens -3. Copie seu Account ID (coluna direita do dashboard) -4. Dashboard → Adicionar Provedor → Cloudflare AI - - API Key: seu token - - Account ID: seu account ID - -**Modelos via `cf/`:** `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, 50+ mais - -> 10K Neurons/dia ≈ 150 respostas de LLM ou 500s de transcrição Whisper gratuita! - -### Scaleway AI (1M tokens gratuitos!) 🆕 - -1. Cadastre-se: [console.scaleway.com](https://console.scaleway.com) -2. Gere uma chave de API IAM -3. Dashboard → Adicionar Provedor → Scaleway - -**Modelos via `scw/`:** `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct` - -> 1M tokens gratuitos para novas contas. Dados processados na 🇫🇷 França (EU/GDPR). -
-
🎨 Criar Combos
+🎨 Create Combos
-### Exemplo 1: Maximizar Assinatura → Backup Barato +### Example 1: Maximize Subscription → Cheap Backup ``` -Dashboard → Combos → Criar Novo +Dashboard → Combos → Create New -Nome: premium-coding -Modelos: - 1. cc/claude-opus-4-6 (Assinatura primária) - 2. glm/glm-4.7 (Backup barato, $0.6/1M) - 3. minimax/MiniMax-M2.1 (Fallback mais barato, $0.20/1M) +Name: premium-coding +Models: + 1. cc/claude-opus-4-6 (Subscription primary) + 2. glm/glm-4.7 (Cheap backup, $0.6/1M) + 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M) -Use na CLI: premium-coding +Use in CLI: premium-coding ``` -### Exemplo 2: Somente Gratuito (Custo Zero) +### Example 2: Free-Only (Zero Cost) ``` -Nome: free-combo -Modelos: - 1. gc/gemini-3-flash-preview (180K grátis/mês) - 2. if/kimi-k2-thinking (ilimitado) - 3. qw/qwen3-coder-plus (ilimitado) +Name: free-combo +Models: + 1. gc/gemini-3-flash-preview (180K free/month) + 2. if/kimi-k2-thinking (unlimited) + 3. qw/qwen3-coder-plus (unlimited) -Custo: $0 para sempre! +Cost: $0 forever! ```
-
---
-## 🐛 Solução de Problemas
+## Solução de Problemas
🔧 Integração CLI
+🔧 CLI Integration
### Cursor IDE ``` -Configurações → Modelos → Avançado: +Settings → Models → Advanced: OpenAI API Base URL: http://localhost:20128/v1 - OpenAI API Key: [do dashboard OmniRoute] + OpenAI API Key: [from OmniRoute dashboard] Model: cc/claude-opus-4-6 ``` ### Claude Code -Use a página **CLI Tools** no dashboard para configuração em um clique, ou edite `~/.claude/settings.json` manualmente. +Use the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually. ### Codex CLI @@ -1345,13 +1679,13 @@ codex "your prompt" ### OpenClaw -**Opção 1 — Dashboard (recomendado):** +**Option 1 — Dashboard (recommended):** ``` -Dashboard → CLI Tools → OpenClaw → Selecionar Modelo → Aplicar +Dashboard → CLI Tools → OpenClaw → Select Model → Apply ``` -**Opção 2 — Manual:** Edite `~/.openclaw/openclaw.json`: +**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`: ```json { @@ -1367,199 +1701,420 @@ Dashboard → CLI Tools → OpenClaw → Selecionar Modelo → Aplicar } ``` -> **Nota:** OpenClaw funciona apenas com OmniRoute local. Use `127.0.0.1` em vez de `localhost` para evitar problemas de resolução IPv6. +> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues. ### Cline / Continue / RooCode ``` -Configurações → Configuração de API: - Provedor: OpenAI Compatible +Settings → API Configuration: + Provider: OpenAI Compatible Base URL: http://localhost:20128/v1 - API Key: [do dashboard OmniRoute] + 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. +
-
+### 🔐 OAuth on a Remote Server
+
+
+
+
+> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server**
+
+#### Why does Antigravity / Gemini CLI OAuth fail on remote servers?
+
+The **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console.
+
+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
+
+# For Gemini CLI:
+GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com
+GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret
+GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret
+```
+
+**6. Restart OmniRoute**
+
+```bash
+# npm:
+npm run dev
+
+# Docker:
+docker restart omniroute
+```
+
+**7. Try connecting again**
+
+Dashboard → Providers → Antigravity (or Gemini CLI) → OAuth
+
+Google will now redirect correctly to `https://your-server.com/callback`.
---
-## 🛠️
+#### Temporary workaround (without custom credentials)
-- **Runtime**: Node.js 20+
-- **Linguagem**: TypeScript 5.9 — **100% TypeScript** em `src/` e `open-sse/` (v1.0.6)
-- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4
-- **Banco de Dados**: LowDB (JSON) + SQLite (estado do domínio + logs de proxy)
-- **Streaming**: Server-Sent Events (SSE)
-- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys
-- **Testes**: Node.js test runner (368+ testes unitários)
-- **CI/CD**: GitHub Actions (publicação automática npm + Docker Hub no release)
-- **Website**: [omniroute.online](https://omniroute.online)
-- **Pacote**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
-- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
-- **Resiliência**: Circuit breaker, backoff exponencial, anti-thundering herd, spoofing TLS
+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.
---
-## 📖 Documentação
-
-| Documento | Descrição |
-| ----------------------------------------------- | ------------------------------------------------- |
-| [Guia do Usuário](docs/USER_GUIDE.md) | Provedores, combos, integração CLI, deploy |
-| [Referência da API](docs/API_REFERENCE.md) | Todos os endpoints com exemplos |
-| [Solução de Problemas](docs/TROUBLESHOOTING.md) | Problemas comuns e soluções |
-| [Arquitetura](docs/ARCHITECTURE.md) | Arquitetura do sistema e internos |
-| [Contribuindo](CONTRIBUTING.md) | Setup de desenvolvimento e diretrizes |
-| [Spec OpenAPI](docs/openapi.yaml) | Especificação OpenAPI 3.0 |
-| [Política de Segurança](SECURITY.md) | Reportar vulnerabilidades e práticas de segurança |
-| [Deploy em VM](docs/VM_DEPLOYMENT_GUIDE.md) | Guia completo: VM + nginx + Cloudflare |
-| [Galeria de Features](docs/FEATURES.md) | Tour visual do dashboard com screenshots |
-
-### 📸 Preview do Dashboard
-
Clique para expandir o guia de solução de problemas
+Click to expand troubleshooting guide
**"Language model did not provide messages"** -- Cota do provedor esgotada → Verifique o rastreador de cota no dashboard -- Solução: Use combo com fallback ou mude para tier mais barato +- Provider quota exhausted → Check dashboard quota tracker +- Solution: Use combo fallback or switch to cheaper tier **Rate limiting** -- Cota de assinatura esgotada → Fallback para GLM/MiniMax -- Adicione combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Subscription quota out → Fallback to GLM/MiniMax +- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -**Token OAuth expirado** +**OAuth token expired** -- Renovado automaticamente pelo OmniRoute -- Se persistir: Dashboard → Provedor → Reconectar +- Auto-refreshed by OmniRoute +- If issues persist: Dashboard → Provider → Reconnect -**Custos altos** +**High costs** -- Verifique estatísticas de uso em Dashboard → Custos -- Mude modelo primário para GLM/MiniMax -- Use tier gratuito (Gemini CLI, iFlow) para tarefas não-críticas +- Check usage stats in Dashboard → Costs +- Switch primary model to GLM/MiniMax +- Use free tier (Gemini CLI, iFlow) for non-critical tasks -**Dashboard abre na porta errada** +**Dashboard/API ports are wrong** -- Defina `PORT=20128` e `NEXT_PUBLIC_BASE_URL=http://localhost:20128` +- `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) -**Erros de cloud sync** +**Cloud sync errors** -- Verifique se `BASE_URL` aponta para sua instância em execução -- Verifique se `CLOUD_URL` aponta para seu endpoint cloud esperado -- Mantenha valores `NEXT_PUBLIC_*` alinhados com valores do servidor +- 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 -**Primeiro login não funciona** +**First login not working** -- Verifique `INITIAL_PASSWORD` no `.env` -- Se não definido, senha padrão é `123456` +- Check `INITIAL_PASSWORD` in `.env` +- If unset, fallback password is `123456` -**Sem logs de requisição** +**No request logs** -- Defina `ENABLE_REQUEST_LOGS=true` no `.env` +- Set `ENABLE_REQUEST_LOGS=true` in `.env` -**Teste de conexão mostra "Invalid" para provedores compatíveis com OpenAI** +**Connection test shows "Invalid" for OpenAI-compatible providers** -- Muitos provedores não expõem endpoint `/models` -- OmniRoute v1.0.6+ inclui validação via chat completions como fallback -- Certifique-se de que a base URL inclui sufixo `/v1` +- Many providers don't expose a `/models` endpoint +- OmniRoute v1.0.6+ includes fallback validation via chat completions +- Ensure base URL includes `/v1` suffix -
-
---
-## 🗺️
+Clique para ver screenshots do dashboard
+🇧🇷 Versão em Português
-| Página | Screenshot | -| ----------------- | ------------------------------------------------- | -| **Provedores** |  | -| **Combos** |  | -| **Analytics** |  | -| **Saúde** |  | -| **Tradutor** |  | -| **Configurações** |  | -| **CLI Tools** |  | -| **Logs de Uso** |  | -| **Endpoint** |  | +#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos? + +Os provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo. + +As credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticação com: + +``` +Error 400: redirect_uri_mismatch +``` + +#### Solução: Configure suas próprias credenciais OAuth + +Você precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor. + +#### Passo a passo + +**1. Acesse o Google Cloud Console** + +Abra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) + +**2. Crie um novo OAuth 2.0 Client ID** + +- Clique em **"+ Create Credentials"** → **"OAuth client ID"** +- Tipo de aplicativo: **"Web application"** +- Nome: escolha qualquer nome (ex: `OmniRoute Remote`) + +**3. Adicione as Authorized Redirect URIs** + +No campo **"Authorized redirect URIs"**, adicione: + +``` +https://seu-servidor.com/callback +``` + +> Substitua `seu-servidor.com` pelo domínio ou IP do seu servidor (inclua a porta se necessário, ex: `http://45.33.32.156:20128/callback`). + +**4. Salve e copie as credenciais** + +Após criar, o Google mostrará o **Client ID** e o **Client Secret**. + +**5. Configure as variáveis de ambiente** + +No seu `.env` (ou nas variáveis de ambiente do Docker): + +```bash +# Para Antigravity: +ANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com +ANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret + +# Para Gemini CLI: +GEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com +GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret +GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret +``` + +**6. Reinicie o OmniRoute** + +```bash +# Se usando npm: +npm run dev + +# Se usando Docker: +docker restart omniroute +``` + +**7. Tente conectar novamente** + +Dashboard → Providers → Antigravity (ou Gemini CLI) → OAuth + +Agora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará. + +--- + +#### Workaround temporário (sem configurar credenciais próprias) + +Se não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**: + +1. O OmniRoute abrirá a URL de autorização do Google +2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto) +3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue) +4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute +5. Clique em **"Connect"** + +> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.
+
---
-## 👥 Contribuidores
+## Documentação
+
+| Document | Description |
+| ---------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 16 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/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
+| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
+
+---
+
+## 🗺️ Roadmap
+
+OmniRoute has **210+ 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, P2C account selection |
+| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |
+| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |
+| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider 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
[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
-### Como Contribuir
+### How to Contribute
-1. Faça fork do repositório
-2. Crie sua branch de funcionalidade (`git checkout -b feature/amazing-feature`)
-3. Faça commit das suas alterações (`git commit -m 'Add amazing feature'`)
-4. Faça push para a branch (`git push origin feature/amazing-feature`)
-5. Abra um Pull Request
+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
-Veja [CONTRIBUTING.md](CONTRIBUTING.md) para diretrizes detalhadas.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
-### Lançando uma Nova Versão
+### Releasing a New Version
```bash
-# Crie um release — publicação no npm acontece automaticamente
-gh release create v1.0.6 --title "v1.0.6" --generate-notes
+# Create a release — npm publish happens automatically
+gh release create v2.0.0 --title "v2.0.0" --generate-notes
```
---
-## 📊 Histórico de Stars
+## 📊 Star History
## Stargazers over time
## [](https://starchart.cc/diegosouzapw/OmniRoute)
-## 🙏 Agradecimentos
+## 🙏 Acknowledgments
-Agradecimento especial a **[9router](https://github.com/decolua/9router)** por **[decolua](https://github.com/decolua)** — o projeto original que inspirou este fork. OmniRoute se baseia nessa fundação incrível com funcionalidades adicionais, APIs multi-modal e uma reescrita completa em TypeScript.
+Special thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.
-Agradecimento especial a **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — a implementação original em Go que inspirou esta adaptação em JavaScript.
+Special thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.
---
-## 📄 Licença
+## Licença
-Licença MIT - veja [LICENSE](LICENSE) para detalhes.
+MIT License - see [LICENSE](LICENSE) for details.
---
Click to expand tech stack details
-### 🔜 Em Breve +- **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**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions) +- **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 -- 🔗 **Integração com OpenCode** — Suporte nativo como provider para a IDE OpenCode -- 🔗 **Integração com TRAE** — Suporte completo ao framework de desenvolvimento TRAE -- 📦 **Batch API** — Processamento assíncrono em lote para requisições em massa -- 🎯 **Roteamento por Tags** — Roteamento de requisições baseado em tags personalizadas -- 💰 **Estratégia de Menor Custo** — Seleção automática do provedor mais barato - -> 📝 Especificações completas de features disponíveis em [`docs/new-features/`](docs/new-features/) (217 specs detalhadas) +
- Feito com ❤️ para desenvolvedores que programam 24/7
+ Built with ❤️ for developers who code 24/7
omniroute.online
+
diff --git a/docs/i18n/pt-BR/docs/FEATURES.md b/docs/i18n/pt-BR/docs/FEATURES.md
new file mode 100644
index 0000000000..e32bab7c3a
--- /dev/null
+++ b/docs/i18n/pt-BR/docs/FEATURES.md
@@ -0,0 +1,145 @@
+# OmniRoute — Dashboard Features Gallery (Português (Brasil))
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/FEATURES.md) · 🇪🇸 [es](../../es/docs/FEATURES.md) · 🇫🇷 [fr](../../fr/docs/FEATURES.md) · 🇩🇪 [de](../../de/docs/FEATURES.md) · 🇮🇹 [it](../../it/docs/FEATURES.md) · 🇷🇺 [ru](../../ru/docs/FEATURES.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FEATURES.md) · 🇯🇵 [ja](../../ja/docs/FEATURES.md) · 🇰🇷 [ko](../../ko/docs/FEATURES.md) · 🇸🇦 [ar](../../ar/docs/FEATURES.md) · 🇮🇳 [in](../../in/docs/FEATURES.md) · 🇹🇭 [th](../../th/docs/FEATURES.md) · 🇻🇳 [vi](../../vi/docs/FEATURES.md) · 🇮🇩 [id](../../id/docs/FEATURES.md) · 🇲🇾 [ms](../../ms/docs/FEATURES.md) · 🇳🇱 [nl](../../nl/docs/FEATURES.md) · 🇵🇱 [pl](../../pl/docs/FEATURES.md) · 🇸🇪 [sv](../../sv/docs/FEATURES.md) · 🇳🇴 [no](../../no/docs/FEATURES.md) · 🇩🇰 [da](../../da/docs/FEATURES.md) · 🇫🇮 [fi](../../fi/docs/FEATURES.md) · 🇵🇹 [pt](../../pt/docs/FEATURES.md) · 🇷🇴 [ro](../../ro/docs/FEATURES.md) · 🇭🇺 [hu](../../hu/docs/FEATURES.md) · 🇧🇬 [bg](../../bg/docs/FEATURES.md) · 🇸🇰 [sk](../../sk/docs/FEATURES.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FEATURES.md) · 🇮🇱 [he](../../he/docs/FEATURES.md) · 🇵🇭 [phi](../../phi/docs/FEATURES.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FEATURES.md)
+
+---
+
+Visual guide to every section of the OmniRoute dashboard.
+
+---
+
+## 🔌 Providers
+
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
+
+
+
+---
+
+## 🎨 Combos
+
+Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
+
+
+
+---
+
+## 📊 Analytics
+
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
+
+
+
+---
+
+## 🏥 System Health
+
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+
+
+
+---
+
+## 🔧 Translator Playground
+
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
+
+
+
+---
+
+## 🎮 Model Playground _(v2.0.9+)_
+
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
+
+---
+
+## 🎨 Themes _(v2.0.5+)_
+
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
+
+## ⚙️ Settings
+
+Comprehensive settings panel with tabs:
+
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning
+- **Advanced** — Configuration overrides
+
+
+
+---
+
+## 🔧 CLI Tools
+
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
+
+
+
+---
+
+## 🤖 CLI Agents _(v2.0.11+)_
+
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
+
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
+
+---
+
+## 🖼️ Media _(v2.0.3+)_
+
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
+
+## 📝 Request Logs
+
+Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
+
+
+
+---
+
+## 🌐 API Endpoint
+
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
+
+
+
+---
+
+## 🔑 API Key Management
+
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
+
+---
+
+## 📋 Audit Log
+
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
+
+---
+
+## 🖥️ Desktop Application
+
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
+
+Key features:
+
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
+
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.
diff --git a/docs/i18n/pt/README.md b/docs/i18n/pt/README.md
index fe08fe4db1..5b019e58c2 100644
--- a/docs/i18n/pt/README.md
+++ b/docs/i18n/pt/README.md
@@ -1,24 +1,94 @@
-omniroute.online
-
-
- # 🚀 OmniRoute — O gateway de IA gratuito
+# 🚀 OmniRoute — The Free AI Gateway (Português (Portugal))
-### Nunca pare de codificar. Roteamento inteligente para **modelos de IA GRATUITOS e de baixo custo** com fallback automático.
-
-_Seu proxy de API universal — um endpoint, mais de 36 provedores, tempo de inatividade zero._
-
-**Conclusões de bate-papo • Incorporações • Geração de imagem • Áudio • Reclassificação • 100% TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Provedor de IA gratuito para seus agentes de codificação favoritos
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Conecte qualquer ferramenta IDE ou CLI com tecnologia de IA por meio do OmniRoute - gateway de API gratuito para codificação ilimitada._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+` tags no longer leak to clients in SSE streaming responses (#585) |
+| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with per-provider/account quota enforcement, idempotency, SHA-256 storage, and optional GitHub issue reporting |
+| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG → generic fallback chain |
+| 🔄 **Model Auto-Sync** | 24h scheduler and manual UI toggle to sync model lists for built-in and custom OpenAI-compatible providers |
+| 🌐 **OpenCode Zen/Go** | Two new providers from @kang-heewon via PR #530: free tier + subscription tier via `OpencodeExecutor` |
+| 🐛 **Gemini CLI OAuth** | Actionable error when `GEMINI_OAUTH_CLIENT_SECRET` is missing in Docker (was cryptic Google error) |
+| 🐛 **OpenCode config** | `saveOpenCodeConfig()` now correctly writes TOML to `XDG_CONFIG_HOME` |
+| 🐛 **Pinned model override** | `body.model` correctly set to `pinnedModel` on context-cache protection |
+| 🐛 **Codex/Claude loop** | `tool_result` blocks now converted to text to stop infinite loops |
+| 🐛 **Login redirect** | Login no longer freezes after skipping password setup |
+| 🐛 **Windows paths** | MSYS2/Git-Bash paths (`/c/...`) normalized to `C:\...` automatically |
+
+---
+
+## 🖼️ Main Dashboard
+
+
-📡 Todos os agentes se conectam via ` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**Stop wasting money and hitting limits:**
-### 🆕 What's New in v3.0.0
+- Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**OmniRoute solves this:**
+
+- ✅ **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
+- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool
---
-[](https://www.npmjs.com/package/omniroute)
-[](https://hub.docker.com/r/diegosouzapw/omniroute)
-[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
-[](https://omniroute.online)
-[](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
+## 📧 Support
-[🌐 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)
+> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.
-🌐 **Available in:** 🇺🇸 [English](../../README.md) | 🇧🇷 [Português (Brasil)](../pt-BR/README.md) | 🇪🇸 [Español](../es/README.md) | 🇫🇷 [Français](../fr/README.md) | 🇮🇹 [Italiano](../it/README.md) | 🇷🇺 [Русский](../ru/README.md) | 🇨🇳 [中文 (简体)](../zh-CN/README.md) | 🇩🇪 [Deutsch](../de/README.md) | 🇮🇳 [हिन्दी](../in/README.md) | 🇹🇭 [ไทย](../th/README.md) | 🇺🇦 [Українська](../uk-UA/README.md) | 🇸🇦 [العربية](../ar/README.md) | 🇯🇵 [日本語](../ja/README.md) | 🇻🇳 [Tiếng Việt](../vi/README.md) | 🇧🇬 [Български](../bg/README.md) | 🇩🇰 [Dansk](../da/README.md) | 🇫🇮 [Suomi](../fi/README.md) | 🇮🇱 [עברית](../he/README.md) | 🇭🇺 [Magyar](../hu/README.md) | 🇮🇩 [Bahasa Indonesia](../id/README.md) | 🇰🇷 [한국어](../ko/README.md) | 🇲🇾 [Bahasa Melayu](../ms/README.md) | 🇳🇱 [Nederlands](../nl/README.md) | 🇳🇴 [Norsk](../no/README.md) | 🇵🇹 [Português (Portugal)](../pt/README.md) | 🇷🇴 [Română](../ro/README.md) | 🇵🇱 [Polski](../pl/README.md) | 🇸🇰 [Slovenčina](../sk/README.md) | 🇸🇪 [Svenska](../sv/README.md) | 🇵🇭 [Filipino](../phi/README.md)
-
-
-
----
-
-## 🖼️
-
-
-
- # 🚀 OmniRoute — O gateway de IA gratuito
+# 🚀 OmniRoute — The Free AI Gateway (Português (Portugal))
-### Nunca pare de codificar. Roteamento inteligente para **modelos de IA GRATUITOS e de baixo custo** com fallback automático.
-
-_Seu proxy de API universal — um endpoint, mais de 36 provedores, tempo de inatividade zero._
-
-**Conclusões de bate-papo • Incorporações • Geração de imagem • Áudio • Reclassificação • 100% TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Provedor de IA gratuito para seus agentes de codificação favoritos
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Conecte qualquer ferramenta IDE ou CLI com tecnologia de IA por meio do OmniRoute - gateway de API gratuito para codificação ilimitada._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+
+
+[](https://www.npmjs.com/package/omniroute)
+[](https://www.npmjs.com/package/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
+[](https://omniroute.online)
+[](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)
+
+
+
+🌐 **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)
+
+---
+
+## 🆕 What's New in v3.0.0
+
+> **Upgrading from v2.9.5?** — See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes.
+
+| Area | Change |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection remediation |
+| ✅ **Route Validation** | All 176 API routes now validated with Zod schemas + `validateBody()` — CI `check:route-validation:t06` passes |
+| 🐛 **omniModel Tag Leak** | Internal `
+
+
+
+---
+
+## 📸 Dashboard Preview
+
+
+
+
+
+---
+
+### 🤖 Free AI Provider for your favorite coding agents
+
+_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._
Click to see dashboard screenshots
+ +| Page | Screenshot | +| -------------- | ------------------------------------------------- | +| **Providers** |  | +| **Combos** |  | +| **Analytics** |  | +| **Health** |  | +| **Translator** |  | +| **Settings** |  | +| **CLI Tools** |  | +| **Usage Logs** |  | +| **Endpoints** |  | + +|
-
+
OpenClaw @@ -92,113 +162,52 @@ _Conecte qualquer ferramenta IDE ou CLI com tecnologia de IA por meio do OmniRou |
http://localhost:20128/v1 ou http://cloud.omniroute.online/v1 — uma configuração, modelos ilimitados e cota
+📡 All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 — one config, unlimited models and quota
---
-### 🆕 What's New in v3.0.0
+## 🤔 Why OmniRoute?
-| Area | Change |
-| ------------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal ` Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `
-
-
-
----
-
-## 📸
-
-
-
-
-
----
-
-## 🤔 Por que OmniRoute?
-
-**Pare de desperdiçar dinheiro e atingir limites:**
-
-- ...
- -| # | # | -| ----- | ---------------------------------------- | -| **1** |  | -| **2** |  | -| **3** |  | -| **4** |  | -| **5** |  | -| **6** |  | -| **7** |  | -| **8** |  | -| **9** |  | - - A cota de assinatura expira sem ser utilizada todos os meses
-- Os limites de taxa impedem você no meio da codificação
-- APIs caras (US$ 20-50/mês por provedor)
-- Troca manual entre provedores
-
-**OmniRoute resolve isso:**
-
-- ✅ **Maximize as assinaturas** - Rastreie a cota, use cada bit antes de redefinir
-- ✅ **Fullback automático** - Assinatura → Chave de API → Barato → Gratuito, tempo de inatividade zero
-- ✅ **Múltiplas contas** - Round-robin entre contas por provedor
-- ✅ **Universal** - Funciona com Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, qualquer ferramenta CLI
-
----
-
-## 📧 Suporte
-
-> 💬 **Junte-se à nossa comunidade!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Obtenha ajuda, compartilhe dicas e fique atualizado.
-
-- **Site**: [omniroute.online](https://omniroute.online)
+- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Problemas**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Projeto Original**: [9router by decolua](https://github.com/decolua/9router)
+- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 Como funciona
+## 🔄 How It Works
```
┌─────────────┐
@@ -227,452 +236,453 @@ Result: Never stop coding, minimal cost
---
-## 🎯 O que o OmniRoute resolve — 30 pontos reais de dor e casos de uso
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **Todo desenvolvedor que usa ferramentas de IA enfrenta esses problemas diariamente.** O OmniRoute foi criado para resolver todos eles, desde custos excessivos até bloqueios regionais, desde fluxos quebrados de OAuth até operações de protocolo e observabilidade empresarial.
+> **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.
-
💸 1. "Eu pago por uma assinatura cara, mas ainda sou interrompido pelos limites"
+💸 1. "I pay for an expensive subscription but still get interrupted by limits"
-Os desenvolvedores pagam US$ 20–200/mês pelo Claude Pro, Codex Pro ou GitHub Copilot. Mesmo pagando, a cota tem um limite máximo – 5h de uso, limites semanais ou limites de taxa por minuto. No meio da sessão de codificação, o provedor para de responder e o desenvolvedor perde fluxo e produtividade. +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. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- **Smart 4-Tier Fallback** — Se a cota de assinatura acabar, redireciona automaticamente para API Key → Barato → Gratuito sem intervenção manual -- **Rastreamento de cota em tempo real** — Mostra o consumo de tokens em tempo real com contagem regressiva redefinida (5h, diariamente, semanalmente) -- **Suporte para múltiplas contas** — Várias contas por provedor com round-robin automático — quando uma acabar, muda para a próxima -- **Combos personalizados** — Cadeias alternativas personalizáveis com 6 estratégias de balanceamento (preencher primeiro, round-robin, P2C, aleatório, menos usado, com custo otimizado) -- **Codex Business Quotas** — Monitoramento de cotas de espaço de trabalho de negócios/equipe diretamente no painel +- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention +- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly) +- **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 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
-` de modelos como DeepSeek R1 em `reasoning_content` padronizado
-- **Saída estruturada para Gemini** — `json_schema` → conversão automática `responseMimeType`/`responseSchema`
-- **`stream` é padronizado como `false`** — Alinha-se com as especificações OpenAI, evitando SSE inesperado em SDKs Python/Rust/Go
+- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 67+ 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
🔌 2. "Preciso usar vários provedores, mas cada um tem uma API diferente"
+🔌 2. "I need to use multiple providers but each has a different API"
-OpenAI usa um formato, Claude (Anthropic) usa outro, Gemini ainda outro. Se um desenvolvedor quiser testar modelos de diferentes provedores ou fazer fallback entre eles, ele precisará reconfigurar SDKs, alterar endpoints e lidar com formatos incompatíveis. Provedores personalizados (FriendLI, NIM) possuem endpoints de modelo não padrão. +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. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- **Endpoint unificado** — Um único `http://localhost:20128/v1` serve como proxy para todos os mais de 36 provedores -- **Tradução de formato** — Automática e transparente: OpenAI ↔ Claude ↔ Gemini ↔ API de respostas -- **Response Sanitization** — Remove campos não padrão (`x_groq`, `usage_breakdown`, `service_tier`) que quebram o OpenAI SDK v1.83+ -- **Normalização de função** — Converte `developer` → `system` para provedores não-OpenAI; `system` → `user` para GLM/ERNIE -- **Think Tag Extraction** — Extrai blocos `
-
🌐 3. "Meu provedor de IA bloqueia minha região/país"
+🌐 3. "My AI provider blocks my region/country"
-Provedores como OpenAI/Codex bloqueiam o acesso de determinadas regiões geográficas. Os usuários recebem erros como `unsupported_country_region_territory` durante conexões OAuth e API. Isto é especialmente frustrante para desenvolvedores de países em desenvolvimento. +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. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- **Configuração de proxy de 3 níveis** — Proxy configurável em 3 níveis: global (todo o tráfego), por provedor (apenas um provedor) e por conexão/chave -- **Selos de proxy codificados por cores** — Indicadores visuais: 🟢 proxy global, 🟡 proxy do provedor, 🔵 proxy de conexão, sempre mostrando o IP -- **Troca de token OAuth por meio de proxy** — O fluxo OAuth também passa pelo proxy, resolvendo `unsupported_country_region_territory` -- **Testes de conexão via proxy** — Os testes de conexão usam o proxy configurado (não há mais bypass direto) -- **Suporte SOCKS5** — Suporte completo ao proxy SOCKS5 para roteamento de saída -- **TLS Fingerprint Spoofing** — Impressão digital TLS semelhante a um navegador via `wreq-js` para ignorar a detecção de bot +- **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
-` prefix
-- **Combos somente gratuitos** — Cadeia `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = US$ 0/mês com tempo de inatividade zero
-- **Créditos gratuitos NVIDIA NIM** — 1.000 créditos gratuitos integrados
-- **Estratégia de Custo Otimizado** — Estratégia de roteamento que escolhe automaticamente o provedor mais barato disponível
+- **Free-Only Combos** — Chain `gc/gemini-3-flash → 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
🆓 4. "Quero usar IA para codificação, mas não tenho dinheiro"
+🆓 4. "I want to use AI for coding but I have no money"
-Nem todos podem pagar US$ 20–200/mês por assinaturas de IA. Estudantes, desenvolvedores de países emergentes, amadores e freelancers precisam de acesso a modelos de qualidade a custo zero. +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. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- **Provedores de nível gratuito integrados** — Suporte nativo para provedores 100% gratuitos: iFlow (8 modelos ilimitados), Qwen (3 modelos ilimitados), Kiro (Claude grátis), Gemini CLI (180 mil/mês grátis) +- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free) - **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/
-
🔒 5. "Preciso proteger meu gateway de IA contra acesso não autorizado"
+🔒 5. "I need to protect my AI gateway from unauthorized access"
-Ao expor um gateway de IA à rede (LAN, VPS, Docker), qualquer pessoa com o endereço pode consumir os tokens/cota do desenvolvedor. Sem proteção, as APIs ficam vulneráveis ao uso indevido, injeção imediata e abuso. +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. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- **Gerenciamento de chaves de API** — Geração, rotação e escopo por provedor com uma página `/dashboard/api-manager` dedicada -- **Permissões em nível de modelo** — Restringir chaves de API a modelos específicos (`openai/*`, padrões curinga), com alternância Permitir tudo/Restringir -- **API Endpoint Protection** — Exija uma chave para `/v1/models` e bloqueie provedores específicos da listagem -- **Auth Guard + Proteção CSRF** — Todas as rotas do painel protegidas com middleware `withAuth` + tokens CSRF -- **Rate Limiter** — Limitação de taxa por IP com janelas configuráveis -- **Filtragem de IP** — Lista de permissões/lista de bloqueio para controle de acesso -- **Prompt Injection Guard** — Sanitização contra padrões de prompt maliciosos -- **Criptografia AES-256-GCM** — Credenciais criptografadas em repouso +- **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. "Meu provedor caiu e perdi meu fluxo de codificação"
+🛑 6. "My provider went down and I lost my coding flow"
-Os provedores de IA podem ficar instáveis, retornar erros 5xx ou atingir limites de taxa temporários. Se um desenvolvedor depender de um único provedor, ele será interrompido. Sem disjuntores, tentativas repetidas podem travar o aplicativo. +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. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- **Disjuntor por provedor** — Abertura/fechamento automático com limites e resfriamento configuráveis (Fechado/Aberto/Meio-aberto) -- **Retirada exponencial** — Atrasos progressivos em novas tentativas -- **Rebanho Anti-Trovão** — Proteção Mutex + semáforo contra tempestades de novas tentativas simultâneas -- **Combo Fallback Chains** — Se o provedor primário falhar, ele cairá automaticamente na cadeia sem intervenção -- **Combo Circuit Breaker** — Desativa automaticamente provedores com falha em uma cadeia de combinação - | 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format | -- **Health Dashboard** — Monitoramento de tempo de atividade, estados de disjuntores, bloqueios, estatísticas de cache, latência p50/p95/p99 +- **Circuit Breaker per-model** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks +- **Exponential Backoff** — Progressive retry delays +- **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 +- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain +- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
-
🔧 7. "Configurar cada ferramenta de IA é tedioso e repetitivo"
+🔧 7. "Configuring each AI tool is tedious and repetitive"
-Os desenvolvedores usam Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Cada ferramenta precisa de uma configuração diferente (endpoint da API, chave, modelo). Reconfigurar ao trocar de provedor ou modelo é uma perda de tempo. +Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- **CLI Tools Dashboard** — Página dedicada com configuração de um clique para Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline -- **GitHub Copilot Config Generator** — Gera `chatLanguageModels.json` para VS Code com seleção de modelo em massa -- **Assistente de integração** — Configuração guiada em 4 etapas para usuários iniciantes -- **Um endpoint, todos os modelos** — Configure `http://localhost:20128/v1` uma vez, acesse mais de 36 provedores +- **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 67+ providers
-
🔑 8. "Gerenciar tokens OAuth de vários provedores é um inferno"
+🔑 8. "Managing OAuth tokens from multiple providers is hell"
-Claude Code, Codex, Gemini CLI, Copilot — todos usam OAuth 2.0 com tokens expirados. Os desenvolvedores precisam se autenticar novamente constantemente, lidar com `client_secret is missing`, `redirect_uri_mismatch` e falhas em servidores remotos. OAuth em LAN/VPS é particularmente problemático. +Claude Code, Codex, Gemini CLI, 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. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- **Atualização automática de token** — Os tokens OAuth são atualizados em segundo plano antes da expiração -- **OAuth 2.0 (PKCE) integrado ** — Fluxo automático para Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow -- **OAuth de várias contas** — Várias contas por provedor por meio de extração de token JWT/ID -- **OAuth LAN/Remote Fix** — Detecção de IP privado para `redirect_uri` + modo URL manual para servidores remotos -- **OAuth Behind Nginx** — Usa `window.location.origin` para compatibilidade de proxy reverso -- **Guia OAuth remoto** — Guia passo a passo para credenciais do Google Cloud em VPS/Docker +- **Auto Token Refresh** — OAuth tokens refresh in background before expiration +- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow +- **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. "Não sei quanto estou gastando ou onde"
+📊 9. "I don't know how much I'm spending or where"
-Os desenvolvedores usam vários provedores pagos, mas não têm uma visão unificada dos gastos. Cada provedor possui seu próprio painel de faturamento, mas não há visão consolidada. Custos inesperados podem se acumular. +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. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- **Painel de análise de custos** — Acompanhamento de custos por token e gerenciamento de orçamento por provedor -- **Limites de orçamento por nível** — Teto de gastos por nível que aciona substituto automático -- **Configuração de preços por modelo** — Preços configuráveis por modelo -- **Estatísticas de uso por chave de API** — Contagem de solicitações e carimbo de data/hora do último uso por chave -- **Painel de análise** — Cartões de estatísticas, gráfico de uso do modelo, tabela de provedores com taxas de sucesso e latência +- **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. "Não consigo diagnosticar erros e problemas em chamadas de IA"
+🐛 10. "I can't diagnose errors and problems in AI calls"
-Quando uma chamada falha, o desenvolvedor não sabe se foi um limite de taxa, um token expirado, um formato errado ou um erro do provedor. Logs fragmentados em diferentes terminais. Sem observabilidade, a depuração é uma tentativa e erro. +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. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- **Painel de registros unificados** — 4 guias: registros de solicitação, registros de proxy, registros de auditoria, console -- **Console Log Viewer** — Visualizador em estilo terminal em tempo real com níveis codificados por cores, rolagem automática, pesquisa, filtro -- **SQLite Proxy Logs** — Logs persistentes que sobrevivem às reinicializações do servidor -- **Translator Playground** — 4 modos de depuração: Playground (tradução de formato), Chat Tester (ida e volta), Test Bench (lote), Live Monitor (tempo real) -- **Solicitar telemetria** — latência p50/p95/p99 + rastreamento X-Request-Id -- **Registro baseado em arquivo com rotação** — O interceptador do console captura tudo no log JSON com rotação baseada em tamanho +- **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 Proxy Logs** — Persistent logs that survive server restarts +- **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 Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation +- **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. "Implantar e manter o gateway é complexo"
+🏗️ 11. "Deploying and maintaining the gateway is complex"
-Instalar, configurar e manter um proxy de IA em diferentes ambientes (local, VPS, Docker, nuvem) exige muito trabalho. Problemas como caminhos codificados, `EACCES` em diretórios, conflitos de porta e compilações entre plataformas aumentam o atrito. +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. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- **instalação global npm** — `npm install -g omniroute && omniroute` — concluído -- **Docker Multiplataforma** — AMD64 + ARM64 nativo (Apple Silicon, AWS Graviton, Raspberry Pi) -- **Perfis Docker Compose** — `base` (sem ferramentas CLI) e `cli` (com Claude Code, Codex, OpenClaw) -- **Aplicativo Electron Desktop** — Aplicativo nativo para Windows/macOS/Linux com bandeja do sistema, inicialização automática e modo offline -- **Modo Split-Port** — API e Dashboard em portas separadas para cenários avançados (proxy reverso, rede de contêineres) -- **Cloud Sync** — Sincronização de configuração entre dispositivos via Cloudflare Workers -- **Backups de banco de dados** — Backup, restauração, exportação e importação automática de todas as configurações +- **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
-
🌍 12. "A interface é somente em inglês e minha equipe não fala inglês"
+🌍 12. "The interface is English-only and my team doesn't speak English"
-Equipes em países que não falam inglês, especialmente na América Latina, Ásia e Europa, enfrentam dificuldades com interfaces somente em inglês. As barreiras linguísticas reduzem a adoção e aumentam os erros de configuração. +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. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- **Painel i18n — 30 idiomas** — Todas as mais de 500 teclas traduzidas, incluindo árabe, búlgaro, dinamarquês, alemão, espanhol, finlandês, francês, hebraico, hindi, húngaro, indonésio, italiano, japonês, coreano, malaio, holandês, norueguês, polonês, português (PT/BR), romeno, russo, eslovaco, sueco, tailandês, ucraniano, vietnamita, chinês, filipino, inglês -- **Suporte RTL** — Suporte da direita para a esquerda para árabe e hebraico -- **READMEs multilíngues** — 30 traduções completas de documentação -- **Seletor de idioma** — Ícone de globo no cabeçalho para troca em tempo real +- **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. "Preciso de mais do que bate-papo - preciso de incorporações, imagens, áudio"
+🔄 13. "I need more than chat — I need embeddings, images, audio"
-IA não é apenas conclusão de bate-papo. Os desenvolvedores precisam gerar imagens, transcrever áudio, criar embeddings para RAG, reclassificar documentos e moderar conteúdo. Cada API possui um endpoint e formato diferente. +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. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- **Embeddings** — `/v1/embeddings` com 6 provedores e mais de 9 modelos -- **Geração de imagem** — `/v1/images/generations` com 10 provedores e mais de 20 modelos (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI) -- **Texto para vídeo** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) e SD WebUI -- **Texto para música** — `/v1/music/generations` — ComfyUI (áudio estável aberto, MusicGen) -- **Transcrição de áudio** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3 -- **Conversão de texto em fala** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, Inworld, Cartesia, PlayHT, + provedores existentes -- **Moderações** — `/v1/moderations` — Verificações de segurança de conteúdo -- **Reclassificação** — `/v1/rerank` — Reclassificação da relevância do documento -- **API de respostas ** — Suporte completo a `/v1/responses` para Codex +- **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. "Não tenho como testar e comparar a qualidade entre modelos"
+🧪 14. "I have no way to test and compare quality across models"
-Os desenvolvedores querem saber qual modelo é melhor para seu caso de uso – código, tradução, raciocínio – mas comparar manualmente é lento. Não existem ferramentas de avaliação integradas. +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. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- **Avaliações LLM** — Teste Golden Set com 10 casos pré-carregados cobrindo saudações, matemática, geografia, geração de código, conformidade com JSON, tradução, remarcação, recusa de segurança -- **4 estratégias de correspondência** — `exact`, `contains`, `regex`, `custom` (função JS) -- **Translator Playground Test Bench** — Teste em lote com múltiplas entradas e saídas esperadas, comparação entre fornecedores -- **Testador de bate-papo** — Ida e volta completa com renderização de resposta visual -- **Monitoramento ao vivo** — Transmissão em tempo real de todas as solicitações que passam pelo proxy +- **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. "Preciso escalar sem perder desempenho"
+📈 15. "I need to scale without losing performance"
-À medida que o volume de solicitações aumenta, sem armazenar em cache as mesmas perguntas geram custos duplicados. Sem idempotência, solicitações duplicadas desperdiçam processamento. Os limites de tarifas por provedor devem ser respeitados. +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. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- **Cache Semântico** — Cache de duas camadas (assinatura + semântica) reduz custo e latência -- **Idempotência de solicitação** — janela de desduplicação de 5s para solicitações idênticas -- **Detecção de limite de taxa** — RPM por provedor, intervalo mínimo e rastreamento simultâneo máximo -- **Limites de taxa editáveis** — Padrões configuráveis em Configurações → Resiliência com persistência -- **Cache de validação de chave de API** — cache de três camadas para desempenho de produção -- **Health Dashboard com telemetria** — latência p50/p95/p99, estatísticas de cache, tempo de atividade +- **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 +- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence +- **API Key Validation Cache** — 3-tier cache for production performance +- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
-
🤖 16. "Quero controlar o comportamento do modelo globalmente"
+🤖 16. "I want to control model behavior globally"
-Desenvolvedores que desejam todas as respostas em um idioma específico, com um tom específico ou que desejam limitar os tokens de raciocínio. Configurar isso em cada ferramenta/solicitação é impraticável. +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. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- **Injeção de Prompt do Sistema** — Prompt global aplicado a todas as solicitações -- **Thinking Budget Validation** — Controle de alocação de token de raciocínio por solicitação (passthrough, automático, personalizado, adaptativo) -- **6 Estratégias de Roteamento** — Estratégias globais que determinam como as solicitações são distribuídas -- **Wildcard Router** — Os padrões `provider/*` roteiam dinamicamente para qualquer provedor -- **Combo Habilitar/Desabilitar Alternar** — Alternar combos diretamente do painel -- **Alternância de provedor** — Habilite/desabilite todas as conexões de um provedor com um clique -- **Provedores bloqueados** — Excluir provedores específicos da listagem `/v1/models` +- **System Prompt Injection** — Global prompt applied to all requests +- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive) +- **6 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 +- **Provider Toggle** — Enable/disable all connections for a provider with one click +- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
-
🧰 17. "Preciso de ferramentas MCP como recursos de produto de primeira classe"
+🧰 17. "I need MCP tools as first-class product capabilities"
-Muitos gateways de IA expõem o MCP apenas como um detalhe de implementação oculto. As equipes precisam de uma camada operacional visível e gerenciável. +Many AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- MCP aparece na navegação do painel e na guia protocolo de endpoint -- Página dedicada de gerenciamento de MCP com processos, ferramentas, escopos e auditoria -- Início rápido integrado para `omniroute --mcp` e integração de cliente +- 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. "Preciso de orquestração A2A com caminhos de tarefa de sincronização + fluxo"
+🧠 18. "I need A2A orchestration with sync + stream task paths"
-Os fluxos de trabalho do agente precisam de respostas diretas e execução em streaming de longa duração com controle do ciclo de vida. +Agent workflows need both direct replies and long-running streamed execution with lifecycle control. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- Endpoint A2A JSON-RPC (`POST /a2a`) com `message/send` e `message/stream` -- Streaming SSE com propagação de estado terminal -- APIs de ciclo de vida de tarefas para `tasks/get` e `tasks/cancel` +- 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. "Preciso de integridade real do processo MCP, não de status adivinhado"
+🛰️ 19. "I need real MCP process health, not guessed status"
-As equipes operacionais precisam saber se o MCP está realmente ativo, e não apenas se uma API está acessível. +Operational teams need to know if MCP is actually alive, not just whether an API is reachable. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- Arquivo de pulsação em tempo de execução com PID, carimbos de data/hora, transporte, contagem de ferramentas e modo de escopo -- API de status MCP combinando pulsação + atividade recente -- Cartões de status da interface do usuário para atualização de processo/tempo de atividade/pulsação +- 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. "Preciso de execução auditável da ferramenta MCP"
+📋 20. "I need auditable MCP tool execution"
-Quando as ferramentas alteram a configuração ou acionam ações operacionais, as equipes precisam de rastreabilidade forense. +When tools mutate config or trigger ops actions, teams need forensic traceability. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- Registro de auditoria apoiado por SQLite para chamadas de ferramentas MCP -- Filtros por ferramenta, sucesso/falha, chave de API e paginação -- Tabela de auditoria do painel + endpoints de estatísticas para automação +- 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. "Preciso de permissões MCP com escopo definido por integração"
+🔐 21. "I need scoped MCP permissions per integration"
-Clientes diferentes devem ter acesso com privilégios mínimos às categorias de ferramentas. +Different clients should have least-privilege access to tool categories. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- 9 escopos MCP granulares para acesso controlado à ferramenta -- Aplicação do escopo e visibilidade na UI de gerenciamento do MCP -- Postura padrão segura para ferramentas operacionais +- 9 granular MCP scopes for controlled tool access +- Scope enforcement and visibility in MCP management UI +- Safe default posture for operational tooling
-
⚙️ 22. "Preciso de controles operacionais sem reimplantar"
+⚙️ 22. "I need operational controls without redeploying"
-As equipes precisam de mudanças rápidas no tempo de execução durante incidentes ou eventos de custo. +Teams need quick runtime changes during incidents or cost events. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- Alternar ativação combinada diretamente do painel MCP -- Aplicar perfis de resiliência de pacotes de políticas predefinidos -- Redefinir o estado do disjuntor no mesmo painel de operações +- Switch combo activation directly from MCP dashboard +- Apply resilience profiles from pre-defined policy packs +- Reset circuit breaker state from the same operations panel
-
🔄 23. "Preciso de visibilidade e cancelamento do ciclo de vida da tarefa A2A ao vivo"
+🔄 23. "I need live A2A task lifecycle visibility and cancellation"
-Sem visibilidade do ciclo de vida, os incidentes de tarefas tornam-se difíceis de triagem. +Without lifecycle visibility, task incidents become hard to triage. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- Listagem/filtragem de tarefas por estado/habilidade com paginação -- Detalhamento de metadados de tarefas, eventos e artefatos -- Terminal de cancelamento de tarefa e ação de UI com confirmação +- 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. "Preciso de métricas de fluxo ativo para carga A2A"
+🌊 24. "I need active stream metrics for A2A load"
-Os fluxos de trabalho de streaming exigem insights operacionais sobre simultaneidade e conexões em tempo real. +Streaming workflows require operational insight into concurrency and live connections. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- Contadores de fluxo ativos integrados ao status A2A -- Carimbo de data/hora da última tarefa e contagens por estado -- Cartões de painel A2A para monitoramento de operações em tempo real +- Active stream counters integrated into A2A status +- Last task timestamp and per-state counts +- A2A dashboard cards for real-time ops monitoring
-
🪪 25. "Preciso de descoberta de agente padrão para clientes"
+🪪 25. "I need standard agent discovery for clients"
-Clientes e orquestradores externos precisam de metadados legíveis por máquina para integração. +External clients and orchestrators need machine-readable metadata for onboarding. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- Cartão de agente exposto em `/.well-known/agent.json` -- Capacidades e habilidades mostradas na UI de gerenciamento -- A API de status A2A inclui metadados de descoberta para automação +- Agent Card exposed at `/.well-known/agent.json` +- Capabilities and skills shown in management UI +- A2A status API includes discovery metadata for automation
-
🧭 26. "Preciso de descoberta de protocolo na UX do produto"
+🧭 26. "I need protocol discoverability in the product UX"
-Se os usuários não conseguirem descobrir superfícies de protocolo, a adoção e a qualidade do suporte cairão. +If users cannot discover protocol surfaces, adoption and support quality drop. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- Entradas da barra lateral para MCP e A2A -- Guia Protocolos da página Endpoint com início rápido e status -- Links da visão geral para painéis de gerenciamento dedicados +- 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. "Preciso de validação de protocolo ponta a ponta com clientes reais"
+🧪 27. "I need end-to-end protocol validation with real clients"
-Os testes simulados não são suficientes para validar a compatibilidade do protocolo antes do lançamento. +Mock tests are not enough to validate protocol compatibility before release. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- Suíte E2E que inicializa o aplicativo e usa transporte de cliente SDK MCP real -- Testes de cliente A2A para fluxos de descoberta, envio, streaming, obtenção e cancelamento -- Verificação cruzada de afirmações com APIs de auditoria MCP e tarefas A2A +- 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. "Preciso de observabilidade unificada em todas as interfaces"
+📡 28. "I need unified observability across all interfaces"
-A divisão da observabilidade por protocolo cria pontos cegos e MTTR mais longo. +Splitting observability by protocol creates blind spots and longer MTTR. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- Painéis/logs/análises unificados em um produto -- Saúde + auditoria + solicitação de telemetria nas camadas OpenAI, MCP e A2A -- APIs operacionais para status e automação +- Unified dashboards/logs/analytics in one product +- Health + audit + request telemetry across OpenAI, MCP, and A2A layers +- Operational APIs for status and automation
-
💼 29. "Preciso de um tempo de execução para proxy + ferramentas + orquestração de agente"
+💼 29. "I need one runtime for proxy + tools + agent orchestration"
-A execução de muitos serviços separados aumenta o custo operacional e os modos de falha. +Running many separate services increases operational cost and failure modes. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- Proxy compatível com OpenAI, servidor MCP e servidor A2A em uma pilha -- Autenticação compartilhada, resiliência, armazenamento de dados e observabilidade -- Modelo de política consistente em todas as superfícies de interação +- 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
-
-### Exemplos de manuais (casos de uso integrados)
+### Example Playbooks (Integrated Use Cases)
-**Manual A: Maximize a assinatura paga + backup barato**
+**Playbook A: Maximize paid subscription + cheap backup**
```txt
Combo: "maximize-claude"
@@ -684,7 +694,7 @@ Monthly cost: $20 + small backup spend
Outcome: higher quality, near-zero interruption
```
-**Manual B: Pilha de codificação de custo zero**
+**Playbook B: Zero-cost coding stack**
```txt
Combo: "free-forever"
@@ -696,7 +706,7 @@ Monthly cost: $0
Outcome: stable free coding workflow
```
-**Manual C: cadeia de fallback sempre ativa 24 horas por dia, 7 dias por semana**
+**Playbook C: 24/7 always-on fallback chain**
```txt
Combo: "always-on"
@@ -709,65 +719,132 @@ Combo: "always-on"
Outcome: deep fallback depth for deadline-critical workloads
```
-**Manual D: Operações de agente com MCP + A2A**
+**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/mcp and /dashboard/a2a
-4) Control incidents with resilience profile + task cancellation
+3) Observe via /dashboard/endpoint (MCP and A2A tabs)
+4) Toggle services via inline status controls
```
---
-## ⚡ Início rápido
+## 🆓 Start Free — Zero Configuration Cost
-**1. Instale globalmente:**
+> 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 **iFlow** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |
+| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |
+| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |
+| 5 | `/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).
+
+## Início Rápido
+
+### 1) Install and run
```bash
npm install -g omniroute
omniroute
```
-🎉 O painel abre às `http://localhost:20128`
+> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:
+>
+> ```bash
+> pnpm install -g omniroute
+> pnpm approve-builds -g # Select all packages → approve
+> omniroute
+> ```
-| Comando | Descrição |
-| ----------------------- | ------------------------------------- |
-| `omniroute` | Iniciar servidor (porta padrão 20128) |
-| `omniroute --port 3000` | Usar porta personalizada |
-| `omniroute --no-open` | Não abra o navegador automaticamente |
-| `omniroute --help` | Mostrar ajuda |
+Dashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.
-**2. Conecte um provedor GRATUITO:**
+| 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 |
-Painel → Provedores → Conectar **Claude Code** ou **Antigravidade** → Login OAuth → Concluído!
+Optional split-port mode:
-**3. Use em sua ferramenta CLI:**
-
-```
-Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Settings:
- Endpoint: http://localhost:20128/v1
- API Key: [copy from dashboard]
- Model: if/kimi-k2-thinking
+```bash
+PORT=20128 DASHBOARD_PORT=20129 omniroute
+# API: http://localhost:20128/v1
+# Dashboard: http://localhost:20129
```
-**É isso aí!** Comece a codificar com modelos de IA GRATUITOS.
+### 2) Connect providers and create your API key
-**Alternativa – execute a partir da fonte:**
+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
+
+```txt
+Base URL: http://localhost:20128/v1
+API Key: [copy from Endpoint page]
+Model: if/kimi-k2-thinking (or any provider/model prefix)
+```
+
+Works with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.
+
+### 4) Enable and validate protocols (v2.0)
+
+**MCP (for tool-driven operations):**
+
+```bash
+omniroute --mcp
+```
+
+Then connect your MCP client over `stdio` and test tools like:
+
+- `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 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
+PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev
```
---
## 🐳 Docker
-OmniRoute está disponível como uma imagem pública do Docker em [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
+OmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
-**Execução rápida:**
+**Quick run:**
```bash
docker run -d \
@@ -778,7 +855,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Com arquivo de ambiente:**
+**With environment file:**
```bash
# Copy and edit .env first
@@ -793,7 +870,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Usando Docker Compose:**
+**Using Docker Compose:**
```bash
# Base profile (no CLI tools)
@@ -803,257 +880,552 @@ docker compose --profile base up -d
docker compose --profile cli up -d
```
-| Imagem | Etiqueta | Tamanho | Descrição |
-| ------------------------ | -------- | ------- | --------------------- |
-| `diegosouzapw/omniroute` | `latest` | ~250 MB | Última versão estável |
-| `diegosouzapw/omniroute` | `1.0.3` | ~250 MB | Versão atual |
+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.
+- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.
+- 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` | `1.0.3` | ~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
+### Início Rápido
+
```bash
-npm run electron:dev # Development mode
+# 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)
+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)
---
-## 💰 Visão geral dos preços
+## 💰 Pricing at a Glance
-| Nível | Provedor | Custo | Redefinição de cota | Melhor para |
-| ------------------- | ------------------- | -------------------------- | ------------------------ | ----------------------- |
-| **💳 ASSINATURA** | Código Claude (Pro) | $ 20/mês | 5h + semanalmente | Já inscrito |
-| | Códice (Plus/Pro) | US$ 20-200/mês | 5h + semanalmente | Usuários OpenAI |
-| | Gêmeos CLI | **GRÁTIS** | 180 mil/mês + 1 mil/dia | Todos! |
-| | Copiloto GitHub | US$ 10-19/mês | Mensalmente | Usuários do GitHub |
-| **🔑 CHAVE DE API** | NVIDIA NIM | **GRÁTIS** (1000 créditos) | Único | Teste de nível gratuito |
-| | DeepSeek | Pagamento conforme uso | Nenhum | Melhor preço/qualidade |
-| | Groq | Nível gratuito + pago | Taxa limitada | Inferência ultrarrápida |
-| | xAI (Groque) | Pagamento conforme uso | Nenhum | Modelos Grok |
-| | Mistral | Nível gratuito + pago | Taxa limitada | IA Europeia |
-| | OpenRouter | Pagamento conforme uso | Nenhum | Mais de 100 modelos |
-| **💰 BARATO** | GLM-4.7 | US$ 0,6/1 milhão | Diariamente 10h | Backup de orçamento |
-| | MiniMax M2.1 | US$ 0,2/1 milhão | Rolamento de 5 horas | Opção mais barata |
-| | Kimi K2 | $ 9 / mês fixo | 10 milhões de tokens/mês | Custo previsível |
-| **🆓 GRÁTIS** | iFlow | $0 | Ilimitado | 8 modelos grátis |
-| | Qwen | $0 | Ilimitado | 3 modelos grátis |
-| | Kiro | $0 | Ilimitado | Cláudio grátis |
+| 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 |
+| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |
+| | 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** | iFlow | **$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 |
-**💡 Dica profissional:** Comece com Gemini CLI (180 mil grátis/mês) + combo iFlow (gratuito ilimitado) = custo de $ 0!
+> 🆕 **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
+iFlow (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.
---
-## 💡 Principais recursos
+---
-### 🧠 Roteamento e inteligência central
+## 🆓 Free Models — What You Actually Get
-| Recurso | O que faz |
-| -------------------------------------------- | -------------------------------------------------------------------------------------------------- |
-| 🎯 **Fullback inteligente de 4 camadas** | Roteamento automático: Assinatura → Chave de API → Barato → Grátis |
-| 📊 **Acompanhamento de cotas em tempo real** | Contagem de tokens ativos + contagem regressiva redefinida por provedor |
-| 🔄 **Tradução de formato** | OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro sem costura + higienização de resposta |
-| 👥 **Suporte para múltiplas contas** | Múltiplas contas por provedor com seleção inteligente |
-| 🔄 **Atualização automática de token** | Os tokens OAuth são atualizados automaticamente com nova tentativa |
-| 🎨 **Combos Personalizados** | 6 estratégias: preencher primeiro, round-robin, p2c, aleatório, menos usado, otimizado para custos |
-| 🧩 **Modelos Personalizados** | Adicione qualquer ID de modelo a qualquer provedor |
-| 🌐 **Roteador curinga** | Rotear padrões `provider/*` para qualquer provedor dinamicamente |
-| 🧠 **Pensando no Orçamento** | Modos de passagem, automático, personalizado e adaptativo para modelos de raciocínio |
-| 🔀 **Model Aliases** | Auto-forward deprecated model IDs to current replacements (built-in + custom) |
-| ⚡ **Background Degradation** | Auto-route background tasks (titles, summaries) to cheaper models |
-| 💬 **Injeção imediata do sistema** | Prompt de sistema global aplicado em todas as solicitações |
-| 📄 **API de respostas** | Suporte completo à API de respostas OpenAI (`/v1/responses`) para Codex |
+> 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.
-### 🎵 APIs multimodais
+### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)
-| Recurso | O que faz |
-| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 🖼️ **Geração de imagens** | `/v1/images/generations` — 4 provedores, mais de 9 modelos |
-| 📐 **Incorporações** | `/v1/embeddings` — 6 provedores, mais de 9 modelos |
-| 🎤 **Transcrição de áudio** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |
-| 🔊 **Conversão de texto em fala** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) |
-| 🛡️ **Moderações** | `/v1/moderations` — Verificações de segurança de conteúdo |
-| 🔀 **Reclassificação** | `/v1/rerank` — Reclassificação da relevância dos documentos |
+| 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 |
-### 🛡️ Resiliência e segurança
+### 🟢 IFLOW MODELS (Free OAuth — No Credit Card)
-| Recurso | O que faz |
-| -------------------------------------------- | ------------------------------------------------------------------------------------ |
-| 🔌 **Disjuntor** | Abertura/fechamento automático por provedor com limites configuráveis |
-| 🛡️ **Rebanho Anti-Trovão** | Mutex + limite de taxa de semáforo para provedores de chaves de API |
-| 🧠 **Cache Semântico** | Cache de duas camadas (assinatura + semântica) reduz custo e latência |
-| ⚡ **Solicitar Idempotência** | Janela de desduplicação 5s para solicitações duplicadas |
-| 🔒 **Falsificação de impressão digital TLS** | Ignore a detecção de bot baseada em TLS via wreq-js |
-| 🌐 **Filtragem de IP** | Lista de permissões/lista de bloqueio para controle de acesso à API |
-| 📊 **Limites de taxas editáveis** | RPM configurável, intervalo mínimo e simultâneo máximo no nível do sistema |
-| 💾 **Rate Limit Persistence** | Learned limits survive restarts via SQLite with 60s debounce + 24h staleness |
-| 🔄 **Token Refresh Resilience** | Per-provider circuit breaker (5 fails→30min) + 30s timeout per attempt |
-| 🛡 **Proteção de endpoint de API** | Autenticação + bloqueio de provedor para o endpoint `/models` |
-| 🔒 **Visibilidade do proxy** | Crachás codificados por cores: 🟢 global, 🟡 provedor, 🔵 por conexão com display IP |
-| 🌐 **Configuração de proxy de 3 níveis** | Configurar proxies em nível global, por provedor ou por conexão |
+| 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 |
-### 📊 Observabilidade e análise
+### 🟡 QWEN MODELS (Device Code Auth)
-| Recurso | O que faz |
-| ------------------------------------------- | ------------------------------------------------------------------------------------------------ |
-| 📝 **Solicitar registro** | Modo de depuração com logs completos de solicitação/resposta |
-| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |
-| 💾 **Logs de proxy SQLite** | Logs de proxy persistentes sobrevivem às reinicializações do servidor |
-| 📊 **Painel de análise** | Alimentado por recargas: cartões de estatísticas, gráfico de uso de modelo, tabela de provedores |
-| 📈 **Acompanhamento do progresso** | Eventos de progresso SSE opcionais para streaming |
-| 🧪 **Avaliações LLM** | Teste de Golden Set com 4 estratégias de jogo |
-| 🔍 **Solicitar Telemetria** | Agregação de latência p50/p95/p99 + rastreamento X-Request-Id |
-| 📋 **Painel de registros** | Página unificada de 4 guias: Logs de solicitação, Logs de proxy, Logs de auditoria, Console |
-| 🖥️ **Visualizador de registros do console** | Visualizador em estilo terminal em tempo real com filtro de nível, pesquisa, rolagem automática |
-| 📑 **Registro baseado em arquivo** | O interceptor do console captura toda a saída para o arquivo de log JSON com rotação |
-| 🏥 **Painel de saúde** | Tempo de atividade do sistema, estados de disjuntores, bloqueios, estatísticas de cache |
-| 💰 **Acompanhamento de custos** | Gestão orçamentária + configuração de preços por modelo |
+| 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) |
-### ☁️ Implantação e sincronização
+### 🟣 GEMINI CLI (Google OAuth)
-| Recurso | O que faz |
-| --------------------------------------- | ------------------------------------------------------------------------------------ |
-| 💾 **Sincronização na nuvem** | Sincronize a configuração entre dispositivos por meio do Cloudflare Workers |
-| 🌐 **Implante em qualquer lugar** | Localhost, VPS, Docker, Cloudflare Workers |
-| 🔑 **Gerenciamento de chaves de API** | Gerar, alternar e definir o escopo de chaves de API por provedor |
-| 🧙 **Assistente de integração** | Configuração guiada em 4 etapas para usuários iniciantes |
-| 🔧 **Painel de Ferramentas CLI** | Configurar com um clique Claude, Codex, Cline, OpenClaw, Kilo, Antigravity |
-| 🔄 **Backups de banco de dados** | Backup, restauração, exportação e importação automáticos para todas as configurações |
-| 🌐 **Internacionalização** | i18n completo com next-intl — Suporte Inglês + Português (Brasil) |
-| 🌍 **Seletor de idioma** | Ícone de globo no cabeçalho para troca de idioma em tempo real (🇺🇸/🇧🇷) |
-| 🧹 **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 |
-| 📂 **Diretório de dados personalizado** | `DATA_DIR` env var para substituir o caminho de armazenamento padrão `~/.omniroute` |
+| Model | Prefix | Limit | Rate Limit |
+| ------------------------ | ------ | --------------------------- | ------------- |
+| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |
+| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |
+
+### ⚫ 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
+> iFlow (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 v2.0 is built as an operational platform, not just a relay proxy.
+
+### 🆕 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 Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |
+| 🤖 **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 (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) |
+| 🤝 **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** | 9 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 combo, apply resilience profiles, reset breakers from one control surface |
+
+### 🧠 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** | 6 balancing strategies + fallback chain control |
+| 🌐 **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) |
+| 💬 **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 |
+| ----------------------------------- | -------------------------------------------------------------------------------------- |
+| 🔌 **Circuit Breakers** | Per-model trip/recover with threshold controls |
+| 🎯 **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 |
+| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |
+| 🔑 **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 |
+
+### 📊 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 |
+| 📋 **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 |
+
+### ☁️ Deployment & Platform
+
+| Feature | What It Does |
+| ----------------------------- | --------------------------------------------------------- |
+| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |
+| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |
+| 💾 **Cloud Sync** | Configuration sync via cloud worker |
+| 🔄 **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 |
+
+### Feature Deep Dive
+
+#### Smart fallback with practical cost control
+
+```txt
+Combo: "my-coding-stack"
+ 1. cc/claude-opus-4-6
+ 2. nvidia/llama-3.3-70b
+ 3. glm/glm-4.7
+ 4. if/kimi-k2-thinking
+```
+
+When quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.
+
+#### 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)
+
+#### 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)
🚀 30. "Preciso enviar fluxos de trabalho de agente sem expansão de códigos colados"
+🚀 30. "I need to ship agentic workflows without glue-code sprawl"
-As equipes perdem velocidade ao unir vários serviços e scripts ad hoc. +Teams lose velocity when stitching multiple ad-hoc services and scripts. -**Como o OmniRoute resolve isso:** +**How OmniRoute solves it:** -- Estratégia unificada de endpoint para clientes e agentes -- UIs de gerenciamento de protocolo integradas e caminhos de validação de fumaça -- Fundações prontas para produção (segurança, registro, resiliência, backup) +- Unified endpoint strategy for clients and agents +- Built-in protocol management UIs and smoke validation paths +- Production-ready foundations (security, logging, resilience, backup)
-` blocos → `reasoning_content` para modelos de pensamento
-- **Saída estruturada** — `json_schema` → `responseMimeType`/`responseSchema` de Gêmeos
-
-### 👥 Suporte para múltiplas contas
-
-- Adicione várias contas por provedor
-- Round-robin automático ou roteamento baseado em prioridade
-- Fallback para a próxima conta quando alguém atingir a cota
-
-### 🔄 Atualização automática de token
-
-- Os tokens OAuth são atualizados automaticamente antes da expiração
-- Não é necessária reautenticação manual
-- Experiência perfeita em todos os provedores
-
-### 🎨 Combos Personalizados
-
-- Crie combinações ilimitadas de modelos
-- 6 estratégias: preencher primeiro, round-robin, poder de duas escolhas, aleatório, menos usado, otimizado para custos
-- Compartilhe combos entre dispositivos com Cloud Sync
-
-### 🏥 Painel de saúde
-
-- Status do sistema (tempo de atividade, versão, uso de memória)
-- Estados do disjuntor por provedor (Fechado/Aberto/Meio-Aberto)
-- Status do limite de taxa e bloqueios ativos
-- Estatísticas de cache de assinatura
-- Telemetria de latência (p50/p95/p99) + cache de prompt
-- Redefinir o status de saúde com um clique
-
-### 🔧 Parque do Tradutor
-
-OmniRoute inclui um poderoso Translator Playground integrado com **4 modos** para depuração, teste e monitoramento de traduções de API:
-
-| Modo | Descrição |
-| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **💻 Parque Infantil** | Tradução direta de formato — cole qualquer corpo de solicitação de API e veja instantaneamente como o OmniRoute o traduz entre formatos de provedor (OpenAI ↔ Claude ↔ Gemini ↔ API de respostas). Inclui modelos de exemplo e detecção automática de formato. |
-| **💬 Testador de bate-papo** | Envie solicitações de chat reais por meio do OmniRoute e veja o percurso completo: sua entrada, a solicitação traduzida, a resposta do provedor e a resposta traduzida de volta. Inestimável para validar o roteamento combinado. |
-| **🧪 Bancada de testes** | Modo de teste em lote — defina vários casos de teste com diferentes entradas e resultados esperados, execute-os todos de uma vez e compare os resultados entre provedores e modelos. |
-| **📱Monitoramento ao vivo** | Monitoramento de solicitações em tempo real: observe as solicitações recebidas conforme elas fluem pelo OmniRoute, veja as traduções de formato acontecendo ao vivo e identifique problemas instantaneamente. |
-
-**Acesso:** Painel → Tradutor (barra lateral)
-
-### 💾 Sincronização na nuvem
-
-- Sincronize provedores, combos e configurações entre dispositivos
-- Sincronização automática em segundo plano
-- Armazenamento criptografado seguro
+- `GET /api/mcp/status`
+- `GET /api/mcp/tools`
+- `GET /api/mcp/audit`
+- `GET /api/mcp/audit/stats`
-## 🧪 Avaliações (Evals)
+📖 Detalhes do recurso
+🧩 MCP Setup (Model Context Protocol)
-### 🎯 Fallback inteligente de 4 camadas +Start MCP transport in stdio mode: -Crie combos com fallback automático: - -``` -Combo: "my-coding-stack" - 1. cc/claude-opus-4-6 (your subscription) - 2. nvidia/llama-3.3-70b (free NVIDIA API) - 3. glm/glm-4.7 (cheap backup, $0.6/1M) - 4. if/kimi-k2-thinking (free fallback) - -→ Auto switches when quota runs out or errors occur +```bash +omniroute --mcp ``` -### 📊 Rastreamento de cotas em tempo real +Recommended validation flow: -- Consumo de token por provedor -- Redefinir contagem regressiva (5 horas, diariamente, semanalmente) -- Estimativa de custos para níveis pagos -- Relatórios mensais de gastos +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. -### 🔄 Tradução de formato +Useful APIs for automation: -Tradução perfeita entre formatos: - -- **OpenAI** ↔ **Claude** ↔ **Gêmeos** ↔ **Respostas OpenAI** -- Sua ferramenta CLI envia o formato OpenAI → OmniRoute traduz → O provedor recebe o formato nativo -- Funciona com qualquer ferramenta que suporte endpoints OpenAI personalizados -- **Higienização de resposta** — Remove campos não padrão para compatibilidade estrita com o OpenAI SDK -- **Normalização de funções** — `developer` → `system` para não-OpenAI; `system` → `user` para modelos GLM/ERNIE -- ** Extração de tags Think ** — `
+
🤝 A2A Setup (Agent2Agent)
-OmniRoute inclui uma estrutura de avaliação integrada para testar a qualidade da resposta do LLM em relação a um conjunto dourado. Acesse-o em **Analytics → Evals** no painel. +Discover the agent: -### Conjunto Dourado Integrado +```bash +curl http://localhost:20128/.well-known/agent.json +``` -O "OmniRoute Golden Set" pré-carregado contém 10 casos de teste cobrindo: +Send a task: -- Saudações, matemática, geografia, geração de código -- Conformidade com o formato JSON, tradução, remarcação -- Recusa de segurança (conteúdo prejudicial), contagem, lógica booleana +```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."}]}}' +``` -### Estratégias de Avaliação +Manage lifecycle: -| Estratégia | Descrição | Exemplo | -| ---------- | --------------------------------------------------------------------------- | -------------------------------- | -| `exact` | A saída deve corresponder exatamente | `"4"` | -| `contains` | A saída deve conter substring (sem distinção entre maiúsculas e minúsculas) | `"Paris"` | -| `regex` | A saída deve corresponder ao padrão regex | `"1.*2.*3"` | -| `custom` | Função JS personalizada retorna verdadeiro/falso | `(output) => output.length > 10` | +- `GET /api/a2a/status` +- `GET /api/a2a/tasks` +- `GET /api/a2a/tasks/:id` +- `POST /api/a2a/tasks/:id/cancel` ---- +Operational UI: -## 📖 Guia de configuração +- `/dashboard/a2a` for task/state/stream observability and smoke actions + +
-
+
+💳 Provedores de assinatura
+🧪 End-to-end protocol validation
-### Código Claude (Pro/Max) +Validate both protocols with real clients: + +```bash +npm run test:protocols:e2e +``` + +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) ```bash Dashboard → Providers → Connect Claude Code @@ -1066,9 +1438,9 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Dica profissional:** Use o Opus para tarefas complexas e o Sonnet para velocidade. OmniRoute rastreia cota por modelo! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! -### Codex OpenAI (Plus/Pro) +### OpenAI Codex (Plus/Pro) ```bash Dashboard → Providers → Connect Codex @@ -1080,7 +1452,24 @@ Models: cx/gpt-5.1-codex-max ``` -### Gemini CLI (GRÁTIS 180K/mês!) +#### 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). + +### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -1092,9 +1481,9 @@ Models: gc/gemini-2.5-pro ``` -**Melhor valor:** Grande nível gratuito! Use isso antes dos níveis pagos. +**Best Value:** Huge free tier! Use this before paid tiers. -### GitHub Copiloto +### GitHub Copilot ```bash Dashboard → Providers → Connect GitHub @@ -1110,88 +1499,88 @@ Models:
-
🔑 Provedores de chave de API
+🔑 API Key Providers
-### NVIDIA NIM (1000 créditos GRÁTIS!) +### NVIDIA NIM (FREE developer access — 70+ models) -1. Inscreva-se: [build.nvidia.com](https://build.nvidia.com) -2. Obtenha uma chave de API gratuita (1.000 créditos de inferência incluídos) -3. Painel → Adicionar Provedor → NVIDIA NIM: - - Chave API: `nvapi-your-key` +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` -**Modelos:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct` e mais de 50 +**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more -**Dica profissional:** API compatível com OpenAI — funciona perfeitamente com a tradução de formato do OmniRoute! +**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation! ### DeepSeek -1. Inscreva-se: [platform.deepseek.com](https://platform.deepseek.com) -2. Obtenha a chave API -3. Painel → Adicionar provedor → DeepSeek +1. Sign up: [platform.deepseek.com](https://platform.deepseek.com) +2. Get API key +3. Dashboard → Add Provider → DeepSeek -**Modelos:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` +**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` -### Groq (nível gratuito disponível!) +### Groq (Free Tier Available!) -1. Inscreva-se: [console.groq.com](https://console.groq.com) -2. Obtenha a chave API (nível gratuito incluído) -3. Painel → Adicionar Provedor → Groq +1. Sign up: [console.groq.com](https://console.groq.com) +2. Get API key (free tier included) +3. Dashboard → Add Provider → Groq -**Modelos:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` +**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` -**Dica profissional:** Inferência ultrarrápida — melhor para codificação em tempo real! +**Pro Tip:** Ultra-fast inference — best for real-time coding! -### OpenRouter (mais de 100 modelos) +### OpenRouter (100+ Models) -1. Inscreva-se: [openrouter.ai](https://openrouter.ai) -2. Obtenha a chave API -3. Painel → Adicionar Provedor → OpenRouter +1. Sign up: [openrouter.ai](https://openrouter.ai) +2. Get API key +3. Dashboard → Add Provider → OpenRouter -**Modelos:** acesse mais de 100 modelos de todos os principais fornecedores por meio de uma única chave de API. +**Models:** Access 100+ models from all major providers through a single API key.
-
💰 Provedores baratos (backup)
+💰 Cheap Providers (Backup)
-### GLM-4.7 (redefinição diária, US$ 0,6/1 milhão) +### GLM-4.7 (Daily reset, $0.6/1M) -1. Inscreva-se: [Zhipu AI](https://open.bigmodel.cn/) -2. Obtenha a chave API do plano de codificação -3. Painel → Adicionar chave API: - - Provedor: `glm` - - Chave API: `your-key` +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` -**Usar:** `glm/glm-4.7` +**Use:** `glm/glm-4.7` -**Dica profissional:** O plano de codificação oferece cota 3× com custo de 1/7! Redefinir diariamente às 10h. +**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -### MiniMax M2.1 (redefinição de 5h, US$ 0,20/1 milhão) +### MiniMax M2.1 (5h reset, $0.20/1M) -1. Inscreva-se: [MiniMax](https://www.minimax.io/) -2. Obtenha a chave API -3. Painel → Adicionar chave API +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key +3. Dashboard → Add API Key -**Usar:** `minimax/MiniMax-M2.1` +**Use:** `minimax/MiniMax-M2.1` -**Dica profissional:** Opção mais barata para contexto longo (1 milhão de tokens)! +**Pro Tip:** Cheapest option for long context (1M tokens)! -### Kimi K2 (US$ 9/mês fixo) +### Kimi K2 ($9/month flat) -1. Inscreva-se: [Moonshot AI](https://platform.moonshot.ai/) -2. Obtenha a chave API -3. Painel → Adicionar chave API +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key +3. Dashboard → Add API Key -**Usar:** `kimi/kimi-latest` +**Use:** `kimi/kimi-latest` -**Dica profissional:** $9 fixos/mês para 10 milhões de tokens = $0,90/custo efetivo de 1 milhão! +**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
-
🆓 Provedores GRATUITOS (backup de emergência)
+🆓 FREE Providers (Emergency Backup)
-### iFlow (8 modelos GRATUITOS) +### iFlow (5 FREE models via OAuth) ```bash Dashboard → Connect iFlow @@ -1206,7 +1595,7 @@ Models: if/deepseek-r1 ``` -### Qwen (3 modelos GRATUITOS) +### Qwen (4 FREE models via Device Code) ```bash Dashboard → Connect Qwen @@ -1218,7 +1607,7 @@ Models: qw/qwen3-coder-flash ``` -### Kiro (Claude GRÁTIS) +### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro @@ -1233,9 +1622,9 @@ Models:
-
🎨 Criar Combos
+🎨 Create Combos
-### Exemplo 1: Maximize a assinatura → Backup barato +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -1249,7 +1638,7 @@ Models: Use in CLI: premium-coding ``` -### Exemplo 2: somente gratuito (custo zero) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -1264,7 +1653,7 @@ Cost: $0 forever!
-
---
-## 🐛 Solução de problemas
+## Resolução de Problemas
🔧 Integração CLI
+🔧 CLI Integration
### Cursor IDE @@ -1275,11 +1664,11 @@ Settings → Models → Advanced: Model: cc/claude-opus-4-6 ``` -### Código Cláudio +### Claude Code -Use a página **Ferramentas CLI** no painel para configuração com um clique ou edite `~/.claude/settings.json` manualmente. +Use the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually. -### CLI do Codex +### Codex CLI ```bash export OPENAI_BASE_URL="http://localhost:20128" @@ -1288,15 +1677,15 @@ export OPENAI_API_KEY="your-omniroute-api-key" codex "your prompt" ``` -###OpenClaw +### OpenClaw -**Opção 1 — Painel (recomendado):** +**Option 1 — Dashboard (recommended):** ``` Dashboard → CLI Tools → OpenClaw → Select Model → Apply ``` -**Opção 2 — Manual:** Editar `~/.openclaw/openclaw.json`: +**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`: ```json { @@ -1312,9 +1701,9 @@ Dashboard → CLI Tools → OpenClaw → Select Model → Apply } ``` -> **Observação:** OpenClaw só funciona com OmniRoute local. Use `127.0.0.1` em vez de `localhost` para evitar problemas de resolução de IPv6. +> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues. -### Cline / Continuar / RooCode +### Cline / Continue / RooCode ``` Settings → API Configuration: @@ -1324,72 +1713,207 @@ Settings → API Configuration: 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. +
-
-- **Tempo de execução**: Node.js 18–22 LTS (⚠️ Node.js 24+ **não é compatível** — `better-sqlite3` binários nativos são incompatíveis)
-- **Idioma**: TypeScript 5.9 — **100% TypeScript** em `src/` e `open-sse/` (v1.0.6)
-- **Estrutura**: Next.js 16 + React 19 + Tailwind CSS 4
-- **Banco de dados**: LowDB (JSON) + SQLite (estado do domínio + logs de proxy)
-- **Streaming**: eventos enviados pelo servidor (SSE)
-- **Autenticação**: OAuth 2.0 (PKCE) + JWT + chaves de API
-- **Testes**: executor de testes Node.js (mais de 368 testes de unidade)
-- **CI/CD**: GitHub Actions (publicação automática de npm + Docker Hub no lançamento)
-- **Site**: [omniroute.online](https://omniroute.online)
-- **Pacote**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
-- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
-- **Resiliência**: Disjuntor, espera exponencial, rebanho anti-trovão, falsificação de TLS
-
----
-
-## 📖 Documentação
-
-| Documento | Descrição |
-| -------------------------------------------- | ------------------------------------------------------ |
-| [User Guide](docs/USER_GUIDE.md) | Provedores, combos, integração CLI, implantação |
-| [API Reference](docs/API_REFERENCE.md) | Todos os endpoints com exemplos |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Problemas e soluções comuns |
-| [Architecture](docs/ARCHITECTURE.md) | Arquitetura do sistema e componentes internos |
-| [Contributing](CONTRIBUTING.md) | Configuração e diretrizes de desenvolvimento |
-| [OpenAPI Spec](docs/openapi.yaml) | Especificação OpenAPI 3.0 |
-| [Security Policy](SECURITY.md) | Relatórios de vulnerabilidades e práticas de segurança |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Guia completo: configuração de VM + nginx + Cloudflare |
-| [Features Gallery](docs/FEATURES.md) | Tour visual do painel com capturas de tela |
-
-### 📸 Visualização do painel
+## 🛠️ Tech Stack
Clique para expandir o guia de solução de problemas
+Click to expand troubleshooting guide
-**"O modelo de linguagem não forneceu mensagens"** +**"Language model did not provide messages"** -- Cota do provedor esgotada → Verifique o rastreador de cota do painel -- Solução: use o combo substituto ou mude para um nível mais barato +- Provider quota exhausted → Check dashboard quota tracker +- Solution: Use combo fallback or switch to cheaper tier -** Limitação de taxa ** +**Rate limiting** -- Cota de assinatura esgotada → Fallback para GLM/MiniMax -- Adicionar combinação: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Subscription quota out → Fallback to GLM/MiniMax +- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -**O token OAuth expirou** +**OAuth token expired** -- Atualizado automaticamente pelo OmniRoute -- Se os problemas persistirem: Painel → Provedor → Reconectar +- Auto-refreshed by OmniRoute +- If issues persist: Dashboard → Provider → Reconnect -**Custos elevados** +**High costs** -- Verifique as estatísticas de uso em Painel → Custos -- Mude o modelo primário para GLM/MiniMax -- Use o nível gratuito (Gemini CLI, iFlow) para tarefas não críticas +- Check usage stats in Dashboard → Costs +- Switch primary model to GLM/MiniMax +- Use free tier (Gemini CLI, iFlow) for non-critical tasks -**Painel abre na porta errada** +**Dashboard/API ports are wrong** -- Definir `PORT=20128` e `NEXT_PUBLIC_BASE_URL=http://localhost:20128` +- `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) -**Erros de sincronização na nuvem** +**Cloud sync errors** -- Verifique `BASE_URL` aponta para sua instância em execução -- Verifique os pontos `CLOUD_URL` para o endpoint de nuvem esperado -- Mantenha os valores `NEXT_PUBLIC_*` alinhados com os valores do lado do servidor +- 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 -**Primeiro login não funciona** +**First login not working** -- Verifique `INITIAL_PASSWORD` em `.env` -- Se não definida, a senha substituta é `123456` +- Check `INITIAL_PASSWORD` in `.env` +- If unset, fallback password is `123456` -**Sem registros de solicitação** +**No request logs** -- Definir `ENABLE_REQUEST_LOGS=true` em `.env` +- Set `ENABLE_REQUEST_LOGS=true` in `.env` -**O teste de conexão mostra "Inválido" para provedores compatíveis com OpenAI** +**Connection test shows "Invalid" for OpenAI-compatible providers** -- Muitos provedores não expõem um endpoint `/models` -- OmniRoute v1.0.6+ inclui validação de fallback por meio de conclusões de chat -- Certifique-se de que o URL base inclua o sufixo `/v1` +- 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 +### 🔐 OAuth on a Remote Server + -> **⚠️ IMPORTANTE para usuários com OmniRoute em VPS/Docker/servidor remoto** +> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server** -#### OAuth +#### Why does Antigravity / Gemini CLI OAuth fail on remote servers? -Os provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que um `redirect_uri` usado no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo. +The **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console. -As credenciais OAuth incorporadas no OmniRoute estão cadastradas **apenas para `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticação com: +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 + +# For Gemini CLI: +GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com +GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +``` + +**6. Restart OmniRoute** + +```bash +# npm: +npm run dev + +# Docker: +docker restart omniroute +``` + +**7. Try connecting again** + +Dashboard → Providers → Antigravity (or Gemini CLI) → OAuth + +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. + +--- + +
+
---
-## 🛠️
+🇧🇷 Versão em Português
+ +#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos? + +Os provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo. + +As credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticação com: ``` Error 400: redirect_uri_mismatch @@ -1397,23 +1921,23 @@ Error 400: redirect_uri_mismatch #### Solução: Configure suas próprias credenciais OAuth -Você precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com o URI do seu servidor. +Você precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor. -####Passo a passo +#### Passo a passo -**1. Acesse o Console do Google Cloud** +**1. Acesse o Google Cloud Console** Abra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) -**2. Crie um novo ID de cliente OAuth 2.0** +**2. Crie um novo OAuth 2.0 Client ID** -- Clique em **"+ Criar credenciais"** → **"ID do cliente OAuth"** -- Tipo de aplicativo: **"Aplicativo Web"** +- Clique em **"+ Create Credentials"** → **"OAuth client ID"** +- Tipo de aplicativo: **"Web application"** - Nome: escolha qualquer nome (ex: `OmniRoute Remote`) -**3. Adicionar como URIs de redirecionamento autorizados** +**3. Adicione as Authorized Redirect URIs** -No campo **"URIs de redirecionamento autorizados"**, adicionado: +No campo **"Authorized redirect URIs"**, adicione: ``` https://seu-servidor.com/callback @@ -1425,7 +1949,7 @@ https://seu-servidor.com/callback Após criar, o Google mostrará o **Client ID** e o **Client Secret**. -**5. Configurar como variáveis de ambiente** +**5. Configure as variáveis de ambiente** No seu `.env` (ou nas variáveis de ambiente do Docker): @@ -1452,150 +1976,145 @@ docker restart omniroute **7. Tente conectar novamente** -Painel → Provedores → Antigravidade (ou Gemini CLI) → OAuth +Dashboard → Providers → Antigravity (ou Gemini CLI) → OAuth Agora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará. --- -#### Solução alternativa temporária (sem configurar credenciais próprias) +#### Workaround temporário (sem configurar credenciais próprias) Se não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**: -1. O OmniRoute abrirá uma URL de autorização do Google +1. O OmniRoute abrirá a URL de autorização do Google 2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto) -3. **Copie a URL completa** da barra de endereço do seu navegador (mesmo que a página não carregue) +3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue) 4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute -5. Clique em **"Conectar"** +5. Clique em **"Connect"** -> Esta solução alternativa funciona porque o código de autorização na URL é válido, independentemente do redirecionamento ter sido carregado ou não. +> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.
-
---
-## 🗺️
+## Documentação
-OmniRoute tem **210+ recursos planejados** em diversas fases de desenvolvimento. Aqui estão as principais áreas:
-
-| Categoria | Recursos planejados | Destaques |
-| --------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------ |
-| 🧠 **Roteamento e Inteligência** | 25+ | Roteamento de menor latência, roteamento baseado em tags, simulação de cota, seleção de conta P2C |
-| 🔒 **Segurança e Conformidade** | 20+ | Proteção SSRF, camuflagem de credenciais, limite de taxa por endpoint, escopo de chave de gerenciamento |
-| 📊 **Observabilidade** | 15+ | Integração OpenTelemetry, monitoramento de cotas em tempo real, rastreamento de custos por modelo |
-| 🔄 **Integrações com Provedores** | 20+ | Registro de modelo dinâmico, resfriamento de provedor, Codex multicontas, análise de cotas do Copilot |
-| ⚡ **Desempenho** | 15+ | Camada de cache dupla, cache de prompt, cache de resposta, manutenção de atividade de streaming, API em lote |
-| 🌐 **Ecossistema** | 10+ | API WebSocket, configuração hot-reload, armazenamento de configuração distribuído, modo comercial |
-
-### 🔜 Em breve
-
-- 🔗 **Integração OpenCode** — Suporte de provedor nativo para o IDE de codificação OpenCode AI
-- 🔗 **Integração TRAE** — Suporte total para a estrutura de desenvolvimento TRAE AI
-- 📦 **API Batch** — Processamento assíncrono em lote para solicitações em massa
-- 🎯 **Roteamento baseado em tags** — Roteie solicitações com base em tags personalizadas e metadados
-- 💰 **Estratégia de custo mais baixo** — Selecione automaticamente o provedor mais barato disponível
-
-> 📝 Especificações completas de recursos disponíveis em [link](docs/new-features/) (217 especificações detalhadas)
+| Document | Description |
+| ---------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 16 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/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
+| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
-## 👥 Colaboradores
+## 🗺️ Roadmap
+
+OmniRoute has **210+ 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, P2C account selection |
+| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |
+| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |
+| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider 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
[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
-### Como contribuir
+### How to Contribute
-1. Bifurque o repositório
-2. Crie sua ramificação de recursos (`git checkout -b feature/amazing-feature`)
-3. Confirme suas alterações (`git commit -m 'Add amazing feature'`)
-4. Envie para a ramificação (`git push origin feature/amazing-feature`)
-5. Abra uma solicitação pull
+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
-Consulte [CONTRIBUTING.md](CONTRIBUTING.md) para obter diretrizes detalhadas.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
-### Lançando uma nova versão
+### Releasing a New Version
```bash
# Create a release — npm publish happens automatically
-gh release create v1.0.6 --title "v1.0.6" --generate-notes
+gh release create v2.0.0 --title "v2.0.0" --generate-notes
```
---
-## 📊 História das Estrelas
+## 📊 Star History
## Stargazers over time
## [](https://starchart.cc/diegosouzapw/OmniRoute)
-## 🙏 Agradecimentos
+## 🙏 Acknowledgments
-Agradecimentos especiais a **[9router](https://github.com/decolua/9router)** de **[decolua](https://github.com/decolua)** — o projeto original que inspirou este fork. OmniRoute se baseia nessa base incrível com recursos adicionais, APIs multimodais e uma reescrita completa do TypeScript.
+Special thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.
-Agradecimentos especiais a **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — a implementação Go original que inspirou esta versão JavaScript.
+Special thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.
---
-## 📄 Licença
+## Licença
-Licença MIT - consulte [LICENSE](LICENSE) para obter detalhes.
+MIT License - see [LICENSE](LICENSE) for details.
---
Clique para ver as capturas de tela do painel
+Click to expand tech stack details
-| Página | Captura de tela | -| -------------------- | ------------------------------------------------- | -| **Fornecedores** |  | -| **Combos** |  | -| **Análise** |  | -| **Saúde** |  | -| **Tradutor** |  | -| **Configurações** |  | -| **Ferramentas CLI** |  | -| **Registros de uso** |  | -| **Ponto final** |  | +- **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**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions) +- **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
- Construído com ❤️ para desenvolvedores que codificam 24 horas por dia, 7 dias por semana
+ Built with ❤️ for developers who code 24/7
omniroute.online
+
diff --git a/docs/i18n/pt/docs/FEATURES.md b/docs/i18n/pt/docs/FEATURES.md
new file mode 100644
index 0000000000..d9e681286c
--- /dev/null
+++ b/docs/i18n/pt/docs/FEATURES.md
@@ -0,0 +1,145 @@
+# OmniRoute — Dashboard Features Gallery (Português (Portugal))
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/FEATURES.md) · 🇪🇸 [es](../../es/docs/FEATURES.md) · 🇫🇷 [fr](../../fr/docs/FEATURES.md) · 🇩🇪 [de](../../de/docs/FEATURES.md) · 🇮🇹 [it](../../it/docs/FEATURES.md) · 🇷🇺 [ru](../../ru/docs/FEATURES.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FEATURES.md) · 🇯🇵 [ja](../../ja/docs/FEATURES.md) · 🇰🇷 [ko](../../ko/docs/FEATURES.md) · 🇸🇦 [ar](../../ar/docs/FEATURES.md) · 🇮🇳 [in](../../in/docs/FEATURES.md) · 🇹🇭 [th](../../th/docs/FEATURES.md) · 🇻🇳 [vi](../../vi/docs/FEATURES.md) · 🇮🇩 [id](../../id/docs/FEATURES.md) · 🇲🇾 [ms](../../ms/docs/FEATURES.md) · 🇳🇱 [nl](../../nl/docs/FEATURES.md) · 🇵🇱 [pl](../../pl/docs/FEATURES.md) · 🇸🇪 [sv](../../sv/docs/FEATURES.md) · 🇳🇴 [no](../../no/docs/FEATURES.md) · 🇩🇰 [da](../../da/docs/FEATURES.md) · 🇫🇮 [fi](../../fi/docs/FEATURES.md) · 🇵🇹 [pt](../../pt/docs/FEATURES.md) · 🇷🇴 [ro](../../ro/docs/FEATURES.md) · 🇭🇺 [hu](../../hu/docs/FEATURES.md) · 🇧🇬 [bg](../../bg/docs/FEATURES.md) · 🇸🇰 [sk](../../sk/docs/FEATURES.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FEATURES.md) · 🇮🇱 [he](../../he/docs/FEATURES.md) · 🇵🇭 [phi](../../phi/docs/FEATURES.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FEATURES.md)
+
+---
+
+Visual guide to every section of the OmniRoute dashboard.
+
+---
+
+## 🔌 Providers
+
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
+
+
+
+---
+
+## 🎨 Combos
+
+Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
+
+
+
+---
+
+## 📊 Analytics
+
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
+
+
+
+---
+
+## 🏥 System Health
+
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+
+
+
+---
+
+## 🔧 Translator Playground
+
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
+
+
+
+---
+
+## 🎮 Model Playground _(v2.0.9+)_
+
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
+
+---
+
+## 🎨 Themes _(v2.0.5+)_
+
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
+
+## ⚙️ Settings
+
+Comprehensive settings panel with tabs:
+
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning
+- **Advanced** — Configuration overrides
+
+
+
+---
+
+## 🔧 CLI Tools
+
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
+
+
+
+---
+
+## 🤖 CLI Agents _(v2.0.11+)_
+
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
+
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
+
+---
+
+## 🖼️ Media _(v2.0.3+)_
+
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
+
+## 📝 Request Logs
+
+Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
+
+
+
+---
+
+## 🌐 API Endpoint
+
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
+
+
+
+---
+
+## 🔑 API Key Management
+
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
+
+---
+
+## 📋 Audit Log
+
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
+
+---
+
+## 🖥️ Desktop Application
+
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
+
+Key features:
+
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
+
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.
diff --git a/docs/i18n/ro/README.md b/docs/i18n/ro/README.md
index 714c05a393..4d5f1c4ba7 100644
--- a/docs/i18n/ro/README.md
+++ b/docs/i18n/ro/README.md
@@ -1,24 +1,94 @@
-omniroute.online
-
-
- # 🚀 OmniRoute — Gateway-ul gratuit AI
+# 🚀 OmniRoute — The Free AI Gateway (Română)
-### Nu opriți niciodată codificarea. Dirijare inteligentă către **modele AI GRATUITE și cu costuri reduse** cu rezervă automată.
-
-_Proxy-ul dvs. universal API - un punct final, peste 36 de furnizori, zero timpi de nefuncționare._
-
-**Finalizări de chat • Încorporare • Generare de imagini • Audio • Reclasificare • 100% TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Furnizor AI gratuit pentru agenții tăi preferați de codare
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Conectați orice instrument IDE sau CLI alimentat de AI prin OmniRoute — gateway API gratuit pentru codare nelimitată._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+` tags no longer leak to clients in SSE streaming responses (#585) |
+| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with per-provider/account quota enforcement, idempotency, SHA-256 storage, and optional GitHub issue reporting |
+| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG → generic fallback chain |
+| 🔄 **Model Auto-Sync** | 24h scheduler and manual UI toggle to sync model lists for built-in and custom OpenAI-compatible providers |
+| 🌐 **OpenCode Zen/Go** | Two new providers from @kang-heewon via PR #530: free tier + subscription tier via `OpencodeExecutor` |
+| 🐛 **Gemini CLI OAuth** | Actionable error when `GEMINI_OAUTH_CLIENT_SECRET` is missing in Docker (was cryptic Google error) |
+| 🐛 **OpenCode config** | `saveOpenCodeConfig()` now correctly writes TOML to `XDG_CONFIG_HOME` |
+| 🐛 **Pinned model override** | `body.model` correctly set to `pinnedModel` on context-cache protection |
+| 🐛 **Codex/Claude loop** | `tool_result` blocks now converted to text to stop infinite loops |
+| 🐛 **Login redirect** | Login no longer freezes after skipping password setup |
+| 🐛 **Windows paths** | MSYS2/Git-Bash paths (`/c/...`) normalized to `C:\...` automatically |
+
+---
+
+## 🖼️ Main Dashboard
+
+
-📡 Toți agenții se conectează prin ` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**Stop wasting money and hitting limits:**
-### 🆕 What's New in v3.0.0
+- Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**OmniRoute solves this:**
+
+- ✅ **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
+- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool
---
-[](https://www.npmjs.com/package/omniroute)
-[](https://hub.docker.com/r/diegosouzapw/omniroute)
-[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
-[](https://omniroute.online)
-[](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
+## 📧 Support
-[🌐 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)
+> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.
-🌐 **Available in:** 🇺🇸 [English](../../README.md) | 🇧🇷 [Português (Brasil)](../pt-BR/README.md) | 🇪🇸 [Español](../es/README.md) | 🇫🇷 [Français](../fr/README.md) | 🇮🇹 [Italiano](../it/README.md) | 🇷🇺 [Русский](../ru/README.md) | 🇨🇳 [中文 (简体)](../zh-CN/README.md) | 🇩🇪 [Deutsch](../de/README.md) | 🇮🇳 [हिन्दी](../in/README.md) | 🇹🇭 [ไทย](../th/README.md) | 🇺🇦 [Українська](../uk-UA/README.md) | 🇸🇦 [العربية](../ar/README.md) | 🇯🇵 [日本語](../ja/README.md) | 🇻🇳 [Tiếng Việt](../vi/README.md) | 🇧🇬 [Български](../bg/README.md) | 🇩🇰 [Dansk](../da/README.md) | 🇫🇮 [Suomi](../fi/README.md) | 🇮🇱 [עברית](../he/README.md) | 🇭🇺 [Magyar](../hu/README.md) | 🇮🇩 [Bahasa Indonesia](../id/README.md) | 🇰🇷 [한국어](../ko/README.md) | 🇲🇾 [Bahasa Melayu](../ms/README.md) | 🇳🇱 [Nederlands](../nl/README.md) | 🇳🇴 [Norsk](../no/README.md) | 🇵🇹 [Português (Portugal)](../pt/README.md) | 🇷🇴 [Română](../ro/README.md) | 🇵🇱 [Polski](../pl/README.md) | 🇸🇰 [Slovenčina](../sk/README.md) | 🇸🇪 [Svenska](../sv/README.md) | 🇵🇭 [Filipino](../phi/README.md)
-
-
-
----
-
-## 🖼️
-
-
-
- # 🚀 OmniRoute — Gateway-ul gratuit AI
+# 🚀 OmniRoute — The Free AI Gateway (Română)
-### Nu opriți niciodată codificarea. Dirijare inteligentă către **modele AI GRATUITE și cu costuri reduse** cu rezervă automată.
-
-_Proxy-ul dvs. universal API - un punct final, peste 36 de furnizori, zero timpi de nefuncționare._
-
-**Finalizări de chat • Încorporare • Generare de imagini • Audio • Reclasificare • 100% TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Furnizor AI gratuit pentru agenții tăi preferați de codare
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Conectați orice instrument IDE sau CLI alimentat de AI prin OmniRoute — gateway API gratuit pentru codare nelimitată._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+
+
+[](https://www.npmjs.com/package/omniroute)
+[](https://www.npmjs.com/package/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
+[](https://omniroute.online)
+[](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)
+
+
+
+🌐 **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)
+
+---
+
+## 🆕 What's New in v3.0.0
+
+> **Upgrading from v2.9.5?** — See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes.
+
+| Area | Change |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection remediation |
+| ✅ **Route Validation** | All 176 API routes now validated with Zod schemas + `validateBody()` — CI `check:route-validation:t06` passes |
+| 🐛 **omniModel Tag Leak** | Internal `
+
+
+
+---
+
+## 📸 Dashboard Preview
+
+
+
+
+
+---
+
+### 🤖 Free AI Provider for your favorite coding agents
+
+_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._
Click to see dashboard screenshots
+ +| Page | Screenshot | +| -------------- | ------------------------------------------------- | +| **Providers** |  | +| **Combos** |  | +| **Analytics** |  | +| **Health** |  | +| **Translator** |  | +| **Settings** |  | +| **CLI Tools** |  | +| **Usage Logs** |  | +| **Endpoints** |  | + +|
-
+
OpenClaw @@ -92,113 +162,52 @@ _Conectați orice instrument IDE sau CLI alimentat de AI prin OmniRoute — gate |
http://localhost:20128/v1 sau http://cloud.omniroute.online.online/v1 modele și cotă nelimitate
+📡 All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 — one config, unlimited models and quota
---
-### 🆕 What's New in v3.0.0
+## 🤔 Why OmniRoute?
-| Area | Change |
-| ------------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal ` Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `
-
-
-
----
-
-## 📸
-
-
-
-
-
----
-
-## 🤔 De ce OmniRoute?
-
-**Nu mai risipi banii și nu mai atingeți limitele:**
-
-- ...
- -| # | # | -| ----- | ---------------------------------------- | -| **1** |  | -| **2** |  | -| **3** |  | -| **4** |  | -| **5** |  | -| **6** |  | -| **7** |  | -| **8** |  | -| **9** |  | - - Cota de abonament expiră neutilizată în fiecare lună
-- Limitele ratelor te opresc la mijloc de codare
-- API-uri scumpe (20-50 USD/lună per furnizor)
-- Comutare manuală între furnizori
-
-**OmniRoute rezolvă asta:**
-
-- ✅ **Maximizați abonamentele** - Urmăriți cota, utilizați fiecare bit înainte de resetare
-- ✅ **Auto de rezervă** - Abonament → Cheie API → Ieftin → Gratuit, timp de nefuncționare zero
-- ✅ **Multi-cont** - Round-robin între conturi pentru fiecare furnizor
-- ✅ **Universal** - Funcționează cu Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, orice instrument CLI
-
----
-
-## 📧 Suport
-
-> 💬 **Alăturați-vă comunității noastre!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Obțineți ajutor, împărtășiți sfaturi și fiți la curent.
-
-- **Site web**: [omniroute.online](https://omniroute.online)
+- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Probleme**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Proiect original**: [9router by decolua](https://github.com/decolua/9router)
+- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 Cum funcționează
+## 🔄 How It Works
```
┌─────────────┐
@@ -227,453 +236,453 @@ Result: Never stop coding, minimal cost
---
-## 🎯 Ce rezolvă OmniRoute — 30 de puncte reale de durere și cazuri de utilizare
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **Fiecare dezvoltator care folosește instrumente AI se confruntă zilnic cu aceste probleme.** OmniRoute a fost creat pentru a le rezolva pe toate - de la depășiri de costuri la blocaje regionale, de la fluxuri OAuth întrerupte la operațiuni de protocol și observabilitate a întreprinderii.
+> **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.
-
💸 1. „Plătesc pentru un abonament scump, dar tot sunt întrerupt de limite”
+💸 1. "I pay for an expensive subscription but still get interrupted by limits"
-Dezvoltatorii plătesc 20–200 USD/lună pentru Claude Pro, Codex Pro sau GitHub Copilot. Chiar și plătind, cota are un plafon - 5 ore de utilizare, limite săptămânale sau limite de tarif pe minut. La mijlocul sesiunii de codare, furnizorul nu mai răspunde și dezvoltatorul își pierde fluxul și productivitatea. +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. -**Cum o rezolvă OmniRoute:** +**How OmniRoute solves it:** -- **Smart 4-Tier Fallback** — Dacă cota de abonament se epuizează, redirecționează automat la cheia API → Ieftin → Gratuit fără intervenție manuală -- **Urmărirea cotelor în timp real** — Afișează consumul de simboluri în timp real cu numărătoarea inversă de resetare (5 ore, zilnic, săptămânal) -- **Asistență pentru mai multe conturi** — Conturi multiple per furnizor cu turneu automat automat — când unul se epuizează, trece la următorul -- **Combinații personalizate** — Lanțuri de rezervă personalizabile cu 6 strategii de echilibrare (fill-first, round-robin, P2C, aleatoriu, cel mai puțin utilizat, optimizat din punct de vedere al costurilor) -- **Cote de afaceri Codex** — Monitorizarea cotelor de spațiu de lucru pentru afaceri/echipe direct în tabloul de bord +- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention +- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly) +- **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 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
-` de la modele precum DeepSeek R1 în `reasoning_content` standardizat
-- **Ieșire structurată pentru Gemeni** — `json_schema` → `responseMimeType`/`responseSchema` conversie automată
-- **`stream` este implicit `false`** — Se aliniază cu specificațiile OpenAI, evitând SSE neașteptat în SDK-urile Python/Rust/Go
+- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 67+ 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
🔌 2. „Trebuie să folosesc mai mulți furnizori, dar fiecare are un API diferit”
+🔌 2. "I need to use multiple providers but each has a different API"
-OpenAI folosește un format, Claude (Anthropic) folosește altul, Gemini încă altul. Dacă un dezvoltator dorește să testeze modele de la diferiți furnizori sau să se retragă între aceștia, trebuie să reconfigureze SDK-urile, să schimbe punctele finale, să se ocupe de formate incompatibile. Furnizorii personalizați (FriendLI, NIM) au puncte finale de model non-standard. +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. -**Cum o rezolvă OmniRoute:** +**How OmniRoute solves it:** -- **Unified Endpoint** — Un singur `http://localhost:20128/v1` servește drept proxy pentru toți cei 36 de furnizori și mai sus -- **Traducerea formatului** — Automată și transparentă: OpenAI ↔ Claude ↔ Gemeni ↔ Responses API -- **Response Sanitization** — Elimina câmpurile nestandard (`x_groq`, `usage_breakdown`, `service_tier`) care încalcă OpenAI SDK v1.83+ -- **Normalizarea rolurilor** — Convertește `developer` → `system` pentru furnizorii non-OpenAI; `system` → `user` pentru GLM/ERNIE -- **Think Tag Extraction** — Extrage blocurile `
-
🌐 3. „Furnizorul meu AI îmi blochează regiunea/țara”
+🌐 3. "My AI provider blocks my region/country"
-Furnizori precum OpenAI/Codex blochează accesul din anumite regiuni geografice. Utilizatorii primesc erori precum `unsupported_country_region_territory` în timpul conexiunilor OAuth și API. Acest lucru este frustrant în special pentru dezvoltatorii din țările în curs de dezvoltare. +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. -**Cum o rezolvă OmniRoute:** +**How OmniRoute solves it:** -- **3-Level Proxy Config** — Proxy configurabil la 3 niveluri: global (tot traficul), per furnizor (doar un singur furnizor) și per conexiune/cheie -- **Insigne de proxy cu coduri de culoare** — Indicatori vizuali: 🟢 proxy global, 🟡 proxy furnizor, 🔵 proxy de conexiune, indicând întotdeauna IP-ul -- **Schimb de jetoane OAuth prin proxy** — fluxul OAuth trece și prin proxy, rezolvând `unsupported_country_region_territory` -- **Teste de conexiune prin proxy** — Testele de conexiune folosesc proxy-ul configurat (nu mai este ocolire directă) -- **Support SOCKS5** — Suport complet SOCKS5 proxy pentru rutarea de ieșire -- **TLS Fingerprint Spoofing** — Amprenta TLS asemănătoare unui browser prin `wreq-js` pentru a ocoli detectarea botului +- **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
-` prefix
-- **Combinații numai gratuite** — Lanțul `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = 0 USD/lună fără timp de nefuncționare
-- **Credite gratuite NVIDIA NIM** — 1000 de credite gratuite integrate
-- **Cost Optimized Strategy** — Strategie de rutare care alege automat cel mai ieftin furnizor disponibil
+- **Free-Only Combos** — Chain `gc/gemini-3-flash → 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
🆓 4. „Vreau să folosesc AI pentru codare, dar nu am bani”
+🆓 4. "I want to use AI for coding but I have no money"
-Nu toată lumea poate plăti 20–200 USD/lună pentru abonamentele AI. Studenții, dezvoltatorii din țările emergente, pasionații și freelancerii au nevoie de acces la modele de calitate la cost zero. +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. -**Cum o rezolvă OmniRoute:** +**How OmniRoute solves it:** -- **Free Tier Providers Built-in** — Suport nativ pentru furnizori 100% gratuiti: iFlow (8 modele nelimitate), Qwen (3 modele nelimitate), Kiro (Claude gratuit), Gemini CLI (180K/lună gratuit) +- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free) - **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/
-
🔒 5. „Trebuie să-mi protejez poarta AI de accesul neautorizat”
+🔒 5. "I need to protect my AI gateway from unauthorized access"
-Când expuneți un gateway AI în rețea (LAN, VPS, Docker), oricine are adresa poate consuma jetoanele/cota dezvoltatorului. Fără protecție, API-urile sunt vulnerabile la utilizare greșită, injectare promptă și abuz. +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. -**Cum o rezolvă OmniRoute:** +**How OmniRoute solves it:** -- **Gestionarea cheilor API** — Generare, rotație și definire pentru fiecare furnizor cu o pagină dedicată `/dashboard/api-manager` -- **Permisiuni la nivel de model** — Restricționați cheile API la anumite modele (`openai/*`, modele cu caractere metalice), cu comutatorul Permite toate/Restricționați -- **API Endpoint Protection** — Solicitați o cheie pentru `/v1/models` și blocați anumiți furnizori din listă -- **Auth Guard + CSRF Protection** — Toate rutele tabloului de bord sunt protejate cu middleware `withAuth` + jetoane CSRF -- **Rate Limiter** — Limitarea ratei per-IP cu ferestre configurabile -- **Filtrare IP** — Lista permisă/lista blocată pentru controlul accesului -- **Prompt Injection Guard** — Igienizare împotriva tiparelor de prompte rău intenționate -- **Criptare AES-256-GCM** — Acreditări criptate în repaus +- **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. „Furnizorul meu a căzut și mi-am pierdut fluxul de codare”
+🛑 6. "My provider went down and I lost my coding flow"
-Furnizorii de AI pot deveni instabili, pot returna erori 5xx sau pot atinge limitele temporare ale ratei. Dacă un dezvoltator depinde de un singur furnizor, acesta este întrerupt. Fără întreruptoare, reîncercări repetate pot bloca aplicația. +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. -**Cum o rezolvă OmniRoute:** +**How OmniRoute solves it:** -- **Circuit Breaker per furnizor** - Deschidere/închidere automată cu praguri configurabile și răcire (Închis/Deschis/Pe jumătate deschis) - | 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format | -- **Backoff exponențial** — Întârzieri progresive ale reîncercării -- **Anti-Thundering Herd** — Mutex + protecție semafor împotriva furtunilor concurente de reîncercare -- **Combo Fallback Chains** — Dacă furnizorul principal eșuează, trece automat prin lanț fără nicio intervenție -- **Combo Circuit Breaker** — Dezactivează automat furnizorii care eșuează dintr-un lanț combinat - | 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format | -- **Tabloul de bord pentru sănătate** — Monitorizare timp de funcționare, stări întrerupătoare de circuit, blocări, statistici cache, latență p50/p95/p99 +- **Circuit Breaker per-model** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks +- **Exponential Backoff** — Progressive retry delays +- **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 +- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain +- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
-
🔧 7. „Configurarea fiecărui instrument AI este plictisitoare și repetitivă”
+🔧 7. "Configuring each AI tool is tedious and repetitive"
-Dezvoltatorii folosesc Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Fiecare instrument are nevoie de o configurație diferită (punct final API, cheie, model). Reconfigurarea la schimbarea de furnizor sau de model este o pierdere de timp. +Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time. -**Cum o rezolvă OmniRoute:** +**How OmniRoute solves it:** -- **CLI Tools Dashboard** — pagină dedicată cu setare cu un singur clic pentru Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline -- **GitHub Copilot Config Generator** — generează `chatLanguageModels.json` pentru VS Code cu selecția în bloc a modelului -- **Onboarding Wizard** — Configurare ghidată în 4 pași pentru utilizatorii debutanți -- **Un punct final, toate modelele** — Configurați `http://localhost:20128/v1` o dată, accesați peste 36 de furnizori +- **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 67+ providers
-
🔑 8. „Gestionarea jetoanelor OAuth de la mai mulți furnizori este un iad”
+🔑 8. "Managing OAuth tokens from multiple providers is hell"
-Claude Code, Codex, Gemini CLI, Copilot - toate folosesc OAuth 2.0 cu token-uri care expiră. Dezvoltatorii trebuie să se reautentifice în mod constant, să se ocupe de `client_secret is missing`, `redirect_uri_mismatch` și defecțiunile de pe serverele de la distanță. OAuth pe LAN/VPS este deosebit de problematică. +Claude Code, Codex, Gemini CLI, 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. -**Cum o rezolvă OmniRoute:** +**How OmniRoute solves it:** -- **Reîmprospătare automată a simbolurilor** — jetoanele OAuth se reîmprospătează în fundal înainte de expirare -- **OAuth 2.0 (PKCE) încorporat** — Flux automat pentru Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow -- **OAuth cu mai multe conturi** — Conturi multiple per furnizor prin extragerea jetonului JWT/ID -- **OAuth LAN/Remediere la distanță** — Detectare IP privată pentru `redirect_uri` + modul URL manual pentru servere la distanță -- **OAuth în spatele Nginx** — Utilizează `window.location.origin` pentru compatibilitatea cu proxy invers -- **Ghid OAuth la distanță** — Ghid pas cu pas pentru acreditările Google Cloud pe VPS/Docker +- **Auto Token Refresh** — OAuth tokens refresh in background before expiration +- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow +- **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. „Nu știu cât cheltuiesc sau unde”
+📊 9. "I don't know how much I'm spending or where"
-Dezvoltatorii folosesc mai mulți furnizori plătiți, dar nu au o viziune unificată asupra cheltuielilor. Fiecare furnizor are propriul tablou de bord de facturare, dar nu există o vizualizare consolidată. Costurile neașteptate se pot acumula. +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. -**Cum o rezolvă OmniRoute:** +**How OmniRoute solves it:** -- **Tabloul de bord pentru analiza costurilor** — Urmărirea costurilor pe token și gestionarea bugetului per furnizor -- **Limite bugetare pe nivel** — Plafonul de cheltuieli pe nivel care declanșează o rezervă automată -- **Configurație de preț pe model** — Prețuri configurabile pe model -- **Statistici de utilizare per cheie API** — Numărul de solicitări și marcajul temporal al ultimei utilizări per cheie -- **Tabloul de bord de analiză** — Carduri cu statistici, diagramă de utilizare a modelului, tabel cu furnizori cu rate de succes și latență +- **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. „Nu pot diagnostica erorile și problemele în apelurile AI”
+🐛 10. "I can't diagnose errors and problems in AI calls"
-Când un apel eșuează, dezvoltatorul nu știe dacă a fost o limită de rată, un simbol expirat, un format greșit sau o eroare a furnizorului. Jurnalele fragmentate pe diferite terminale. Fără observabilitate, depanarea este o încercare și eroare. +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. -**Cum o rezolvă OmniRoute:** +**How OmniRoute solves it:** -- **Tabloul de bord pentru jurnalele unificate** — 4 file: jurnalele de solicitare, jurnalele proxy, jurnalele de audit, consolă -- **Console Log Viewer** — Vizualizator în timp real în stil terminal cu niveluri codificate în culori, defilare automată, căutare, filtru -- **SQLite Proxy Logs** — Jurnale persistente care supraviețuiesc repornirilor serverului -- **Translator Playground** — 4 moduri de depanare: Playground (traducere format), Chat Tester (dus-întors), Test Bench (lot), Live Monitor (în timp real) -- **Solicitare telemetrie** — latență p50/p95/p99 + urmărire X-Request-Id -- **Înregistrare bazată pe fișiere cu rotație** — Interceptor de consolă captează totul în jurnalul JSON cu rotație bazată pe dimensiune +- **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 Proxy Logs** — Persistent logs that survive server restarts +- **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 Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation +- **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. „Implementarea și întreținerea gateway-ului este complexă”
+🏗️ 11. "Deploying and maintaining the gateway is complex"
-Instalarea, configurarea și menținerea unui proxy AI în diferite medii (local, VPS, Docker, cloud) necesită multă muncă. Probleme precum căile codificate hard, `EACCES` pe directoare, conflictele de porturi și versiunile pe mai multe platforme adaugă fricțiuni. +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. -**Cum o rezolvă OmniRoute:** +**How OmniRoute solves it:** -- **npm global install** — `npm install -g omniroute && omniroute` — finalizat -- **Docker Multi-Platform** - AMD64 + ARM64 nativ (Apple Silicon, AWS Graviton, Raspberry Pi) -- **Docker Compose Profiles** — `base` (fără instrumente CLI) și `cli` (cu Claude Code, Codex, OpenClaw) -- **Electron Desktop App** — aplicație nativă pentru Windows/macOS/Linux cu bară de sistem, pornire automată, mod offline -- **Split-Port Mode** — API și tablou de bord pe porturi separate pentru scenarii avansate (reverse proxy, rețea container) -- **Cloud Sync** — Configurați sincronizarea între dispozitive prin Cloudflare Workers -- **Backups DB** — Backup automat, restaurare, export și import al tuturor setărilor +- **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
-
🌍 12. „Interfața este doar în limba engleză și echipa mea nu vorbește engleză”
+🌍 12. "The interface is English-only and my team doesn't speak English"
-Echipele din țările care nu vorbesc engleza, în special din America Latină, Asia și Europa, se luptă cu interfețele doar în limba engleză. Barierele lingvistice reduc adoptarea și cresc erorile de configurare. +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. -**Cum o rezolvă OmniRoute:** +**How OmniRoute solves it:** -- **Tabloul de bord i18n — 30 de limbi** — Toate cele peste 500 de taste traduse, inclusiv arabă, bulgară, daneză, germană, spaniolă, finlandeză, franceză, ebraică, hindi, maghiară, indoneziană, italiană, japoneză, coreeană, malay, olandeză, norvegiană, poloneză, portugheză (PT/BR), română, rusă, slovacă, suedeză, thailandeză, ucraineană, filipineză, engleză, chineză, vietnameză, -- ** Suport RTL** — Suport de la dreapta la stânga pentru arabă și ebraică -- **ReadME-uri în mai multe limbi** — 30 de traduceri complete de documentație -- **Selector de limbă** — Pictograma glob în antet pentru comutare în timp real +- **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. „Am nevoie de mai mult decât de chat — am nevoie de încorporare, imagini, audio”
+🔄 13. "I need more than chat — I need embeddings, images, audio"
-AI nu este doar finalizarea chatului. Dezvoltatorii trebuie să genereze imagini, să transcrie sunetul, să creeze înglobări pentru RAG, să reclasifice documentele și să modereze conținutul. Fiecare API are un punct final și un format diferit. +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. -**Cum o rezolvă OmniRoute:** +**How OmniRoute solves it:** -- **Embeddings** — `/v1/embeddings` cu 6 furnizori și peste 9 modele -- **Generarea imaginii** — `/v1/images/generations` cu 10 furnizori și peste 20 de modele (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI) -- **Text-to-Video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) și SD WebUI +- **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) -- **Transcriere audio** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3 -- **Text-to-Speech** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, Inworld, Cartesia, PlayHT, + furnizori existenți -- **Moderări** — `/v1/moderations` — Verificări de siguranță a conținutului -- **Reclasificare** — `/v1/rerank` — Reclasificarea relevanței documentului -- **Responses API** — Suport complet `/v1/responses` pentru Codex +- **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. „Nu am cum să testez și să compar calitatea între modele”
+🧪 14. "I have no way to test and compare quality across models"
-Dezvoltatorii vor să știe care model este cel mai bun pentru cazul lor de utilizare - cod, traducere, raționament - dar compararea manuală este lentă. Nu există instrumente de evaluare integrate. +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. -**Cum o rezolvă OmniRoute:** +**How OmniRoute solves it:** -- **Evaluări LLM** — Testarea setului de aur cu 10 cazuri preîncărcate care acoperă salutări, matematică, geografie, generare de cod, conformitate cu JSON, traducere, reducere, refuz de siguranță -- **4 strategii de potrivire** — `exact`, `contains`, `regex`, `custom` (funcția JS) -- **Translator Playground Test Bench** — Testare în loturi cu mai multe intrări și rezultate așteptate, comparație între furnizori -- **Tester de chat** — Tur complet dus-întors cu randare vizuală a răspunsului -- **Live Monitor** — Flux în timp real al tuturor solicitărilor care circulă prin proxy +- **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. „Trebuie să mă scalez fără a pierde performanța”
+📈 15. "I need to scale without losing performance"
-Pe măsură ce volumul cererilor crește, fără memorarea în cache aceleași întrebări generează costuri duplicate. Fara idempotenta, cererile duplicate procesarea deseurilor. Limitele de tarife pentru fiecare furnizor trebuie respectate. +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. -**Cum o rezolvă OmniRoute:** +**How OmniRoute solves it:** -- **Cache semantic** — Cache-ul pe două niveluri (semnătură + semantică) reduce costurile și latența -- **Request Idempotency** — fereastră de deduplicare 5s pentru cereri identice -- **Rate Limit Detection** — RPM per furnizor, interval minim și urmărire simultană maximă -- **Limite de rată editabile** — Valori implicite configurabile în Setări → Reziliență cu persistență -- **API Key Validation Cache** — cache pe 3 niveluri pentru performanța producției -- **Tabloul de bord pentru sănătate cu telemetrie** — latență p50/p95/p99, statistici cache, timp de funcționare +- **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 +- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence +- **API Key Validation Cache** — 3-tier cache for production performance +- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
-
🤖 16. „Vreau să controlez comportamentul modelului la nivel global”
+🤖 16. "I want to control model behavior globally"
-Dezvoltatori care doresc toate răspunsurile într-o anumită limbă, cu un anumit ton sau care doresc să limiteze simbolurile de raționament. Configurarea acestui lucru în fiecare instrument/cerere nu este practică. +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. -**Cum o rezolvă OmniRoute:** +**How OmniRoute solves it:** -- **System Prompt Injection** — Prompt global aplicat tuturor solicitărilor -- **Thinking Budget Validation** — Controlul raționării alocării token-ului per cerere (transmis, automat, personalizat, adaptiv) -- **6 Strategii de rutare** — Strategii globale care determină modul în care sunt distribuite cererile -- **Wildcard Router** — modelele `provider/*` sunt direcționate dinamic către orice furnizor -- **Combo Activare/Dezactivare Comutare** — Comută combo direct din tabloul de bord -- **Comutare furnizor** — Activați/dezactivați toate conexiunile pentru un furnizor cu un singur clic -- **Furnizori blocați** — Excludeți anumiți furnizori din lista `/v1/models` +- **System Prompt Injection** — Global prompt applied to all requests +- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive) +- **6 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 +- **Provider Toggle** — Enable/disable all connections for a provider with one click +- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
-
🧰 17. „Am nevoie de instrumente MCP ca capabilități de produs de primă clasă”
+🧰 17. "I need MCP tools as first-class product capabilities"
-Multe gateway-uri AI expun MCP doar ca un detaliu ascuns de implementare. Echipele au nevoie de un nivel de operare vizibil și ușor de gestionat. +Many AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer. -**Cum o rezolvă OmniRoute:** +**How OmniRoute solves it:** -- MCP apare în panoul de bord de navigare și fila de protocol final -- Pagina de management MCP dedicată cu proces, instrumente, domenii și audit -- Pornire rapidă încorporată pentru `omniroute --mcp` și integrarea clientului +- 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. „Am nevoie de orchestrare A2A cu sincronizare + căi de activități de flux”
+🧠 18. "I need A2A orchestration with sync + stream task paths"
-Fluxurile de lucru ale agenților necesită atât răspunsuri directe, cât și execuție în flux de lungă durată, cu control ciclului de viață. +Agent workflows need both direct replies and long-running streamed execution with lifecycle control. -**Cum o rezolvă OmniRoute:** +**How OmniRoute solves it:** -- Punct final A2A JSON-RPC (`POST /a2a`) cu `message/send` și `message/stream` -- Streaming SSE cu propagare a stării terminale -- API-uri pentru ciclul de viață al sarcinilor pentru `tasks/get` și `tasks/cancel` +- 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. „Am nevoie de sănătate reală a procesului MCP, nu de stare ghicită”
+🛰️ 19. "I need real MCP process health, not guessed status"
-Echipele operaționale trebuie să știe dacă MCP este de fapt în viață, nu doar dacă un API este accesibil. +Operational teams need to know if MCP is actually alive, not just whether an API is reachable. -**Cum o rezolvă OmniRoute:** +**How OmniRoute solves it:** -- Fișier runtime heartbeat cu PID, marcaje de timp, transport, număr de instrumente și modul de aplicare -- API de stare MCP care combină bătăile inimii + activitatea recentă -- Carduri de stare a interfeței de utilizare pentru prospețimea procesului/uptime/inima +- 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. „Am nevoie de o execuție auditabilă a instrumentului MCP”
+📋 20. "I need auditable MCP tool execution"
-Când instrumentele modifică configurația sau declanșează acțiuni operaționale, echipele au nevoie de trasabilitate criminalistică. +When tools mutate config or trigger ops actions, teams need forensic traceability. -**Cum o rezolvă OmniRoute:** +**How OmniRoute solves it:** -- Înregistrare de audit susținută de SQLite pentru apelurile instrumentelor MCP -- Filtrează după instrument, succes/eșec, cheie API și paginare -- Tabelul de audit al tabloului de bord + punctele finale de statistici pentru automatizare +- 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. „Am nevoie de permisiuni MCP pentru fiecare integrare”
+🔐 21. "I need scoped MCP permissions per integration"
-Clienții diferiți ar trebui să aibă cel mai mic privilegiu de acces la categoriile de instrumente. +Different clients should have least-privilege access to tool categories. -**Cum o rezolvă OmniRoute:** +**How OmniRoute solves it:** -- 9 lunete MCP granulare pentru acces controlat la instrumente -- Aplicarea domeniului de aplicare și vizibilitatea în interfața de utilizare a managementului MCP -- Poziție implicită sigură pentru instrumentele operaționale +- 9 granular MCP scopes for controlled tool access +- Scope enforcement and visibility in MCP management UI +- Safe default posture for operational tooling
-
⚙️ 22. „Am nevoie de controale operaționale fără redistribuire”
+⚙️ 22. "I need operational controls without redeploying"
-Echipele au nevoie de modificări rapide ale timpului de rulare în timpul incidentelor sau evenimentelor de cost. +Teams need quick runtime changes during incidents or cost events. -**Cum o rezolvă OmniRoute:** +**How OmniRoute solves it:** -- Comutați activarea comboi direct din tabloul de bord MCP -- Aplicați profiluri de rezistență din pachetele de politici predefinite -- Resetați starea întreruptorului de la același panou de operare +- Switch combo activation directly from MCP dashboard +- Apply resilience profiles from pre-defined policy packs +- Reset circuit breaker state from the same operations panel
-
🔄 23. „Am nevoie de vizibilitate și anulare a ciclului de viață a sarcinii A2A live”
+🔄 23. "I need live A2A task lifecycle visibility and cancellation"
-Fără vizibilitatea ciclului de viață, incidentele sarcinilor devin greu de triat. +Without lifecycle visibility, task incidents become hard to triage. -**Cum o rezolvă OmniRoute:** +**How OmniRoute solves it:** -- Listarea sarcinilor/filtrarea după stare/abilitate cu paginare -- Detaliați metadatele sarcinii, evenimentele și artefactele -- Punct final de anulare a sarcinii și acțiune UI cu confirmare +- 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. „Am nevoie de valori de flux active pentru încărcarea A2A”
+🌊 24. "I need active stream metrics for A2A load"
-Fluxurile de lucru în flux necesită o perspectivă operațională privind concurența și conexiunile live. +Streaming workflows require operational insight into concurrency and live connections. -**Cum o rezolvă OmniRoute:** +**How OmniRoute solves it:** -- Contoare active de flux integrate în starea A2A -- Marcaj de timp pentru ultima sarcină și numărătoare pentru fiecare stat -- Carduri de bord A2A pentru monitorizarea operațiunilor în timp real +- Active stream counters integrated into A2A status +- Last task timestamp and per-state counts +- A2A dashboard cards for real-time ops monitoring
-
🪪 25. „Am nevoie de descoperire de agenți standard pentru clienți”
+🪪 25. "I need standard agent discovery for clients"
-Clienții externi și orchestratorii au nevoie de metadate care pot fi citite de mașină pentru integrare. +External clients and orchestrators need machine-readable metadata for onboarding. -**Cum o rezolvă OmniRoute:** +**How OmniRoute solves it:** -- Card de agent expus la `/.well-known/agent.json` -- Capacități și abilități afișate în UI de management -- API-ul de stare A2A include metadate de descoperire pentru automatizare +- Agent Card exposed at `/.well-known/agent.json` +- Capabilities and skills shown in management UI +- A2A status API includes discovery metadata for automation
-
🧭 26. „Am nevoie de descoperirea protocolului în produsul UX”
+🧭 26. "I need protocol discoverability in the product UX"
-Dacă utilizatorii nu pot descoperi suprafețele de protocol, calitatea adoptării și a suportului scade. +If users cannot discover protocol surfaces, adoption and support quality drop. -**Cum o rezolvă OmniRoute:** +**How OmniRoute solves it:** -- Intrări din bara laterală pentru MCP și A2A -- Pagina Endpoint Fila Protocoale cu pornire rapidă și stare -- Link-uri de la prezentare generală la tablouri de bord dedicate de management +- 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. „Am nevoie de validarea protocolului end-to-end cu clienți reali”
+🧪 27. "I need end-to-end protocol validation with real clients"
-Testele simulate nu sunt suficiente pentru a valida compatibilitatea protocolului înainte de lansare. +Mock tests are not enough to validate protocol compatibility before release. -**Cum o rezolvă OmniRoute:** +**How OmniRoute solves it:** -- Suita E2E care pornește aplicația și utilizează transportul clientului MCP SDK real -- Testele client A2A pentru descoperirea, trimiterea, transmiterea în flux, obținerea și anularea fluxurilor -- Verificați încrucișați afirmațiile cu auditul MCP și API-urile pentru sarcini A2A +- 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. „Am nevoie de observabilitate unificată pe toate interfețele”
+📡 28. "I need unified observability across all interfaces"
-Împărțirea observabilității în funcție de protocol creează puncte oarbe și MTTR mai lung. +Splitting observability by protocol creates blind spots and longer MTTR. -**Cum o rezolvă OmniRoute:** +**How OmniRoute solves it:** -- Tablouri de bord/jurnale/analitice unificate într-un singur produs -- Sănătate + audit + solicitare de telemetrie în straturi OpenAI, MCP și A2A -- API-uri operaționale pentru stare și automatizare +- Unified dashboards/logs/analytics in one product +- Health + audit + request telemetry across OpenAI, MCP, and A2A layers +- Operational APIs for status and automation
-
💼 29. „Am nevoie de un timp de rulare pentru proxy + instrumente + orchestrare agent”
+💼 29. "I need one runtime for proxy + tools + agent orchestration"
-Rularea multor servicii separate crește costurile operaționale și modurile de eșec. +Running many separate services increases operational cost and failure modes. -**Cum o rezolvă OmniRoute:** +**How OmniRoute solves it:** -- Proxy compatibil OpenAI, server MCP și server A2A într-o singură stivă -- Autentificare partajată, rezistență, stocare de date și observabilitate -- Model de politică consistent pe toate suprafețele de interacțiune +- 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
-
-### Exemple de manuale (cazuri de utilizare integrate)
+### Example Playbooks (Integrated Use Cases)
-**Playbook A: Maximizați abonamentul plătit + backup ieftin**
+**Playbook A: Maximize paid subscription + cheap backup**
```txt
Combo: "maximize-claude"
@@ -685,7 +694,7 @@ Monthly cost: $20 + small backup spend
Outcome: higher quality, near-zero interruption
```
-**Playbook B: teanc de codare cu costuri zero**
+**Playbook B: Zero-cost coding stack**
```txt
Combo: "free-forever"
@@ -697,7 +706,7 @@ Monthly cost: $0
Outcome: stable free coding workflow
```
-**Playbook C: lanț alternativ permanent activ 24/7**
+**Playbook C: 24/7 always-on fallback chain**
```txt
Combo: "always-on"
@@ -710,65 +719,132 @@ Combo: "always-on"
Outcome: deep fallback depth for deadline-critical workloads
```
-**Playbook D: Agentul operează cu MCP + A2A**
+**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/mcp and /dashboard/a2a
-4) Control incidents with resilience profile + task cancellation
+3) Observe via /dashboard/endpoint (MCP and A2A tabs)
+4) Toggle services via inline status controls
```
---
-## ⚡ Pornire rapidă
+## 🆓 Start Free — Zero Configuration Cost
-**1. Instalați la nivel global:**
+> 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 **iFlow** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |
+| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |
+| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |
+| 5 | `/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).
+
+## Pornire rapidă
+
+### 1) Install and run
```bash
npm install -g omniroute
omniroute
```
-🎉 Tabloul de bord se deschide la `http://localhost:20128`
+> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:
+>
+> ```bash
+> pnpm install -g omniroute
+> pnpm approve-builds -g # Select all packages → approve
+> omniroute
+> ```
-| Comanda | Descriere |
-| ----------------------- | ---------------------------------------- |
-| `omniroute` | Porniți serverul (portul implicit 20128) |
-| `omniroute --port 3000` | Utilizați portul personalizat |
-| `omniroute --no-open` | Nu deschideți automat browserul |
-| `omniroute --help` | Arată ajutor |
+Dashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.
-**2. Conectați un furnizor GRATUIT:**
+| 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 |
-Tabloul de bord → Furnizori → Conectare **Claude Code** sau **Antigravity** → Conectare OAuth → Gata!
+Optional split-port mode:
-**3. Utilizați în instrumentul dvs. CLI:**
-
-```
-Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Settings:
- Endpoint: http://localhost:20128/v1
- API Key: [copy from dashboard]
- Model: if/kimi-k2-thinking
+```bash
+PORT=20128 DASHBOARD_PORT=20129 omniroute
+# API: http://localhost:20128/v1
+# Dashboard: http://localhost:20129
```
-**Asta este!** Începeți să codați cu modele AI GRATUITE.
+### 2) Connect providers and create your API key
-**Alternativă - rulează de la sursă:**
+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
+
+```txt
+Base URL: http://localhost:20128/v1
+API Key: [copy from Endpoint page]
+Model: if/kimi-k2-thinking (or any provider/model prefix)
+```
+
+Works with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.
+
+### 4) Enable and validate protocols (v2.0)
+
+**MCP (for tool-driven operations):**
+
+```bash
+omniroute --mcp
+```
+
+Then connect your MCP client over `stdio` and test tools like:
+
+- `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 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
+PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev
```
---
## 🐳 Docker
-OmniRoute este disponibil ca imagine publică Docker pe [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
+OmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
-**Alergare rapidă:**
+**Quick run:**
```bash
docker run -d \
@@ -779,7 +855,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Cu fișierul de mediu:**
+**With environment file:**
```bash
# Copy and edit .env first
@@ -794,7 +870,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Utilizarea Docker Compose:**
+**Using Docker Compose:**
```bash
# Base profile (no CLI tools)
@@ -804,258 +880,552 @@ docker compose --profile base up -d
docker compose --profile cli up -d
```
-| Imagine | Etichetă | Dimensiune | Descriere |
-| ------------------------ | -------- | ---------- | ----------------------- |
-| `diegosouzapw/omniroute` | `latest` | ~250MB | Ultima versiune stabilă |
-| `diegosouzapw/omniroute` | `1.0.3` | ~250MB | Versiunea curentă |
+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.
+- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.
+- 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` | `1.0.3` | ~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
+### Pornire rapidă
+
```bash
-npm run electron:dev # Development mode
+# 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)
+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)
---
-## 💰 Prețurile dintr-o privire
+## 💰 Pricing at a Glance
-| Nivelul | Furnizor | Cost | Resetare cotă | Cel mai bun pentru |
-| ---------------- | ----------------- | ---------------------------- | --------------------------- | ------------------------- |
-| **💳 ABONARE** | Claude Code (Pro) | 20 USD/lună | 5h + săptămânal | Deja abonat |
-| | Codex (Plus/Pro) | 20-200 USD/lună | 5h + săptămânal | Utilizatori OpenAI |
-| | Gemeni CLI | **GRATIS** | 180K/lună + 1K/zi | Toată lumea! |
-| | GitHub Copilot | 10-19 USD/lună | Lunar | utilizatorii GitHub |
-| **🔑 CHEIA API** | NVIDIA NIM | **GRATIS** (1000 de credite) | O singură dată | Testare gratuită la nivel |
-| | DeepSeek | Plată-pe-utilizare | Niciuna | Cel mai bun preț/calitate |
-| | Groq | Nivel gratuit + plătit | Tarif limitat | Inferență ultra-rapidă |
-| | xAI (Grok) | Plată-pe-utilizare | Niciuna | Modele Grok |
-| | Mistral | Nivel gratuit + plătit | Tarif limitat | IA europeană |
-| | OpenRouter | Plată-pe-utilizare | Niciuna | 100+ modele |
-| **💰 IEFTIN** | GLM-4.7 | 0,6 USD/1 milion | Zilnic 10:00 | Backup buget |
-| | MiniMax M2.1 | 0,2 USD/1 milion | rulare de 5 ore | Cea mai ieftină opțiune |
-| | Kimi K2 | 9 USD/lună plat | 10 milioane de jetoane/lună | Cost previzibil |
-| **🆓 GRATUIT** | iFlow | $0 | Nelimitat | 8 modele gratuite |
-| | Qwen | $0 | Nelimitat | 3 modele gratuite |
-| | Kiro | $0 | Nelimitat | Claude liber |
+| 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 |
+| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |
+| | 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** | iFlow | **$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 |
-**💡 Sfat profesionist:** Începeți cu Gemini CLI (180K gratuit/lună) + iFlow (gratuit nelimitat) combo = cost 0 USD!
+> 🆕 **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
+iFlow (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.
---
-## 💡 Caracteristici cheie
+---
-### 🧠 Core Routing & Intelligence
+## 🆓 Free Models — What You Actually Get
-| Caracteristica | Ce face |
-| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| 🎯 **Backback inteligent pe 4 niveluri** | Rută automată: Abonament → Cheie API → Ieftin → Gratuit |
-| 📊 **Urmărirea cotelor în timp real** | Numărătoare de jetoane live + numărătoare inversă de resetare per furnizor |
-| 🔄 **Traducerea formatului** | OpenAI ↔ Claude ↔ Gemeni ↔ Cursor ↔ Kiro fără întreruperi + dezinfectare răspuns |
-| 👥 **Asistență pentru mai multe conturi** | Conturi multiple per furnizor cu selecție inteligentă |
-| 🔄 **Reîmprospătare automată a simbolului** | Tokenurile OAuth se reîmprospătează automat cu reîncercarea |
-| 🎨 **Combinații personalizate** | 6 strategii: fill-first, round-robin, p2c, aleatoriu, cel mai puțin utilizat, optimizat din punct de vedere al costurilor |
-| 🧩 **Modele personalizate** | Adăugați orice ID de model oricărui furnizor |
-| 🌐 **Wildcard Router** | Dirijați dinamic modelele `provider/*` către orice furnizor |
-| 🧠 **Buget de gândire** | Moduri de trecere, automat, personalizat și adaptiv pentru modelele de raționament |
-| 🔀 **Model Aliases** | Auto-forward deprecated model IDs to current replacements (built-in + custom) |
-| ⚡ **Background Degradation** | Auto-route background tasks (titles, summaries) to cheaper models |
-| 💬 **System Prompt Injection** | Prompt de sistem global aplicat pentru toate solicitările |
-| 📄 **Responses API** | Compatibilitate completă cu OpenAI Responses API (`/v1/responses`) pentru Codex |
+> 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.
-### 🎵 API-uri multimodale
+### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)
-| Caracteristica | Ce face |
-| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 🖼️ **Generarea imaginii** | `/v1/images/generations` — 4 furnizori, peste 9 modele |
-| 📐 **Inglobări** | `/v1/embeddings` — 6 furnizori, peste 9 modele |
-| 🎤 **Transcriere audio** | `/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) |
-| 🛡️ **Moderații** | `/v1/moderations` — Verificări de siguranță a conținutului |
-| 🔀 **Reclasificare** | `/v1/rerank` — Reclasificarea relevanței documentului |
+| 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 |
-### 🛡️ Reziliență și securitate
+### 🟢 IFLOW MODELS (Free OAuth — No Credit Card)
-| Caracteristica | Ce face |
-| -------------------------------------- | -------------------------------------------------------------------------------------- |
-| 🔌 **Disjunctor** | Deschidere/închidere automată pentru fiecare furnizor cu praguri configurabile |
-| 🛡️ **Turmă Anti-Tunete** | Limită de rată Mutex + semafor pentru furnizorii de chei API |
-| 🧠 **Cache semantic** | Cache-ul pe două niveluri (semnătură + semantică) reduce costurile și latența |
-| ⚡ **Solicita Idempotenta** | Fereastra de dedup 5s pentru cereri duplicate |
-| 🔒 **TLS Fingerprint Spoofing** | Ocoliți detectarea botului bazată pe TLS prin wreq-js |
-| 🔏 **CLI Fingerprint Matching** | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP** |
-| 🌐 **Filtrare IP** | Lista permisă/lista blocată pentru controlul accesului API |
-| 📊 **Limite de rată editabile** | RPM configurabil, interval minim și concurență maximă la nivel de sistem |
-| 💾 **Rate Limit Persistence** | Learned limits survive restarts via SQLite with 60s debounce + 24h staleness |
-| 🔄 **Token Refresh Resilience** | Per-provider circuit breaker (5 fails→30min) + 30s timeout per attempt |
-| 🛡 **Protecție API Endpoint** | Autentificare + blocare furnizor pentru punctul final `/models` |
-| 🔒 **Vizibilitatea proxy** | Ecusoane cu coduri de culoare: 🟢 global, 🟡 furnizor, 🔵 per conexiune cu afișaj IP |
-| 🌐 **Configurare proxy pe 3 niveluri** | Configurați proxy-uri la nivel global, per furnizor sau per conexiune |
+| 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 |
-### 📊 Observabilitate și analiză
+### 🟡 QWEN MODELS (Device Code Auth)
-| Caracteristica | Ce face |
-| -------------------------------------- | ------------------------------------------------------------------------------------------------- |
-| 📝 **Solicitare înregistrare** | Modul de depanare cu jurnalele complete de cereri/răspuns |
-| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |
-| 💾 **Jurnale proxy SQLite** | Jurnalele proxy persistente supraviețuiesc repornirilor de server |
-| 📊 **Tabloul de bord de analiză** | Recharts-powered: carduri cu statistici, diagramă de utilizare a modelului, tabel furnizor |
-| 📈 **Urmărirea progresului** | Înscrieți-vă evenimentele de progres SSE pentru streaming |
-| 🧪 **Evaluări LLM** | Testarea setului de aur cu 4 strategii de meci |
-| 🔍 **Solicitare telemetrie** | agregare latență p50/p95/p99 + urmărire X-Request-Id |
-| 📋 **Tabloul de bord jurnal** | Pagina unificată cu 4 file: Jurnalele de solicitări, Jurnalele proxy, Jurnalele de audit, Consolă |
-| 🖥️ **Console Log Viewer** | Vizualizator în timp real în stil terminal cu filtru de nivel, căutare, defilare automată |
-| 📑 **Înregistrare pe bază de fișiere** | Interceptor de consolă captează toate ieșirile în fișierul jurnal JSON cu rotație |
-| 🏥 **Tabloul de bord pentru sănătate** | Timp de funcționare a sistemului, stări întrerupătoare, blocări, statistici cache |
-| 💰 **Urmărirea costurilor** | Gestionarea bugetului + configurarea prețurilor pe model |
+| 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) |
-### ☁️ Implementare și sincronizare
+### 🟣 GEMINI CLI (Google OAuth)
-| Caracteristica | Ce face |
-| ------------------------------------- | ------------------------------------------------------------------------------- |
-| 💾 **Cloud Sync** | Sincronizați configurația între dispozitive prin Cloudflare Workers |
-| 🌐 **Implementează oriunde** | Localhost, VPS, Docker, lucrători Cloudflare |
-| 🔑 **Administrarea cheilor API** | Generați, rotiți și stabiliți cheile API pentru fiecare furnizor |
-| 🧙 **Onboarding Wizard** | Configurare ghidată în 4 pași pentru utilizatorii debutanți |
-| 🔧 **Tabloul de bord CLI Tools** | Configurați cu un singur clic Claude, Codex, Cline, OpenClaw, Kilo, Antigravity |
-| 🔄 **Backup-uri DB** | Backup automat, restaurare, export și import pentru toate setările |
-| 🌐 **Internaționalizare** | I18n complet cu next-intl — suport engleză + portugheză (Brazilia) |
-| 🌍 **Selector de limbă** | Pictograma glob în antet pentru schimbarea limbii în timp real (🇺🇸/🇧🇷) |
-| 🧹 **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 |
-| 📂 **Director de date personalizate** | `DATA_DIR` env var pentru a înlocui calea de stocare implicită `~/.omniroute` |
+| Model | Prefix | Limit | Rate Limit |
+| ------------------------ | ------ | --------------------------- | ------------- |
+| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |
+| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |
+
+### ⚫ 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
+> iFlow (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 v2.0 is built as an operational platform, not just a relay proxy.
+
+### 🆕 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 Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |
+| 🤖 **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 (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) |
+| 🤝 **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** | 9 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 combo, apply resilience profiles, reset breakers from one control surface |
+
+### 🧠 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** | 6 balancing strategies + fallback chain control |
+| 🌐 **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) |
+| 💬 **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 |
+| ----------------------------------- | -------------------------------------------------------------------------------------- |
+| 🔌 **Circuit Breakers** | Per-model trip/recover with threshold controls |
+| 🎯 **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 |
+| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |
+| 🔑 **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 |
+
+### 📊 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 |
+| 📋 **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 |
+
+### ☁️ Deployment & Platform
+
+| Feature | What It Does |
+| ----------------------------- | --------------------------------------------------------- |
+| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |
+| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |
+| 💾 **Cloud Sync** | Configuration sync via cloud worker |
+| 🔄 **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 |
+
+### Feature Deep Dive
+
+#### Smart fallback with practical cost control
+
+```txt
+Combo: "my-coding-stack"
+ 1. cc/claude-opus-4-6
+ 2. nvidia/llama-3.3-70b
+ 3. glm/glm-4.7
+ 4. if/kimi-k2-thinking
+```
+
+When quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.
+
+#### 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)
+
+#### 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)
🚀 30. „Trebuie să trimit fluxuri de lucru agentice fără extinderea codului lipici”
+🚀 30. "I need to ship agentic workflows without glue-code sprawl"
-Echipele își pierd din viteza atunci când realizează mai multe servicii și scripturi ad-hoc. +Teams lose velocity when stitching multiple ad-hoc services and scripts. -**Cum o rezolvă OmniRoute:** +**How OmniRoute solves it:** -- Strategie unificată pentru clienți și agenți -- Interfețe de utilizare a protocolului încorporate și căi de validare a fumului -- Baze pregătite pentru producție (securitate, logare, rezistență, backup) +- Unified endpoint strategy for clients and agents +- Built-in protocol management UIs and smoke validation paths +- Production-ready foundations (security, logging, resilience, backup)
-` → `reasoning_content` pentru modele de gândire
-- **Ieșire structurată** — `json_schema` → `responseMimeType`/`responseSchema` a lui Gemeni
-
-### 👥 Suport pentru mai multe conturi
-
-- Adăugați mai multe conturi pentru fiecare furnizor
-- Auto round-robin sau rutare bazată pe prioritate
-- Revenire la următorul cont când cineva atinge cota
-
-### 🔄 Reîmprospătare automată a simbolului
-
-- Tokenurile OAuth se reîmprospătează automat înainte de expirare
-- Nu este nevoie de re-autentificare manuală
-- Experiență perfectă pentru toți furnizorii
-
-### 🎨 Combo personalizate
-
-- Creați combinații de modele nelimitate
-- 6 strategii: umplere întâi, round-robin, putere cu două alegeri, aleatoriu, cel mai puțin utilizat, optimizat din punct de vedere al costurilor
-- Partajați combo-uri pe dispozitive cu Cloud Sync
-
-### 🏥 Tabloul de bord pentru sănătate
-
-- Starea sistemului (timp de funcționare, versiune, utilizare a memoriei)
-- Stări întrerupătoarelor de circuit pentru fiecare furnizor (Închis/Deschis/Pe jumătate deschis)
-- Starea limitei ratei și blocajele active
-- Statistici de cache pentru semnături
-- Telemetrie latență (p50/p95/p99) + cache prompt
-- Resetați starea de sănătate cu un singur clic
-
-### 🔧 Translator Playground
-
-OmniRoute include un puternic Translator Playground încorporat cu **4 moduri** pentru depanare, testare și monitorizare a traducerilor API:
-
-| Modul | Descriere |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **💻 Loc de joacă** | Traducere directă a formatului — inserați orice corp de solicitare API și vedeți instantaneu cum îl traduce OmniRoute între formatele de furnizor (OpenAI ↔ Claude ↔ Gemini ↔ Responses API). Include exemple de șabloane și detecție automată a formatului. |
-| **💬 Tester de chat** | Trimiteți cereri reale de chat prin OmniRoute și vedeți întregul drum dus-întors: intrarea dvs., solicitarea tradusă, răspunsul furnizorului și răspunsul tradus înapoi. Neprețuit pentru validarea rutei combinate. |
-| **🧪 Banc de testare** | Mod de testare în loturi — definiți mai multe cazuri de testare cu diferite intrări și rezultate așteptate, rulați-le pe toate simultan și comparați rezultatele între furnizori și modele. |
-| **📱 Monitor live** | Monitorizare în timp real a cererilor — urmăriți cererile primite în timp ce acestea trec prin OmniRoute, vedeți traducerile formatului care au loc în direct și identificați problemele instantaneu. |
-
-**Acces:** Tabloul de bord → Traducător (bara laterală)
-
-### 💾 Cloud Sync
-
-- Sincronizați furnizorii, combo-urile și setările pe dispozitive
-- Sincronizare automată în fundal
-- Stocare securizată criptată
+- `GET /api/mcp/status`
+- `GET /api/mcp/tools`
+- `GET /api/mcp/audit`
+- `GET /api/mcp/audit/stats`
-## 🧪 Evaluări (Evaluări)
+📖 Detalii caracteristică
+🧩 MCP Setup (Model Context Protocol)
-### 🎯 Smart 4-Tier Fallback +Start MCP transport in stdio mode: -Creați combinații cu rezervă automată: - -``` -Combo: "my-coding-stack" - 1. cc/claude-opus-4-6 (your subscription) - 2. nvidia/llama-3.3-70b (free NVIDIA API) - 3. glm/glm-4.7 (cheap backup, $0.6/1M) - 4. if/kimi-k2-thinking (free fallback) - -→ Auto switches when quota runs out or errors occur +```bash +omniroute --mcp ``` -### 📊 Urmărirea cotelor în timp real +Recommended validation flow: -- Consumul de token per furnizor -- Resetați numărătoarea inversă (5 ore, zilnic, săptămânal) -- Estimarea costurilor pentru nivelurile plătite -- Rapoarte lunare de cheltuieli +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. -### 🔄 Format traducere +Useful APIs for automation: -Traducere fără întreruperi între formate: - -- **OpenAI** ↔ **Claude** ↔ **Gemeni** ↔ **Răspunsuri OpenAI** -- Instrumentul dvs. CLI trimite formatul OpenAI → OmniRoute traduce → Furnizorul primește formatul nativ -- Funcționează cu orice instrument care acceptă puncte finale personalizate OpenAI -- **Sanitizarea răspunsului** — Elimina câmpurile nestandard pentru compatibilitate strictă cu OpenAI SDK -- **Normalizarea rolurilor** — `developer` → `system` pentru non-OpenAI; `system` → `user` pentru modelele GLM/ERNIE -- **Think tag extraction** — blocuri `
+
🤝 A2A Setup (Agent2Agent)
-OmniRoute include un cadru de evaluare încorporat pentru a testa calitatea răspunsului LLM față de un set de aur. Accesați-l prin **Analitice → Evaluări** în tabloul de bord. +Discover the agent: -### Set de aur încorporat +```bash +curl http://localhost:20128/.well-known/agent.json +``` -„Setul de Aur OmniRoute” preîncărcat conține 10 cazuri de testare care acoperă: +Send a task: -- Salutări, matematică, geografie, generare de cod -- Conformitatea formatului JSON, traducere, reducere -- Refuz de siguranță (conținut dăunător), numărare, logică booleană +```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."}]}}' +``` -### Strategii de evaluare +Manage lifecycle: -| Strategie | Descriere | Exemplu | -| ---------- | ------------------------------------------------------------------------- | -------------------------------- | -| `exact` | Ieșirea trebuie să se potrivească exact cu | `"4"` | -| `contains` | Ieșirea trebuie să conțină subșir (indiferență de majuscule și minuscule) | `"Paris"` | -| `regex` | Ieșirea trebuie să se potrivească cu modelul regex | `"1.*2.*3"` | -| `custom` | Funcția JS personalizată returnează adevărat/fals | `(output) => output.length > 10` | +- `GET /api/a2a/status` +- `GET /api/a2a/tasks` +- `GET /api/a2a/tasks/:id` +- `POST /api/a2a/tasks/:id/cancel` ---- +Operational UI: -## 📖 Ghid de configurare +- `/dashboard/a2a` for task/state/stream observability and smoke actions + +
-
+
+💳 Furnizori de abonament
+🧪 End-to-end protocol validation
-### Cod Claude (Pro/Max) +Validate both protocols with real clients: + +```bash +npm run test:protocols:e2e +``` + +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) ```bash Dashboard → Providers → Connect Claude Code @@ -1068,7 +1438,7 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Sfat profesionist:** Folosiți Opus pentru sarcini complexe, Sonnet pentru viteză. OmniRoute urmărește cota per model! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! ### OpenAI Codex (Plus/Pro) @@ -1082,7 +1452,24 @@ Models: cx/gpt-5.1-codex-max ``` -### Gemini CLI (GRATIS 180K/lună!) +#### 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). + +### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -1094,7 +1481,7 @@ Models: gc/gemini-2.5-pro ``` -**Cea mai bună valoare:** Nivel gratuit imens! Utilizați acest lucru înainte de nivelurile plătite. +**Best Value:** Huge free tier! Use this before paid tiers. ### GitHub Copilot @@ -1112,88 +1499,88 @@ Models:
-
🔑 Furnizori de chei API
+🔑 API Key Providers
-### NVIDIA NIM (1000 de credite GRATUITE!) +### NVIDIA NIM (FREE developer access — 70+ models) -1. Înscrieți-vă: [build.nvidia.com](https://build.nvidia.com) -2. Obțineți cheia API gratuită (1000 de credite de inferență incluse) -3. Tabloul de bord → Adăugați furnizor → NVIDIA NIM: - - Cheie API: `nvapi-your-key` +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` -**Modele:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct` și peste 50 de altele +**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more -**Sfat profesional:** API compatibil cu OpenAI - funcționează perfect cu traducerea formatului OmniRoute! +**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation! ### DeepSeek -1. Înscrieți-vă: [platform.deepseek.com](https://platform.deepseek.com) -2. Obțineți cheia API -3. Tabloul de bord → Adăugați furnizor → DeepSeek +1. Sign up: [platform.deepseek.com](https://platform.deepseek.com) +2. Get API key +3. Dashboard → Add Provider → DeepSeek -**Modele:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` +**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` -### Groq (nivel gratuit disponibil!) +### Groq (Free Tier Available!) -1. Înscrieți-vă: [console.groq.com](https://console.groq.com) -2. Obțineți cheia API (nivel gratuit inclus) -3. Tabloul de bord → Adăugați furnizor → Groq +1. Sign up: [console.groq.com](https://console.groq.com) +2. Get API key (free tier included) +3. Dashboard → Add Provider → Groq -**Modele:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` +**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` -**Sfat profesionist:** Inferență ultra-rapidă - cel mai bun pentru codare în timp real! +**Pro Tip:** Ultra-fast inference — best for real-time coding! -### OpenRouter (100+ modele) +### OpenRouter (100+ Models) -1. Înscrieți-vă: [openrouter.ai](https://openrouter.ai) -2. Obțineți cheia API -3. Tabloul de bord → Adăugare furnizor → OpenRouter +1. Sign up: [openrouter.ai](https://openrouter.ai) +2. Get API key +3. Dashboard → Add Provider → OpenRouter -**Modele:** Accesați peste 100 de modele de la toți furnizorii importanți printr-o singură cheie API. +**Models:** Access 100+ models from all major providers through a single API key.
-
💰 Furnizori ieftini (backup)
+💰 Cheap Providers (Backup)
-### GLM-4.7 (Resetare zilnică, 0,6 USD/1 milion) +### GLM-4.7 (Daily reset, $0.6/1M) -1. Înscrieți-vă: [Zhipu AI](https://open.bigmodel.cn/) -2. Obțineți cheia API din Coding Plan -3. Tabloul de bord → Adăugați cheia API: - - Furnizor: `glm` - - Cheie API: `your-key` +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` -**Utilizați:** `glm/glm-4.7` +**Use:** `glm/glm-4.7` -**Sfat profesionist:** Planul de codare oferă cotă de 3 ori la 1/7 cost! Resetați zilnic la 10:00. +**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -### MiniMax M2.1 (resetare 5 ore, 0,20 USD/1 milion) +### MiniMax M2.1 (5h reset, $0.20/1M) -1. Înscrieți-vă: [MiniMax](https://www.minimax.io/) -2. Obțineți cheia API -3. Tabloul de bord → Adăugați cheia API +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key +3. Dashboard → Add API Key -**Utilizați:** `minimax/MiniMax-M2.1` +**Use:** `minimax/MiniMax-M2.1` -**Sfat pro:** Cea mai ieftină opțiune pentru context lung (1 milion de jetoane)! +**Pro Tip:** Cheapest option for long context (1M tokens)! -### Kimi K2 (9 USD/lună fix) +### Kimi K2 ($9/month flat) -1. Abonați-vă: [Moonshot AI](https://platform.moonshot.ai/) -2. Obțineți cheia API -3. Tabloul de bord → Adăugați cheia API +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key +3. Dashboard → Add API Key -**Utilizați:** `kimi/kimi-latest` +**Use:** `kimi/kimi-latest` -**Sfat profesionist:** Fix 9 USD/lună pentru 10 milioane de jetoane = 0,90 USD/cost efectiv de 1 milion! +**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
-
🆓 Furnizori GRATUITI (Backup de urgență)
+🆓 FREE Providers (Emergency Backup)
-### iFlow (8 modele GRATUITE) +### iFlow (5 FREE models via OAuth) ```bash Dashboard → Connect iFlow @@ -1208,7 +1595,7 @@ Models: if/deepseek-r1 ``` -### Qwen (3 modele GRATUITE) +### Qwen (4 FREE models via Device Code) ```bash Dashboard → Connect Qwen @@ -1220,7 +1607,7 @@ Models: qw/qwen3-coder-flash ``` -### Kiro (Claude GRATUIT) +### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro @@ -1235,9 +1622,9 @@ Models:
-
🎨 Creați combinații
+🎨 Create Combos
-### Exemplul 1: Maximizați abonamentul → Backup ieftin +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -1251,7 +1638,7 @@ Models: Use in CLI: premium-coding ``` -### Exemplul 2: Numai gratuit (cost zero) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -1266,7 +1653,7 @@ Cost: $0 forever!
-
---
-## 🐛 Depanare
+## Depanare
🔧 Integrare CLI
+🔧 CLI Integration
### Cursor IDE @@ -1277,9 +1664,9 @@ Settings → Models → Advanced: Model: cc/claude-opus-4-6 ``` -### Claude Cod +### Claude Code -Utilizați pagina **Instrumente CLI** din tabloul de bord pentru configurarea cu un singur clic sau editați manual `~/.claude/settings.json`. +Use the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually. ### Codex CLI @@ -1292,13 +1679,13 @@ codex "your prompt" ### OpenClaw -**Opțiunea 1 — Tabloul de bord (recomandat):** +**Option 1 — Dashboard (recommended):** ``` Dashboard → CLI Tools → OpenClaw → Select Model → Apply ``` -**Opțiunea 2 — Manual:** Editați `~/.openclaw/openclaw.json`: +**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`: ```json { @@ -1314,9 +1701,9 @@ Dashboard → CLI Tools → OpenClaw → Select Model → Apply } ``` -> **Notă:** OpenClaw funcționează numai cu OmniRoute local. Utilizați `127.0.0.1` în loc de `localhost` pentru a evita problemele de rezoluție IPv6. +> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues. -### Cline / Continuare / RooCode +### Cline / Continue / RooCode ``` Settings → API Configuration: @@ -1326,110 +1713,245 @@ Settings → API Configuration: 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. +
-
-- **Runtime**: Node.js 18–22 LTS (⚠️ Node.js 24+ este **nu este acceptat** - `better-sqlite3` binarele native sunt incompatibile)
-- **Limba**: TypeScript 5.9 — **100% TypeScript** în `src/` și `open-sse/` (v1.0.6)
-- **Cadru**: Next.js 16 + React 19 + Tailwind CSS 4
-- **Bază de date**: LowDB (JSON) + SQLite (starea domeniului + jurnalele proxy)
-- **Streaming**: evenimente trimise de server (SSE)
-- **Auth**: OAuth 2.0 (PKCE) + JWT + chei API
-- **Testare**: Runner de testare Node.js (368+ teste unitare)
-- **CI/CD**: GitHub Actions (publicare automată npm + Docker Hub la lansare)
-- **Site web**: [omniroute.online](https://omniroute.online)
-- **Pachet**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
-- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
-- **Reziliență**: întrerupător de circuit, backoff exponențial, turmă anti-tunet, falsificare TLS
-
----
-
-## 📖 Documentație
-
-| Document | Descriere |
-| -------------------------------------------- | --------------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Furnizori, combo-uri, integrare CLI, implementare |
-| [API Reference](docs/API_REFERENCE.md) | Toate punctele finale cu exemple |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Probleme și soluții comune |
-| [Architecture](docs/ARCHITECTURE.md) | Arhitectura sistemului și elementele interne |
-| [Contributing](CONTRIBUTING.md) | Configurare și linii directoare de dezvoltare |
-| [OpenAPI Spec](docs/openapi.yaml) | Specificație OpenAPI 3.0 |
-| [Security Policy](SECURITY.md) | Raportarea vulnerabilităților și practicile de securitate |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Ghid complet: VM + nginx + configurare Cloudflare |
-| [Features Gallery](docs/FEATURES.md) | Tur vizual al tabloului de bord cu capturi de ecran |
-
-### 📸 Previzualizarea tabloului de bord
+## 🛠️ Tech Stack
Faceți clic pentru a extinde ghidul de depanare
+Click to expand troubleshooting guide
-**„Modelul de limbă nu a furnizat mesaje”** +**"Language model did not provide messages"** -- Cota de furnizor epuizată → Verificați instrumentul de urmărire a cotei din tabloul de bord -- Soluție: utilizați alternativă combinată sau treceți la un nivel mai ieftin +- Provider quota exhausted → Check dashboard quota tracker +- Solution: Use combo fallback or switch to cheaper tier -**Limitarea ratei** +**Rate limiting** -- Scăderea cotei de abonament → Fallback la GLM/MiniMax -- Adăugați combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Subscription quota out → Fallback to GLM/MiniMax +- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -**Tokenul OAuth a expirat** +**OAuth token expired** -- Reîmprospătat automat de OmniRoute -- Dacă problemele persistă: Dashboard → Provider → Reconnect +- Auto-refreshed by OmniRoute +- If issues persist: Dashboard → Provider → Reconnect -**Costuri mari** +**High costs** -- Verificați statisticile de utilizare în Tabloul de bord → Costuri -- Comutați modelul principal la GLM/MiniMax -- Utilizați nivelul gratuit (Gemini CLI, iFlow) pentru sarcini necritice +- Check usage stats in Dashboard → Costs +- Switch primary model to GLM/MiniMax +- Use free tier (Gemini CLI, iFlow) for non-critical tasks -**Tabloul de bord se deschide pe portul greșit** +**Dashboard/API ports are wrong** -- Setați `PORT=20128` și `NEXT_PUBLIC_BASE_URL=http://localhost:20128` +- `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) -**Erori de sincronizare în cloud** +**Cloud sync errors** -- Verificați `BASE_URL` puncte către instanța dvs. care rulează -- Verificați `CLOUD_URL` puncte către punctul final din cloud așteptat -- Păstrați valorile `NEXT_PUBLIC_*` aliniate cu valorile de pe partea serverului +- 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 -**Prima conectare nu funcționează** +**First login not working** -- Verificați `INITIAL_PASSWORD` în `.env` -- Dacă nu este setată, parola de rezervă este `123456` +- Check `INITIAL_PASSWORD` in `.env` +- If unset, fallback password is `123456` -**Fără jurnal de solicitare** +**No request logs** -- Setați `ENABLE_REQUEST_LOGS=true` în `.env` +- Set `ENABLE_REQUEST_LOGS=true` in `.env` -**Testul de conectare arată „Invalid” pentru furnizorii compatibili cu OpenAI** +**Connection test shows "Invalid" for OpenAI-compatible providers** -- Mulți furnizori nu expun un punct final `/models` -- OmniRoute v1.0.6+ include validarea de rezervă prin finalizarea chatului -- Asigurați-vă că adresa URL de bază include sufixul `/v1` +- 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 +### 🔐 OAuth on a Remote Server + -> **⚠️ IMPORTANT pentru utilizatorii cu OmniRoute în VPS/Docker/servidor remoto** +> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server** -#### OAuth +#### Why does Antigravity / Gemini CLI OAuth fail on remote servers? -Pentru autentificare, **Antigravity** și **Gemini CLI** folosesc **Google OAuth 2.0**. O Google exige que a `redirect_uri` utilizat nu fluxo OAuth seja **exatamente** uma das URIs pre-cadastradas no Google Cloud Console do aplicative. +The **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console. -As credenciais OAuth embutidas no OmniRoute esteo cadastradas **apenas for `localhost`**. Când accesați OmniRoute într-un server la distanță (ex: `https://omniroute.meuservidor.com`), sau Google respinge autentificarea com: +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 ``` -### Soluție: Configurați propriile acreditări OAuth +#### Solution: Configure your own OAuth credentials -Você necesita criar um **OAuth 2.0 Client ID** nu Google Cloud Console ca URI pentru server. +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 + +# For Gemini CLI: +GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com +GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +``` + +**6. Restart OmniRoute** + +```bash +# npm: +npm run dev + +# Docker: +docker restart omniroute +``` + +**7. Try connecting again** + +Dashboard → Providers → Antigravity (or Gemini CLI) → OAuth + +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. + +--- + +
+
---
-## 🛠️
+🇧🇷 Versão em Português
+ +#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos? + +Os provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo. + +As credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticação com: + +``` +Error 400: redirect_uri_mismatch +``` + +#### Solução: Configure suas próprias credenciais OAuth + +Você precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor. #### Passo a passo -**1. Acces sau Google Cloud Console** +**1. Acesse o Google Cloud Console** Abra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) -**2. Plângeți nou OAuth 2.0 Client ID** +**2. Crie um novo OAuth 2.0 Client ID** -- Faceți clic pe **"+ Create Credentials"** → **"OAuth client ID"** -- Tip de aplicație: **"Aplicație web"** -- Nume: scolha qualquer nome (ex: `OmniRoute Remote`) +- Clique em **"+ Create Credentials"** → **"OAuth client ID"** +- Tipo de aplicativo: **"Web application"** +- Nome: escolha qualquer nome (ex: `OmniRoute Remote`) -**3. Adăugați ca URI de redirecționare autorizate** +**3. Adicione as Authorized Redirect URIs** -No campo **„URI-uri de redirecționare autorizate”**, adiție: +No campo **"Authorized redirect URIs"**, adicione: ``` https://seu-servidor.com/callback ``` -> Substitue `seu-servidor.com` pelo domínio sau IP do seu servidor (inclua a porta se necessário, ex: `http://45.33.32.156:20128/callback`). +> Substitua `seu-servidor.com` pelo domínio ou IP do seu servidor (inclua a porta se necessário, ex: `http://45.33.32.156:20128/callback`). -**4. Salve și copie ca credenciais** +**4. Salve e copie as credenciais** -Após criar, o Google afișează o **Client ID** e o **Client Secret**. +Após criar, o Google mostrará o **Client ID** e o **Client Secret**. -**5. Configurați ca variabile de mediu** +**5. Configure as variáveis de ambiente** -Nu ai `.env` (ai variat de ambient do Docker): +No seu `.env` (ou nas variáveis de ambiente do Docker): ```bash # Para Antigravity: @@ -1452,152 +1974,147 @@ npm run dev docker restart omniroute ``` -**7. Tente connect novamente** +**7. Tente conectar novamente** -Tabloul de bord → Furnizori → Antigravity (sau Gemini CLI) → OAuth +Dashboard → Providers → Antigravity (ou Gemini CLI) → OAuth -Agora sau Google redirecționează corect pentru `https://seu-servidor.com/callback` și funcționează autenticação. +Agora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará. --- -### Soluție temporară (sem configurar credenciais proprias) +#### Workaround temporário (sem configurar credenciais próprias) -Nu vă rugăm să vă convingeți acum, dar este posibil să utilizați sau să fluxați **manual de URL**: +Se não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**: -1. OmniRoute deschide o adresă URL de autorizare Google -2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no server remote) -3. **Copiați o adresă URL completă** da bara de accesare a browserului (mesmo que a page não carregue) -4. Cole essa URL nu există câmpuri care nu apar modal de conexão pentru OmniRoute -5. Faceți clic pe **„Conectați-vă”** +1. O OmniRoute abrirá a URL de autorização do Google +2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto) +3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue) +4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute +5. Clique em **"Connect"** -> Această soluție de soluționare funcționează deoarece codul de autorizare a URL-ului este valabil independent de redirecționare pentru a încărca sau nu. +> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.
-
---
-## 🗺️
+## Documentație
-OmniRoute are **210+ funcții planificate** în mai multe faze de dezvoltare. Iată domeniile cheie:
-
-| Categoria | Caracteristici planificate | Repere |
-| --------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| 🧠 **Routing & Intelligence** | 25+ | Rutare cu cea mai mică latență, rutare bazată pe etichete, verificare preliminară a cotei, selecție contului P2C |
-| 🔒 **Securitate și conformitate** | 20+ | Întărirea SSRF, acoperirea acreditărilor, limita de rată per punct final, domeniul de aplicare al cheii de management |
-| 📊 **Observabilitate** | 15+ | Integrarea OpenTelemetry, monitorizarea cotelor în timp real, urmărirea costurilor per model |
-| 🔄 **Integrări furnizori** | 20+ | Registrul modelului dinamic, perioadele de încărcare ale furnizorului, Codexul cu mai multe conturi, analiza cotelor Copilot |
-| ⚡ **Performanță** | 15+ | Strat cache dublu, cache prompt, cache de răspuns, streaming keepalive, API batch |
-| 🌐 **Ecosistem** | 10+ | WebSocket API, config hot-reload, magazin de configurare distribuit, mod comercial |
-
-### 🔜 În curând
-
-- 🔗 **Integrare OpenCode** — Suport furnizor nativ pentru IDE-ul de codare OpenCode AI
-- 🔗 **Integrare TRAE** — Suport complet pentru cadrul de dezvoltare TRAE AI
-- 📦 **Batch API** — Procesare asincronă în lot pentru solicitări în bloc
-- 🎯 **Rutare bazată pe etichete** — Solicitări de rutare bazate pe etichete și metadate personalizate
-- 💰 **Strategia cu cel mai mic cost** — Selectați automat cel mai ieftin furnizor disponibil
-
-> 📝 Specificații complete ale caracteristicilor disponibile în [link](docs/new-features/) (217 specificații detaliate)
+| Document | Description |
+| ---------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 16 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/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
+| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
-## 👥 Colaboratori
+## 🗺️ Roadmap
+
+OmniRoute has **210+ 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, P2C account selection |
+| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |
+| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |
+| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider 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
[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
-### Cum să contribui
+### How to Contribute
-1. Bifurcați depozitul
-2. Creați-vă ramura caracteristică (`git checkout -b feature/amazing-feature`)
-3. Afișează modificările (`git commit -m 'Add amazing feature'`)
-4. Apăsați la ramură (`git push origin feature/amazing-feature`)
-5. Deschideți o cerere de tragere
+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
-Consultați [CONTRIBUTING.md](CONTRIBUTING.md) pentru instrucțiuni detaliate.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
-### Lansarea unei noi versiuni
+### Releasing a New Version
```bash
# Create a release — npm publish happens automatically
-gh release create v1.0.6 --title "v1.0.6" --generate-notes
+gh release create v2.0.0 --title "v2.0.0" --generate-notes
```
---
-## 📊 Istoria stelelor
+## 📊 Star History
## Stargazers over time
## [](https://starchart.cc/diegosouzapw/OmniRoute)
-## 🙏 Mulțumiri
+## 🙏 Acknowledgments
-Mulțumiri speciale pentru **[9router](https://github.com/decolua/9router)** de **[decolua](https://github.com/decolua)** — proiectul original care a inspirat această furcă. OmniRoute se bazează pe această bază incredibilă cu funcții suplimentare, API-uri multimodale și o rescrie completă TypeScript.
+Special thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.
-Mulțumiri speciale pentru **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — implementarea Go originală care a inspirat acest port JavaScript.
+Special thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.
---
-## 📄 Licență
+## Licență
-Licență MIT - consultați [LICENSE](LICENSE) pentru detalii.
+MIT License - see [LICENSE](LICENSE) for details.
---
Faceți clic pentru a vedea capturile de ecran de pe tabloul de bord
+Click to expand tech stack details
-| Pagina | Captură de ecran | -| ------------------------ | ------------------------------------------------- | -| **Furnizori** |  | -| **Combo** |  | -| **Analitice** |  | -| **Sănătate** |  | -| **Translator** |  | -| **Setări** |  | -| **Instrumente CLI** |  | -| **Jurnale de utilizare** |  | -| **Punctul final** |  | +- **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**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions) +- **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
- Construit cu ❤️ pentru dezvoltatorii care codifică 24/7
+ Built with ❤️ for developers who code 24/7
omniroute.online
+
diff --git a/docs/i18n/ro/docs/FEATURES.md b/docs/i18n/ro/docs/FEATURES.md
new file mode 100644
index 0000000000..e0625281eb
--- /dev/null
+++ b/docs/i18n/ro/docs/FEATURES.md
@@ -0,0 +1,145 @@
+# OmniRoute — Dashboard Features Gallery (Română)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/FEATURES.md) · 🇪🇸 [es](../../es/docs/FEATURES.md) · 🇫🇷 [fr](../../fr/docs/FEATURES.md) · 🇩🇪 [de](../../de/docs/FEATURES.md) · 🇮🇹 [it](../../it/docs/FEATURES.md) · 🇷🇺 [ru](../../ru/docs/FEATURES.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FEATURES.md) · 🇯🇵 [ja](../../ja/docs/FEATURES.md) · 🇰🇷 [ko](../../ko/docs/FEATURES.md) · 🇸🇦 [ar](../../ar/docs/FEATURES.md) · 🇮🇳 [in](../../in/docs/FEATURES.md) · 🇹🇭 [th](../../th/docs/FEATURES.md) · 🇻🇳 [vi](../../vi/docs/FEATURES.md) · 🇮🇩 [id](../../id/docs/FEATURES.md) · 🇲🇾 [ms](../../ms/docs/FEATURES.md) · 🇳🇱 [nl](../../nl/docs/FEATURES.md) · 🇵🇱 [pl](../../pl/docs/FEATURES.md) · 🇸🇪 [sv](../../sv/docs/FEATURES.md) · 🇳🇴 [no](../../no/docs/FEATURES.md) · 🇩🇰 [da](../../da/docs/FEATURES.md) · 🇫🇮 [fi](../../fi/docs/FEATURES.md) · 🇵🇹 [pt](../../pt/docs/FEATURES.md) · 🇷🇴 [ro](../../ro/docs/FEATURES.md) · 🇭🇺 [hu](../../hu/docs/FEATURES.md) · 🇧🇬 [bg](../../bg/docs/FEATURES.md) · 🇸🇰 [sk](../../sk/docs/FEATURES.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FEATURES.md) · 🇮🇱 [he](../../he/docs/FEATURES.md) · 🇵🇭 [phi](../../phi/docs/FEATURES.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FEATURES.md)
+
+---
+
+Visual guide to every section of the OmniRoute dashboard.
+
+---
+
+## 🔌 Providers
+
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
+
+
+
+---
+
+## 🎨 Combos
+
+Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
+
+
+
+---
+
+## 📊 Analytics
+
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
+
+
+
+---
+
+## 🏥 System Health
+
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+
+
+
+---
+
+## 🔧 Translator Playground
+
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
+
+
+
+---
+
+## 🎮 Model Playground _(v2.0.9+)_
+
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
+
+---
+
+## 🎨 Themes _(v2.0.5+)_
+
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
+
+## ⚙️ Settings
+
+Comprehensive settings panel with tabs:
+
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning
+- **Advanced** — Configuration overrides
+
+
+
+---
+
+## 🔧 CLI Tools
+
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
+
+
+
+---
+
+## 🤖 CLI Agents _(v2.0.11+)_
+
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
+
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
+
+---
+
+## 🖼️ Media _(v2.0.3+)_
+
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
+
+## 📝 Request Logs
+
+Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
+
+
+
+---
+
+## 🌐 API Endpoint
+
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
+
+
+
+---
+
+## 🔑 API Key Management
+
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
+
+---
+
+## 📋 Audit Log
+
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
+
+---
+
+## 🖥️ Desktop Application
+
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
+
+Key features:
+
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
+
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.
diff --git a/docs/i18n/ru/README.md b/docs/i18n/ru/README.md
index 04d93215f8..386283d3d0 100644
--- a/docs/i18n/ru/README.md
+++ b/docs/i18n/ru/README.md
@@ -1,24 +1,94 @@
-omniroute.online
-
-
- # 🚀 OmniRoute — Бесплатный AI Gateway
+# 🚀 OmniRoute — The Free AI Gateway (Русский)
-### Никогда не прекращайте программировать. Умная маршрутизация к **БЕСПЛАТНЫМ и дешёвым AI-моделям** с автоматическим fallback.
-
-_Ваш универсальный API-прокси — одна точка доступа, 36+ провайдеров, нулевой простой._
-
-**Chat Completions • Embeddings • Генерация изображений • Аудио • Reranking • 100% TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Бесплатный AI-провайдер для ваших любимых агентов программирования
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Подключайте любую IDE или CLI-инструмент с AI через OmniRoute — бесплатный API gateway для неограниченного программирования._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+` tags no longer leak to clients in SSE streaming responses (#585) |
+| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with per-provider/account quota enforcement, idempotency, SHA-256 storage, and optional GitHub issue reporting |
+| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG → generic fallback chain |
+| 🔄 **Model Auto-Sync** | 24h scheduler and manual UI toggle to sync model lists for built-in and custom OpenAI-compatible providers |
+| 🌐 **OpenCode Zen/Go** | Two new providers from @kang-heewon via PR #530: free tier + subscription tier via `OpencodeExecutor` |
+| 🐛 **Gemini CLI OAuth** | Actionable error when `GEMINI_OAUTH_CLIENT_SECRET` is missing in Docker (was cryptic Google error) |
+| 🐛 **OpenCode config** | `saveOpenCodeConfig()` now correctly writes TOML to `XDG_CONFIG_HOME` |
+| 🐛 **Pinned model override** | `body.model` correctly set to `pinnedModel` on context-cache protection |
+| 🐛 **Codex/Claude loop** | `tool_result` blocks now converted to text to stop infinite loops |
+| 🐛 **Login redirect** | Login no longer freezes after skipping password setup |
+| 🐛 **Windows paths** | MSYS2/Git-Bash paths (`/c/...`) normalized to `C:\...` automatically |
+
+---
+
+## 🖼️ Main Dashboard
+
+
-📡 Все агенты подключаются через ` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**Stop wasting money and hitting limits:**
-### 🆕 What's New in v3.0.0
+- Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**OmniRoute solves this:**
+
+- ✅ **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
+- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool
---
-[](https://www.npmjs.com/package/omniroute)
-[](https://hub.docker.com/r/diegosouzapw/omniroute)
-[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
-[](https://omniroute.online)
-[](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
+## 📧 Support
-[🌐 Сайт](https://omniroute.online) • [🚀 Быстрый старт](#-быстрый-старт) • [💡 Функции](#-основные-функции) • [📖 Документация](#-документация) • [💰 Цены](#-обзор-цен)
+> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.
-🌐 **Available in:** 🇺🇸 [English](../../README.md) | 🇧🇷 [Português (Brasil)](../pt-BR/README.md) | 🇪🇸 [Español](../es/README.md) | 🇫🇷 [Français](../fr/README.md) | 🇮🇹 [Italiano](../it/README.md) | 🇷🇺 [Русский](../ru/README.md) | 🇨🇳 [中文 (简体)](../zh-CN/README.md) | 🇩🇪 [Deutsch](../de/README.md) | 🇮🇳 [हिन्दी](../in/README.md) | 🇹🇭 [ไทย](../th/README.md) | 🇺🇦 [Українська](../uk-UA/README.md) | 🇸🇦 [العربية](../ar/README.md) | 🇯🇵 [日本語](../ja/README.md) | 🇻🇳 [Tiếng Việt](../vi/README.md) | 🇧🇬 [Български](../bg/README.md) | 🇩🇰 [Dansk](../da/README.md) | 🇫🇮 [Suomi](../fi/README.md) | 🇮🇱 [עברית](../he/README.md) | 🇭🇺 [Magyar](../hu/README.md) | 🇮🇩 [Bahasa Indonesia](../id/README.md) | 🇰🇷 [한국어](../ko/README.md) | 🇲🇾 [Bahasa Melayu](../ms/README.md) | 🇳🇱 [Nederlands](../nl/README.md) | 🇳🇴 [Norsk](../no/README.md) | 🇵🇹 [Português (Portugal)](../pt/README.md) | 🇷🇴 [Română](../ro/README.md) | 🇵🇱 [Polski](../pl/README.md) | 🇸🇰 [Slovenčina](../sk/README.md) | 🇸🇪 [Svenska](../sv/README.md) | 🇵🇭 [Filipino](../phi/README.md)
-
-
-
----
-
-## 🖼️
-
-
-
- # 🚀 OmniRoute — Бесплатный AI Gateway
+# 🚀 OmniRoute — The Free AI Gateway (Русский)
-### Никогда не прекращайте программировать. Умная маршрутизация к **БЕСПЛАТНЫМ и дешёвым AI-моделям** с автоматическим fallback.
-
-_Ваш универсальный API-прокси — одна точка доступа, 36+ провайдеров, нулевой простой._
-
-**Chat Completions • Embeddings • Генерация изображений • Аудио • Reranking • 100% TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Бесплатный AI-провайдер для ваших любимых агентов программирования
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Подключайте любую IDE или CLI-инструмент с AI через OmniRoute — бесплатный API gateway для неограниченного программирования._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+
+
+[](https://www.npmjs.com/package/omniroute)
+[](https://www.npmjs.com/package/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
+[](https://omniroute.online)
+[](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)
+
+
+
+🌐 **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)
+
+---
+
+## 🆕 What's New in v3.0.0
+
+> **Upgrading from v2.9.5?** — See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes.
+
+| Area | Change |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection remediation |
+| ✅ **Route Validation** | All 176 API routes now validated with Zod schemas + `validateBody()` — CI `check:route-validation:t06` passes |
+| 🐛 **omniModel Tag Leak** | Internal `
+
+
+
+---
+
+## 📸 Dashboard Preview
+
+
+
+
+
+---
+
+### 🤖 Free AI Provider for your favorite coding agents
+
+_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._
Click to see dashboard screenshots
+ +| Page | Screenshot | +| -------------- | ------------------------------------------------- | +| **Providers** |  | +| **Combos** |  | +| **Analytics** |  | +| **Health** |  | +| **Translator** |  | +| **Settings** |  | +| **CLI Tools** |  | +| **Usage Logs** |  | +| **Endpoints** |  | + +|
-
+
OpenClaw @@ -92,586 +162,527 @@ _Подключайте любую IDE или CLI-инструмент с AI ч |
http://localhost:20128/v1 или http://cloud.omniroute.online/v1 — одна конфигурация, неограниченные модели и квота
+📡 All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 — one config, unlimited models and quota
---
-### 🆕 What's New in v3.0.0
+## 🤔 Why OmniRoute?
-| Area | Change |
-| ------------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal ` Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `
-
-
-
----
-
-## 📸
-
-
-
-
-
----
-
-## 🤔 Почему OmniRoute?
-
-**Перестаньте тратить деньги и упираться в лимиты:**
-
-- ...
- -| # | # | -| ----- | ---------------------------------------- | -| **1** |  | -| **2** |  | -| **3** |  | -| **4** |  | -| **5** |  | -| **6** |  | -| **7** |  | -| **8** |  | -| **9** |  | - - Квота подписки истекает неиспользованной каждый месяц
-- Лимиты скорости останавливают вас посреди программирования
-- Дорогие API ($20-50/месяц за провайдера)
-- Ручное переключение между провайдерами
-
-**OmniRoute решает это:**
-
-- ✅ **Максимизируйте подписки** — Отслеживайте квоты, используйте всё до сброса
-- ✅ **Автоматический fallback** — Подписка → API Key → Дешёвый → Бесплатный, нулевой простой
-- ✅ **Мульти-аккаунт** — Round-robin между аккаунтами каждого провайдера
-- ✅ **Универсальный** — Работает с Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, любым CLI-инструментом
-
----
-
-## 📧 Поддержка
-
-> 💬 **Присоединяйтесь к сообществу!** [Группа WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Получайте помощь, делитесь советами и оставайтесь в курсе.
-
-- **Сайт**: [omniroute.online](https://omniroute.online)
+- **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**: [Группа сообщества](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Оригинальный проект**: [9router от decolua](https://github.com/decolua/9router)
+- **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`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 Как это работает
+## 🔄 How It Works
```
┌─────────────┐
-│ Ваш CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
+│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
│ Tool │
└──────┬──────┘
│ http://localhost:20128/v1
↓
┌─────────────────────────────────────────┐
-│ OmniRoute (Умный маршрутизатор) │
-│ • Трансляция формата (OpenAI ↔ Claude) │
-│ • Отслеживание квот + Embeddings + Изображения │
-│ • Автообновление токенов │
+│ OmniRoute (Smart Router) │
+│ • Format translation (OpenAI ↔ Claude) │
+│ • Quota tracking + Embeddings + Images │
+│ • Auto token refresh │
└──────┬──────────────────────────────────┘
│
- ├─→ [Tier 1: ПОДПИСКА] Claude Code, Codex, Gemini CLI
- │ ↓ квота исчерпана
- ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM и др.
- │ ↓ лимит бюджета
- ├─→ [Tier 3: ДЕШЁВЫЙ] GLM ($0.6/1M), MiniMax ($0.2/1M)
- │ ↓ лимит бюджета
- └─→ [Tier 4: БЕСПЛАТНЫЙ] iFlow, Qwen, Kiro (неограниченно)
+ ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI
+ │ ↓ 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] iFlow, Qwen, Kiro (unlimited)
-Результат: Никогда не прекращайте программировать, минимальные затраты
+Result: Never stop coding, minimal cost
```
---
-## 🎯 Что решает OmniRoute — 30 реальных проблем и вариантов использования
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **Каждый разработчик, использующий инструменты искусственного интеллекта, ежедневно сталкивается с этими проблемами.** OmniRoute был создан для решения всех этих проблем — от перерасхода средств до региональных блоков, от нарушенных потоков OAuth до операций протокола и наблюдения за предприятием.
+> **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.
-
💸 1. «Я плачу за дорогую подписку, но меня все равно прерывают лимиты»
+💸 1. "I pay for an expensive subscription but still get interrupted by limits"
-Разработчики платят 20–200 долларов в месяц за Claude Pro, Codex Pro или GitHub Copilot. Даже при оплате квота имеет потолок — 5 часов использования, еженедельные лимиты или поминутные ограничения. В середине сеанса кодирования провайдер перестает отвечать, и разработчик теряет поток и производительность. +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. -**Как OmniRoute решает эту проблему:** +**How OmniRoute solves it:** -- **Умный 4-уровневый резерв** — если квота подписки исчерпана, происходит автоматическое перенаправление на API-ключ → Дешево → Бесплатно без вмешательства вручную. -- **Отслеживание квот в реальном времени** — показывает потребление токенов в режиме реального времени с обратным отсчетом сброса (5 часов, ежедневно, еженедельно). -- **Поддержка нескольких учетных записей** — Несколько учетных записей у каждого провайдера с автоматическим циклическим перебором — когда один из них заканчивается, переключается на следующий -- **Пользовательские комбинации** — Настраиваемые резервные цепочки с 6 стратегиями балансировки (сначала заполняемые, циклический, P2C, случайные, наименее используемые, с оптимизацией затрат) -- **Бизнес-квоты Кодекса** — мониторинг квот рабочего пространства для бизнеса/команды непосредственно на панели управления. +- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention +- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly) +- **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 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
-` из таких моделей, как DeepSeek R1, в стандартизированный `reasoning_content`.
-- **Структурированный вывод для Gemini** — автоматическое преобразование `json_schema` → `responseMimeType`/`responseSchema`.
-- **`stream` по умолчанию — `false`** — соответствует спецификации OpenAI, что позволяет избежать неожиданного SSE в SDK Python/Rust/Go.
+- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 67+ 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
🔌 2. «Мне нужно использовать несколько поставщиков, но у каждого свой API»
+🔌 2. "I need to use multiple providers but each has a different API"
-OpenAI использует один формат, Claude (Anthropic) — другой, Gemini — третий. Если разработчик хочет протестировать модели от разных поставщиков или использовать резервный вариант между ними, ему необходимо перенастроить SDK, изменить конечные точки, разобраться с несовместимыми форматами. Пользовательские поставщики (FriendLI, NIM) имеют нестандартные конечные точки модели. +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. -**Как OmniRoute решает эту проблему:** +**How OmniRoute solves it:** -- **Единая конечная точка** — один `http://localhost:20128/v1` служит прокси для всех 36+ провайдеров. -- **Перевод формата** — Автоматический и прозрачный: OpenAI ↔ Claude ↔ Gemini ↔ API ответов -- **Очистка ответов** — удаляются нестандартные поля (`x_groq`, `usage_breakdown`, `service_tier`), которые нарушают OpenAI SDK v1.83+. -- **Нормализация ролей** — преобразует `developer` в `system` для поставщиков, не поддерживающих OpenAI; `system` → `user` для GLM/ERNIE -- **Think Tag Extraction** — извлекает блоки `
-
🌐 3. «Мой провайдер ИИ блокирует мой регион/страну»
+🌐 3. "My AI provider blocks my region/country"
-Такие провайдеры, как OpenAI/Codex, блокируют доступ из определенных географических регионов. Пользователи получают ошибки типа `unsupported_country_region_territory` во время подключений OAuth и API. Особенно это расстраивает разработчиков из развивающихся стран. +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. -**Как OmniRoute решает эту проблему:** +**How OmniRoute solves it:** -- **3-уровневая конфигурация прокси** — настраиваемый прокси-сервер на трех уровнях: глобальный (весь трафик), для каждого провайдера (только один провайдер) и для каждого соединения/ключа. -- **Значки прокси с цветной кодировкой** — Визуальные индикаторы: 🟢 глобальный прокси, 🟡 прокси-сервер провайдера, 🔵 прокси-сервер подключения, всегда показывающий IP-адрес. -- **Обмен токенов OAuth через прокси** — поток OAuth также проходит через прокси, решая проблему `unsupported_country_region_territory`. -- **Тесты подключения через прокси** — тесты подключения используют настроенный прокси-сервер (прямого обхода больше нет) -- **Поддержка SOCKS5** — Полная поддержка прокси-сервера SOCKS5 для исходящей маршрутизации. -- **Подмена отпечатка пальца TLS** — отпечаток TLS, подобный браузеру, через `wreq-js` для обхода обнаружения ботов. +- **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
-` prefix
-- **Комбинации только бесплатно** — цепочка `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = 0 долларов США в месяц без простоев.
-- **Бесплатные кредиты NVIDIA NIM** — интегрировано 1000 бесплатных кредитов.
-- **Стратегия оптимизации затрат** — стратегия маршрутизации, которая автоматически выбирает самого дешевого доступного провайдера.
+- **Free-Only Combos** — Chain `gc/gemini-3-flash → 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
🆓 4. «Я хочу использовать ИИ для кодирования, но у меня нет денег»
+🆓 4. "I want to use AI for coding but I have no money"
-Не каждый может платить 20–200 долларов в месяц за подписку на ИИ. Студентам, разработчикам из развивающихся стран, любителям и фрилансерам нужен доступ к качественным моделям по нулевой цене. +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. -**Как OmniRoute решает эту проблему:** +**How OmniRoute solves it:** -- **Встроенные провайдеры уровня бесплатного пользования** — Встроенная поддержка 100% бесплатных провайдеров: iFlow (8 моделей с неограниченным количеством пользователей), Qwen (3 модели с неограниченным количеством пользователей), Kiro (Claude бесплатно), Gemini CLI (180 тысяч в месяц бесплатно). +- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free) - **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/
-
🔒 5. «Мне нужно защитить мой AI-шлюз от несанкционированного доступа»
+🔒 5. "I need to protect my AI gateway from unauthorized access"
-При предоставлении доступа к сети AI-шлюза (LAN, VPS, Docker) любой, у кого есть адрес, может использовать токены/квоту разработчика. Без защиты API уязвимы для неправильного использования, быстрого внедрения и злоупотреблений. +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. -**Как OmniRoute решает эту проблему:** +**How OmniRoute solves it:** -- **Управление ключами API** — генерация, ротация и определение области действия для каждого поставщика с помощью специальной страницы `/dashboard/api-manager`. -- **Разрешения на уровне модели** — Ограничьте использование ключей API определенными моделями (`openai/*`, шаблоны подстановочных знаков) с помощью переключателя Разрешить все/Ограничить. -- **API Endpoint Protection** — требует ключ для `/v1/models` и блокирует определенных поставщиков из списка. -- **Auth Guard + защита CSRF** — все маршруты информационной панели защищены промежуточным программным обеспечением `withAuth` + токенами CSRF. -- **Ограничитель скорости** — ограничение скорости для каждого IP с помощью настраиваемых окон. -- **IP-фильтрация** — список разрешенных/блокированных для контроля доступа. -- **Prompt Injection Guard** — очистка от вредоносных шаблонов подсказок. -- **Шифрование AES-256-GCM** — неактивные учетные данные зашифрованы. +- **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. «Мой провайдер вышел из строя, и я потерял процесс кодирования»
+🛑 6. "My provider went down and I lost my coding flow"
-Поставщики ИИ могут работать нестабильно, возвращать ошибки 5xx или достигать временных ограничений скорости. Если разработчик зависит от одного провайдера, его работу прерывают. Без автоматических выключателей повторные попытки могут привести к сбою приложения. +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. -**Как OmniRoute решает эту проблему:** +**How OmniRoute solves it:** -- **Выключатель для каждого поставщика** — автоматическое открытие/закрытие с настраиваемыми пороговыми значениями и временем восстановления (закрыто/открыто/полуоткрыто). -- **Экспоненциальная задержка** – прогрессивная задержка повторных попыток. -- **Anti-Thundering Herd** — Мьютекс + защита семафора от одновременных штормов повторных попыток. -- **Комбо-резервные цепочки** — в случае сбоя основного поставщика автоматически проходит через цепочку без вмешательства. -- **Комбо-выключатель** — автоматически отключает неисправных поставщиков в комбинированной цепочке. -- **Панель работоспособности** — мониторинг работоспособности, состояния автоматических выключателей, блокировки, статистика кэша, задержка p50/p95/p99. +- **Circuit Breaker per-model** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks +- **Exponential Backoff** — Progressive retry delays +- **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 +- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain +- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
-
🔧 7. «Настройка каждого инструмента искусственного интеллекта утомительна и повторяется»
+🔧 7. "Configuring each AI tool is tedious and repetitive"
-Разработчики используют Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Для каждого инструмента требуется своя конфигурация (конечная точка API, ключ, модель). Перенастройка при смене провайдера или модели — пустая трата времени. +Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time. -**Как OmniRoute решает эту проблему:** +**How OmniRoute solves it:** -- **Панель инструментов CLI** — выделенная страница с настройкой в один клик Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline. -- **Генератор конфигураций GitHub Copilot** — генерирует `chatLanguageModels.json` для кода VS с массовым выбором модели. -- **Мастер адаптации** — пошаговая пошаговая настройка для начинающих пользователей. -- **Одна конечная точка, все модели** — настройте `http://localhost:20128/v1` один раз и получите доступ к более чем 36 поставщикам услуг. +- **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 67+ providers
-
🔑 8. «Управление токенами OAuth от нескольких провайдеров — это ад»
+🔑 8. "Managing OAuth tokens from multiple providers is hell"
-Claude Code, Codex, Gemini CLI, Copilot — все используют OAuth 2.0 с токенами с истекающим сроком действия. Разработчикам необходимо постоянно проходить повторную аутентификацию, иметь дело с `client_secret is missing`, `redirect_uri_mismatch` и сбоями на удаленных серверах. OAuth в LAN/VPS особенно проблематичен. +Claude Code, Codex, Gemini CLI, 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. -**Как OmniRoute решает эту проблему:** +**How OmniRoute solves it:** -- **Автоматическое обновление токенов** — токены OAuth обновляются в фоновом режиме до истечения срока их действия. -- **Встроенный OAuth 2.0 (PKCE)** — автоматический поток для Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow. -- **OAuth с несколькими учетными записями** – несколько учетных записей для каждого провайдера посредством извлечения токена JWT/ID. -- **OAuth LAN/Remote Fix** — обнаружение частного IP-адреса для `redirect_uri` + ручной режим URL-адреса для удаленных серверов. -- **OAuth за Nginx** — использует `window.location.origin` для совместимости с обратным прокси-сервером. -- **Руководство по удаленному OAuth** — пошаговое руководство по учетным данным Google Cloud на VPS/Docker. +- **Auto Token Refresh** — OAuth tokens refresh in background before expiration +- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow +- **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. «Я не знаю, сколько и куда я трачу»
+📊 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. -**Как OmniRoute решает эту проблему:** +**How OmniRoute solves it:** -- **Панель анализа затрат** — отслеживание затрат на каждый токен и управление бюджетом для каждого поставщика. -- **Ограничения бюджета на уровень** — потолок расходов на уровень, который запускает автоматический возврат к резервному варианту. -- **Конфигурация цен на модель** — настраиваемые цены на модель. -- **Статистика использования каждого ключа API** — количество запросов и временная метка последнего использования для каждого ключа. -- **Панель аналитики** — карточки статистики, диаграмма использования модели, таблица поставщиков с показателями успеха и задержкой. +- **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. «Я не могу диагностировать ошибки и проблемы в вызовах ИИ»
+🐛 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. -**Как OmniRoute решает эту проблему:** +**How OmniRoute solves it:** -- **Панель управления унифицированными журналами** — 4 вкладки: журналы запросов, журналы прокси, журналы аудита, консоль. -- **Консольный просмотр журнала** — просмотрщик в режиме терминала в режиме реального времени с уровнями с цветовой кодировкой, автоматической прокруткой, поиском и фильтрацией. -- **Журналы прокси-сервера SQLite** — постоянные журналы, сохраняющиеся после перезапуска сервера. -- **Площадка транслятора (Translator Playground)** — 4 режима отладки: Площадка (перевод формата), Тестер чата (туда и обратно), Тестовый стенд (пакетный), Мониторинг в реальном времени (в режиме реального времени). -- **Запрос телеметрии** — задержка p50/p95/p99 + отслеживание X-Request-Id -- **Журналирование на основе файлов с ротацией** — перехватчик консоли записывает все в журнал JSON с ротацией на основе размера. +- **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 Proxy Logs** — Persistent logs that survive server restarts +- **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 Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation +- **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. «Развертывание и обслуживание шлюза сложны»
+🏗️ 11. "Deploying and maintaining the gateway is complex"
-Установка, настройка и обслуживание прокси-сервера AI в различных средах (локальных, VPS, Docker, облаке) — трудоемкий процесс. Такие проблемы, как жестко запрограммированные пути, `EACCES` в каталогах, конфликты портов и кроссплатформенные сборки, добавляют проблем. +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. -**Как OmniRoute решает эту проблему:** +**How OmniRoute solves it:** -- **глобальная установка npm** — `npm install -g omniroute && omniroute` — выполнено -- **Мультиплатформенность Docker** — встроенная версия AMD64 + ARM64 (Apple Silicon, AWS Graviton, Raspberry Pi) -- **Профили Docker Compose** — `base` (без инструментов CLI) и `cli` (с Claude Code, Codex, OpenClaw) -- **Electron Desktop App** — собственное приложение для Windows/macOS/Linux с панелью задач, автозапуском и автономным режимом. -- **Режим разделения портов** — API и панель мониторинга на отдельных портах для расширенных сценариев (обратный прокси-сервер, сеть контейнеров). -- **Cloud Sync** — синхронизация конфигурации между устройствами через Cloudflare Workers. -- **Резервные копии БД** — автоматическое резервное копирование, восстановление, экспорт и импорт всех настроек. +- **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
-
🌍 12. «Интерфейс только на английском языке, и моя команда не говорит по-английски»
+🌍 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. -**Как OmniRoute решает эту проблему:** +**How OmniRoute solves it:** -- **Панель управления i18n — 30 языков** — Все более 500 клавиш переведены, включая арабский, болгарский, датский, немецкий, испанский, финский, французский, иврит, хинди, венгерский, индонезийский, итальянский, японский, корейский, малайский, голландский, норвежский, польский, португальский (PT/BR), румынский, русский, словацкий, шведский, тайский, украинский, вьетнамский, китайский, филиппинский, английский -- **Поддержка RTL** — поддержка написания справа налево для арабского языка и иврита. -- **Многоязычные файлы README** — 30 полных переводов документации. -- **Выбор языка** — значок глобуса в заголовке для переключения в реальном времени. +- **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. «Мне нужно больше, чем просто чат — мне нужны вложения, изображения, аудио»
+🔄 13. "I need more than chat — I need embeddings, images, audio"
-ИИ — это не просто завершение чата. Разработчикам необходимо генерировать изображения, расшифровывать аудио, создавать вложения для RAG, изменять ранжирование документов и модерировать контент. Каждый API имеет свою конечную точку и формат. +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. -**Как OmniRoute решает эту проблему:** +**How OmniRoute solves it:** -- **Встраивания** — `/v1/embeddings` с 6 поставщиками и более чем 9 моделями. -- **Генерация изображений** — `/v1/images/generations` с 10 поставщиками и более чем 20 моделями (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigradity, SD WebUI, ComfyUI) -- **Преобразование текста в видео** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) и SD WebUI. -- **Преобразование текста в музыку** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen) -- **Аудиотранскрипция** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3 -- **Преобразование текста в речь** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, Inworld, Cartesia, PlayHT и + существующие поставщики -- **Модерация** — `/v1/moderations` — Проверка безопасности контента. -- **Реранжирование** — `/v1/rerank` — Изменение ранжирования релевантности документа. -- **API ответов** — полная поддержка `/v1/responses` для Кодекса. +- **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. «У меня нет возможности тестировать и сравнивать качество разных моделей»
+🧪 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. -**Как OmniRoute решает эту проблему:** +**How OmniRoute solves it:** -- **Оценки LLM** — тестирование золотого набора с 10 предварительно загруженными вариантами, охватывающими приветствия, математику, географию, генерацию кода, соответствие JSON, перевод, уценку, отказ от безопасности. -- **4 стратегии сопоставления** — `exact`, `contains`, `regex`, `custom` (функция JS) -- **Тестовый стенд (Testbed)** — пакетное тестирование с несколькими входными данными и ожидаемыми результатами, сравнение между поставщиками. -- **Тестер чата** — полный цикл с визуальным отображением ответов. -- **Живой монитор** — поток всех запросов, проходящих через прокси, в реальном времени. +- **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. «Мне нужно масштабироваться без потери производительности»
+📈 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. -**Как OmniRoute решает эту проблему:** +**How OmniRoute solves it:** -- **Семантический кеш** — двухуровневый кеш (сигнатура + семантика) снижает стоимость и задержку. -- **Request Idempotency** — окно дедупликации 5 с для идентичных запросов. -- **Обнаружение ограничения скорости** — число оборотов в минуту для каждого провайдера, минимальный разрыв и максимальное одновременное отслеживание. -- **Редактируемые ограничения скорости** — настраиваемые значения по умолчанию в меню «Настройки» → «Устойчивость с постоянством». -- **Кэш проверки ключей API** — трехуровневый кеш для повышения производительности. -- **Панель состояния с телеметрией** — задержка p50/p95/p99, статистика кэша, время безотказной работы. +- **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 +- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence +- **API Key Validation Cache** — 3-tier cache for production performance +- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
-
🤖 16. «Я хочу глобально контролировать поведение модели»
+🤖 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. -**Как OmniRoute решает эту проблему:** +**How OmniRoute solves it:** -- **Внедрение системных подсказок** — глобальное приглашение применяется ко всем запросам. -- **Продуманная проверка бюджета** — контроль распределения токенов для каждого запроса (сквозной, автоматический, пользовательский, адаптивный) -- **6 стратегий маршрутизации** — глобальные стратегии, определяющие распределение запросов. -- **Маршрутизатор с подстановочными знаками** — шаблоны `provider/*` динамически маршрутизируются к любому поставщику. -- **Переключение/включение комбо** — переключение комбо непосредственно с панели управления. -- **Переключение поставщика** — включение/отключение всех подключений к провайдеру одним щелчком мыши. -- **Заблокированные поставщики** — исключить определенных поставщиков из списка `/v1/models`. +- **System Prompt Injection** — Global prompt applied to all requests +- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive) +- **6 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 +- **Provider Toggle** — Enable/disable all connections for a provider with one click +- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
-
🧰 17. «Мне нужны инструменты MCP как первоклассные возможности продукта»
+🧰 17. "I need MCP tools as first-class product capabilities"
-Многие шлюзы AI предоставляют MCP только как скрытую деталь реализации. Командам нужен видимый и управляемый операционный уровень. +Many AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer. -**Как OmniRoute решает эту проблему:** +**How OmniRoute solves it:** -- MCP отображается на панели навигации панели управления и на вкладке протокола конечной точки. -- Отдельная страница управления MCP с процессами, инструментами, объемами работ и аудитом. -- Встроенное краткое руководство по `omniroute --mcp` и адаптации клиентов. +- 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. «Мне нужна оркестровка A2A с путями задач синхронизации и потоковой передачи»
+🧠 18. "I need A2A orchestration with sync + stream task paths"
-Рабочие процессы агента требуют как прямых ответов, так и длительного потокового выполнения с контролем жизненного цикла. +Agent workflows need both direct replies and long-running streamed execution with lifecycle control. -**Как OmniRoute решает эту проблему:** +**How OmniRoute solves it:** -- Конечная точка A2A JSON-RPC (`POST /a2a`) с `message/send` и `message/stream`. -- Потоковая передача SSE с распространением состояния терминала -- API жизненного цикла задач для `tasks/get` и `tasks/cancel`. +- 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. «Мне нужно реальное состояние процесса MCP, а не угаданный статус»
+🛰️ 19. "I need real MCP process health, not guessed status"
-Оперативным группам необходимо знать, действительно ли MCP работает, а не только доступен ли API. +Operational teams need to know if MCP is actually alive, not just whether an API is reachable. -**Как OmniRoute решает эту проблему:** +**How OmniRoute solves it:** -- Файл контрольного сигнала времени выполнения с PID, временными метками, транспортом, количеством инструментов и режимом области действия. -- API статуса MCP, объединяющий пульс + недавнюю активность -- Карты состояния пользовательского интерфейса для актуальности процессов, времени безотказной работы и пульса. +- 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. «Мне нужно проверяемое выполнение инструмента MCP»
+📋 20. "I need auditable MCP tool execution"
-Когда инструменты изменяют конфигурацию или запускают действия операционной системы, командам необходима судебно-медицинская отслеживаемость. +When tools mutate config or trigger ops actions, teams need forensic traceability. -**Как OmniRoute решает эту проблему:** +**How OmniRoute solves it:** -- Ведение журнала аудита на основе SQLite для вызовов инструментов MCP. -- Фильтры по инструменту, успеху/неуспеху, ключу API и нумерации страниц. -- Таблица аудита панели мониторинга + конечные точки статистики для автоматизации +- 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. «Мне нужны ограниченные разрешения MCP для каждой интеграции»
+🔐 21. "I need scoped MCP permissions per integration"
-Разные клиенты должны иметь минимальный доступ к категориям инструментов. +Different clients should have least-privilege access to tool categories. -**Как OmniRoute решает эту проблему:** +**How OmniRoute solves it:** -- 9 детальных областей MCP для контролируемого доступа к инструментам -- Обеспечение соблюдения границ и видимость в пользовательском интерфейсе управления MCP. -- Безопасное положение по умолчанию для рабочих инструментов. +- 9 granular MCP scopes for controlled tool access +- Scope enforcement and visibility in MCP management UI +- Safe default posture for operational tooling
-
⚙️ 22. «Мне нужен оперативный контроль без передислокации»
+⚙️ 22. "I need operational controls without redeploying"
-Командам необходимы быстрые изменения во время выполнения во время инцидентов или событий, связанных с затратами. +Teams need quick runtime changes during incidents or cost events. -**Как OmniRoute решает эту проблему:** +**How OmniRoute solves it:** -- Переключение комбо-активации прямо с панели управления MCP. -- Применение профилей устойчивости из предварительно определенных пакетов политик. -- Сброс состояния автоматического выключателя с той же панели управления. +- Switch combo activation directly from MCP dashboard +- Apply resilience profiles from pre-defined policy packs +- Reset circuit breaker state from the same operations panel
-
🔄 23. «Мне нужна оперативная видимость и отмена жизненного цикла задачи A2A»
+🔄 23. "I need live A2A task lifecycle visibility and cancellation"
-Без прозрачности жизненного цикла инциденты с задачами становится трудно сортировать. +Without lifecycle visibility, task incidents become hard to triage. -**Как OmniRoute решает эту проблему:** +**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. «Мне нужны метрики активного потока для загрузки A2A»
+🌊 24. "I need active stream metrics for A2A load"
-Рабочие процессы потоковой передачи требуют оперативного понимания параллелизма и живых соединений. +Streaming workflows require operational insight into concurrency and live connections. -**Как OmniRoute решает эту проблему:** +**How OmniRoute solves it:** -- Счетчики активных потоков интегрированы в статус A2A -- Временная метка последней задачи и количество состояний -- Карты информационной панели A2A для мониторинга операций в реальном времени. +- Active stream counters integrated into A2A status +- Last task timestamp and per-state counts +- A2A dashboard cards for real-time ops monitoring
-
🪪 25. «Мне нужно стандартное обнаружение агента для клиентов»
+🪪 25. "I need standard agent discovery for clients"
-Внешним клиентам и оркестраторам для адаптации необходимы машиночитаемые метаданные. +External clients and orchestrators need machine-readable metadata for onboarding. -**Как OmniRoute решает эту проблему:** +**How OmniRoute solves it:** -- Карта агента открыта по адресу `/.well-known/agent.json`. -- Возможности и навыки, отображаемые в пользовательском интерфейсе управления. -- API статуса A2A включает метаданные обнаружения для автоматизации. +- Agent Card exposed at `/.well-known/agent.json` +- Capabilities and skills shown in management UI +- A2A status API includes discovery metadata for automation
-
🧭 26. «Мне нужна возможность обнаружения протокола в UX продукта»
+🧭 26. "I need protocol discoverability in the product UX"
-Если пользователи не могут обнаружить поверхности протокола, качество внедрения и поддержки снижается. +If users cannot discover protocol surfaces, adoption and support quality drop. -**Как OmniRoute решает эту проблему:** +**How OmniRoute solves it:** -- Записи на боковой панели для MCP и A2A. -- Вкладка «Протоколы» на странице конечной точки с быстрым запуском и статусом. -- Ссылки из обзора на специальные панели управления. +- 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. «Мне нужна сквозная проверка протокола с реальными клиентами»
+🧪 27. "I need end-to-end protocol validation with real clients"
-Пробных тестов недостаточно для проверки совместимости протокола перед выпуском. +Mock tests are not enough to validate protocol compatibility before release. -**Как OmniRoute решает эту проблему:** +**How OmniRoute solves it:** -- Пакет E2E, который загружает приложение и использует настоящий клиентский транспорт MCP SDK. -- Клиент A2A тестирует потоки обнаружения, отправки, потоковой передачи, получения и отмены. -- Перекрестная проверка утверждений с помощью API-интерфейсов аудита MCP и задач A2A. +- 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. «Мне нужна унифицированная наблюдаемость на всех интерфейсах»
+📡 28. "I need unified observability across all interfaces"
-Разделение наблюдаемости по протоколам создает «слепые зоны» и увеличивает MTTR. +Splitting observability by protocol creates blind spots and longer MTTR. -**Как OmniRoute решает эту проблему:** +**How OmniRoute solves it:** -- Унифицированные дашборды/логи/аналитика в одном продукте -- Здоровье + аудит + телеметрия запросов на уровнях OpenAI, MCP и A2A. -- Операционные API для статуса и автоматизации +- Unified dashboards/logs/analytics in one product +- Health + audit + request telemetry across OpenAI, MCP, and A2A layers +- Operational APIs for status and automation
-
💼 29. «Мне нужна одна среда выполнения для прокси + инструментов + оркестровки агентов»
+💼 29. "I need one runtime for proxy + tools + agent orchestration"
-Запуск множества отдельных служб увеличивает эксплуатационные расходы и количество видов сбоев. +Running many separate services increases operational cost and failure modes. -**Как OmniRoute решает эту проблему:** +**How OmniRoute solves it:** -- OpenAI-совместимый прокси, сервер MCP и сервер A2A в одном стеке -- Общая аутентификация, устойчивость, хранилище данных и наблюдаемость. -- Согласованная модель политики на всех поверхностях взаимодействия. +- 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
-
-### Примеры сборников сценариев (интегрированные варианты использования)
+### Example Playbooks (Integrated Use Cases)
-**Пособие А: максимальное использование платной подписки + дешевое резервное копирование**
+**Playbook A: Maximize paid subscription + cheap backup**
```txt
Combo: "maximize-claude"
@@ -683,7 +694,7 @@ Monthly cost: $20 + small backup spend
Outcome: higher quality, near-zero interruption
```
-**Пособие Б: стек кодирования с нулевой стоимостью**
+**Playbook B: Zero-cost coding stack**
```txt
Combo: "free-forever"
@@ -695,7 +706,7 @@ Monthly cost: $0
Outcome: stable free coding workflow
```
-**Пособие C: Всегда работающая резервная цепочка 24 часа в сутки, 7 дней в неделю**
+**Playbook C: 24/7 always-on fallback chain**
```txt
Combo: "always-on"
@@ -708,65 +719,132 @@ Combo: "always-on"
Outcome: deep fallback depth for deadline-critical workloads
```
-**Сборник D: Операции агента с помощью MCP + A2A**
+**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/mcp and /dashboard/a2a
-4) Control incidents with resilience profile + task cancellation
+3) Observe via /dashboard/endpoint (MCP and A2A tabs)
+4) Toggle services via inline status controls
```
---
-## ⚡ Быстрый старт
+## 🆓 Start Free — Zero Configuration Cost
-**1. Установите глобально:**
+> 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 **iFlow** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |
+| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |
+| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |
+| 5 | `/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).
+
+## Быстрый старт
+
+### 1) Install and run
```bash
npm install -g omniroute
omniroute
```
-🎉 Dashboard открывается на `http://localhost:20128`
+> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:
+>
+> ```bash
+> pnpm install -g omniroute
+> pnpm approve-builds -g # Select all packages → approve
+> omniroute
+> ```
-| Команда | Описание |
-| ----------------------- | ------------------------------------------ |
-| `omniroute` | Запустить сервер (порт по умолчанию 20128) |
-| `omniroute --port 3000` | Использовать другой порт |
-| `omniroute --no-open` | Не открывать браузер автоматически |
-| `omniroute --help` | Показать справку |
+Dashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.
-**2. Подключите БЕСПЛАТНОГО провайдера:**
+| 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 |
-Dashboard → Провайдеры → Подключить **Claude Code** или **Antigravity** → OAuth вход → Готово!
+Optional split-port mode:
-**3. Используйте в CLI-инструменте:**
-
-```
-Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Настройки:
- Endpoint: http://localhost:20128/v1
- API Key: [скопируйте из dashboard]
- Model: if/kimi-k2-thinking
+```bash
+PORT=20128 DASHBOARD_PORT=20129 omniroute
+# API: http://localhost:20128/v1
+# Dashboard: http://localhost:20129
```
-**Готово!** Начните программировать с БЕСПЛАТНЫМИ AI-моделями.
+### 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
+
+```txt
+Base URL: http://localhost:20128/v1
+API Key: [copy from Endpoint page]
+Model: if/kimi-k2-thinking (or any provider/model prefix)
+```
+
+Works with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.
+
+### 4) Enable and validate protocols (v2.0)
+
+**MCP (for tool-driven operations):**
+
+```bash
+omniroute --mcp
+```
+
+Then connect your MCP client over `stdio` and test tools like:
+
+- `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 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
+PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev
```
---
## 🐳 Docker
-OmniRoute доступен как публичный Docker-образ на [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
+OmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
-**Быстрый запуск:**
+**Quick run:**
```bash
docker run -d \
@@ -777,10 +855,10 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**С файлом окружения:**
+**With environment file:**
```bash
-# Скопируйте и отредактируйте .env
+# Copy and edit .env first
cp .env.example .env
docker run -d \
@@ -792,295 +870,627 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Используя Docker Compose:**
+**Using Docker Compose:**
```bash
-# Базовый профиль (без CLI-инструментов)
+# Base profile (no CLI tools)
docker compose --profile base up -d
-# CLI-профиль (Claude Code, Codex, OpenClaw встроены)
+# CLI profile (Claude Code, Codex, OpenClaw built-in)
docker compose --profile cli up -d
```
-| Образ | Тег | Размер | Описание |
-| ------------------------ | -------- | ------ | -------------------------- |
-| `diegosouzapw/omniroute` | `latest` | ~250MB | Последний стабильный релиз |
-| `diegosouzapw/omniroute` | `1.0.6` | ~250MB | Текущая версия |
+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.
+- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.
+- 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` | `1.0.3` | ~250MB | Current version |
---
----
+## 🖥️ Desktop App — Offline & Always-On
-## 🖥️
+> 🆕 **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.
-> 🆕 **НОВИНКА!** OmniRoute теперь доступен как **нативное настольное приложение** для Windows, macOS и Linux.
+Run OmniRoute as a standalone desktop app — no terminal, no browser, no internet required for local models. The Electron-based app includes:
-- 🖥️ **Нативное Окно** — Выделенное окно с интеграцией в системный трей
-- 🔄 **Автозапуск** — Запуск OmniRoute при входе в систему
-- 🔔 **Нативные Уведомления** — Оповещения об исчерпании квоты
-- ⚡ **Установка в Один Клик** — NSIS (Windows), DMG (macOS), AppImage (Linux)
-- 🌐 **Оффлайн Режим** — Полностью работает без интернета
+- 🖥️ **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
+
+### Быстрый старт
```bash
-npm run electron:dev # Режим разработки
-npm run electron:build # Текущая платформа
+# 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)
+npm run electron:build:mac # macOS (.dmg) — x64 & arm64
npm run electron:build:linux # Linux (.AppImage)
```
-📖 Полная документация: [`electron/README.md`](electron/README.md)
+### 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 | Провайдер | Стоимость | Сброс квоты | Лучше всего для |
-| ----------------- | ----------------- | ----------------------------- | ------------------ | -------------------------------- |
-| **💳 ПОДПИСКА** | Claude Code (Pro) | $20/мес | 5ч + еженедельно | Уже подписан |
-| | Codex (Plus/Pro) | $20-200/мес | 5ч + еженедельно | Пользователи OpenAI |
-| | Gemini CLI | **БЕСПЛАТНО** | 180K/мес + 1K/день | Все! |
-| | GitHub Copilot | $10-19/мес | Ежемесячно | Пользователи GitHub |
-| **🔑 API KEY** | NVIDIA NIM | **БЕСПЛАТНО** (1000 кредитов) | Одноразово | Бесплатное тестирование |
-| | DeepSeek | По использованию | Нет | Лучшее соотношение цена/качество |
-| | Groq | Беспл. уровень + платный | Ограничено | Сверхбыстрый вывод |
-| | xAI (Grok) | По использованию | Нет | Модели Grok |
-| | Mistral | Беспл. уровень + платный | Ограничено | Европейский AI |
-| | OpenRouter | По использованию | Нет | 100+ моделей |
-| **💰 ДЕШЁВЫЙ** | GLM-4.7 | $0.6/1M | Ежедневно 10ч | Бюджетный бэкап |
-| | MiniMax M2.1 | $0.2/1M | 5ч ротация | Самый дешёвый вариант |
-| | Kimi K2 | $9/мес фикс | 10M токенов/мес | Предсказуемая цена |
-| **🆓 БЕСПЛАТНЫЙ** | iFlow | $0 | Неограниченно | 8 бесплатных моделей |
-| | Qwen | $0 | Неограниченно | 3 бесплатные модели |
-| | Kiro | $0 | Неограниченно | Claude бесплатно |
+| 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 |
+| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |
+| | 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** | iFlow | **$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 |
-**💡 Совет:** Начните с Gemini CLI (180K бесплатно/мес) + iFlow (неограниченно бесплатно) = $0!
+> 🆕 **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
+iFlow (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
-| Функция | Что делает |
-| ------------------------------------------- | ----------------------------------------------------------------------------- |
-| 🎯 **Умный 4-уровневый Fallback** | Авто-маршрутизация: Подписка → API Key → Дешёвый → Бесплатный |
-| 📊 **Отслеживание квот в реальном времени** | Счётчик токенов в реальном времени + обратный отсчёт до сброса |
-| 🔄 **Трансляция формата** | OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro бесшовно |
-| 👥 **Мульти-аккаунт** | Несколько аккаунтов на провайдера с интеллектуальным выбором |
-| 🔄 **Автообновление токенов** | OAuth-токены обновляются автоматически с повторами |
-| 🎨 **Пользовательские комбо** | 6 стратегий: fill-first, round-robin, p2c, random, least-used, cost-optimized |
-| 🧩 **Пользовательские модели** | Добавьте любой ID модели к любому провайдеру |
-| 🌐 **Wildcard-маршрутизатор** | Маршрутизируйте паттерны `provider/*` к любому провайдеру динамически |
-| 🧠 **Бюджет рассуждений** | Режимы passthrough, auto, custom и adaptive для моделей рассуждений |
-| 🔀 **Model Aliases** | Auto-forward deprecated model IDs to current replacements (built-in + custom) |
-| ⚡ **Background Degradation** | Auto-route background tasks (titles, summaries) to cheaper models |
-| 💬 **Инъекция System Prompt** | Глобальный system prompt для всех запросов |
-| 📄 **API Responses** | Полная поддержка OpenAI Responses API (`/v1/responses`) для Codex |
+> 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.
-### 🎵 Мультимодальные API
+### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)
-| Функция | Что делает |
-| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 🖼️ **Генерация изображений** | `/v1/images/generations` — 4 провайдера, 9+ моделей |
-| 📐 **Embeddings** | `/v1/embeddings` — 6 провайдеров, 9+ моделей |
-| 🎤 **Транскрипция аудио** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |
-| 🔊 **Текст в речь** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) |
-| 🛡️ **Модерация** | `/v1/moderations` — Проверки безопасности контента |
-| 🔀 **Reranking** | `/v1/rerank` — Переранжирование релевантности |
+| 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 |
-### 🛡️ Устойчивость и безопасность
+### 🟢 IFLOW MODELS (Free OAuth — No Credit Card)
-| Функция | Что делает |
-| -------------------------------- | -------------------------------------------------------------------------------------- |
-| 🔌 **Circuit Breaker** | Авто-открытие/закрытие по провайдеру с настраиваемыми порогами |
-| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |
-| 🛡️ **Anti-Thundering Herd** | Mutex + семафор для API key провайдеров |
-| 🧠 **Семантический кеш** | Двухуровневый кеш (сигнатура + семантика) снижает стоимость |
-| ⚡ **Идемпотентность запросов** | 5с окно дедупликации для дублирующихся запросов |
-| 🔒 **Спуфинг TLS Fingerprint** | Обход обнаружения ботов через wreq-js |
-| 🔏 **CLI Fingerprint Matching** | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP** |
-| 🌐 **Фильтрация IP** | Allowlist/blocklist для контроля доступа к API |
-| 📊 **Настраиваемые Rate Limits** | Настраиваемые RPM, минимальный интервал, макс. конкуррентность |
-| 💾 **Rate Limit Persistence** | Learned limits survive restarts via SQLite with 60s debounce + 24h staleness |
-| 🔄 **Token Refresh Resilience** | Per-provider circuit breaker (5 fails→30min) + 30s timeout per attempt |
+| 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 |
-### 📊 Наблюдаемость и аналитика
+### 🟡 QWEN MODELS (Device Code Auth)
-| Функция | Что делает |
-| -------------------------------- | ------------------------------------------------------------------------ |
-| 📝 **Логи запросов** | Режим debug с полными логами запросов/ответов |
-| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |
-| 💾 **Логи SQLite** | Постоянные proxy-логи переживают перезапуски |
-| 📊 **Dashboard аналитики** | Recharts: карточки статистики, график использования, таблица провайдеров |
-| 📈 **Отслеживание прогресса** | Opt-in SSE-события прогресса для стриминга |
-| 🧪 **Оценки LLM** | Тестирование с golden set и 4 стратегиями сравнения |
-| 🔍 **Телеметрия запросов** | Агрегация латентности p50/p95/p99 + трекинг X-Request-Id |
-| 📋 **Логи + Квоты** | Отдельные страницы для просмотра логов и отслеживания квот |
-| 🏥 **Dashboard здоровья** | Uptime, состояния circuit breaker, блокировки, статистика кеша |
-| 💰 **Отслеживание стоимости** | Управление бюджетом + настройка цен по моделям |
+| 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) |
-### ☁️ Деплой и синхронизация
+### 🟣 GEMINI CLI (Google OAuth)
-| Функция | Что делает |
-| -------------------------- | --------------------------------------------------------------------------- |
-| 💾 **Cloud Sync** | Синхронизация настроек между устройствами через Cloudflare Workers |
-| 🌐 **Деплой куда угодно** | Localhost, VPS, Docker, Cloudflare Workers |
-| 🔑 **Управление API Keys** | Генерация, ротация и настройка scope API keys по провайдерам |
-| 🧙 **Мастер настройки** | 4-шаговая настройка для новых пользователей |
-| 🔧 **Dashboard CLI Tools** | Настройка в один клик для Claude, Codex, Cline, OpenClaw, Kilo, Antigravity |
-| 🔄 **Бэкапы БД** | Автоматическое резервное копирование и восстановление всех настроек |
+| Model | Prefix | Limit | Rate Limit |
+| ------------------------ | ------ | --------------------------- | ------------- |
+| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |
+| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |
+
+### ⚫ 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
+> iFlow (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 v2.0 is built as an operational platform, not just a relay proxy.
+
+### 🆕 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 Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |
+| 🤖 **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 (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) |
+| 🤝 **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** | 9 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 combo, apply resilience profiles, reset breakers from one control surface |
+
+### 🧠 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** | 6 balancing strategies + fallback chain control |
+| 🌐 **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) |
+| 💬 **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 |
+| ----------------------------------- | -------------------------------------------------------------------------------------- |
+| 🔌 **Circuit Breakers** | Per-model trip/recover with threshold controls |
+| 🎯 **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 |
+| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |
+| 🔑 **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 |
+
+### 📊 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 |
+| 📋 **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 |
+
+### ☁️ Deployment & Platform
+
+| Feature | What It Does |
+| ----------------------------- | --------------------------------------------------------- |
+| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |
+| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |
+| 💾 **Cloud Sync** | Configuration sync via cloud worker |
+| 🔄 **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 |
+
+### Feature Deep Dive
+
+#### Smart fallback with practical cost control
+
+```txt
+Combo: "my-coding-stack"
+ 1. cc/claude-opus-4-6
+ 2. nvidia/llama-3.3-70b
+ 3. glm/glm-4.7
+ 4. if/kimi-k2-thinking
+```
+
+When quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.
+
+#### 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)
+
+#### 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)
🚀 30. «Мне нужно реализовать агентские рабочие процессы без разрастания связующего кода»
+🚀 30. "I need to ship agentic workflows without glue-code sprawl"
-Команды теряют скорость при объединении нескольких специальных сервисов и сценариев. +Teams lose velocity when stitching multiple ad-hoc services and scripts. -**Как OmniRoute решает эту проблему:** +**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)
-
-## 🧪 Оценки (Evals)
+📖 Подробности функций
+🧩 MCP Setup (Model Context Protocol)
-### 🎯 Умный 4-уровневый Fallback +Start MCP transport in stdio mode: -Создавайте комбо с автоматическим fallback: - -``` -Combo: "my-coding-stack" - 1. cc/claude-opus-4-6 (ваша подписка) - 2. nvidia/llama-3.3-70b (бесплатный NVIDIA API) - 3. glm/glm-4.7 (дешёвый бэкап, $0.6/1M) - 4. if/kimi-k2-thinking (бесплатный fallback) - -→ Автоматически переключается при исчерпании квоты или ошибках +```bash +omniroute --mcp ``` -### 📊 Отслеживание квот в реальном времени +Recommended validation flow: -- Потребление токенов по провайдерам -- Обратный отсчёт до сброса (5 часов, ежедневно, еженедельно) -- Оценка стоимости для платных уровней -- Ежемесячные отчёты о расходах +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: -Бесшовная трансляция между форматами: - -- **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **OpenAI Responses** -- Ваш CLI отправляет формат OpenAI → OmniRoute транслирует → Провайдер получает нативный формат -- Работает с любым инструментом, поддерживающим пользовательские OpenAI endpoints - -### 👥 Мульти-аккаунт - -- Добавляйте несколько аккаунтов на провайдера -- Автоматический round-robin или маршрутизация по приоритету -- Fallback на следующий аккаунт при исчерпании квоты - -### 🔄 Автообновление токенов - -- OAuth-токены обновляются автоматически до истечения -- Без необходимости ручной повторной аутентификации -- Бесшовный опыт по всем провайдерам - -### 🎨 Пользовательские комбо - -- Создавайте неограниченные комбинации моделей -- 6 стратегий: fill-first, round-robin, power-of-two-choices, random, least-used, cost-optimized -- Делитесь комбо между устройствами с Cloud Sync - -### 🏥 Dashboard здоровья - -- Статус системы (uptime, версия, использование памяти) -- Состояния circuit breaker по провайдерам (Closed/Open/Half-Open) -- Статус rate limit и активные блокировки -- Статистика кеша сигнатур -- Телеметрия латентности (p50/p95/p99) + кеш промптов -- Сброс состояния здоровья одним кликом - -### 🔧 Playground транслятора - -- Отладка, тестирование и визуализация трансляции форматов API -- Отправляйте запросы и смотрите, как OmniRoute транслирует между форматами провайдеров -- Бесценно для устранения проблем интеграции - -### 💾 Cloud Sync - -- Синхронизация провайдеров, комбо и настроек между устройствами -- Автоматическая фоновая синхронизация -- Безопасное шифрованное хранилище +- `GET /api/mcp/status` +- `GET /api/mcp/tools` +- `GET /api/mcp/audit` +- `GET /api/mcp/audit/stats`
+
🤝 A2A Setup (Agent2Agent)
-OmniRoute включает встроенный фреймворк оценки для тестирования качества ответов LLM по golden set. Доступ через **Analytics → Evals** в dashboard. +Discover the agent: -### Встроенный Set +```bash +curl http://localhost:20128/.well-known/agent.json +``` -Предзагруженный «OmniRoute Golden Set» содержит 10 тестов: +Send a task: -- Приветствия, математика, география, генерация кода -- Соответствие формату JSON, перевод, markdown -- Отказ от небезопасного контента (Safety refusal), подсчёт, булева логика +```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."}]}}' +``` -### Стратегии оценки +Manage lifecycle: -| Стратегия | Описание | Пример | -| ---------- | ----------------------------------------------------- | -------------------------------- | -| `exact` | Вывод должен совпадать точно | `"4"` | -| `contains` | Вывод должен содержать подстроку (без учёта регистра) | `"Paris"` | -| `regex` | Вывод должен соответствовать regex-паттерну | `"1.*2.*3"` | -| `custom` | Пользовательская JS-функция возвращает true/false | `(output) => output.length > 10` | +- `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: + +```bash +npm run test:protocols:e2e +``` + +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) ```bash -Dashboard → Провайдеры → Подключить Claude Code -→ OAuth вход → Автообновление токенов -→ Отслеживание квоты 5ч + еженедельно +Dashboard → Providers → Connect Claude Code +→ OAuth login → Auto token refresh +→ 5-hour + weekly quota tracking -Модели: +Models: cc/claude-opus-4-6 cc/claude-sonnet-4-5-20250929 cc/claude-haiku-4-5-20251001 ``` -**Совет:** Используйте Opus для сложных задач, Sonnet для скорости. OmniRoute отслеживает квоту по моделям! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! ### OpenAI Codex (Plus/Pro) ```bash -Dashboard → Провайдеры → Подключить Codex -→ OAuth вход (порт 1455) -→ Сброс 5ч + еженедельно +Dashboard → Providers → Connect Codex +→ OAuth login (port 1455) +→ 5-hour + weekly reset -Модели: +Models: cx/gpt-5.2-codex cx/gpt-5.1-codex-max ``` -### Gemini CLI (БЕСПЛАТНО 180K/мес!) +#### 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). + +### Gemini CLI (FREE 180K/month!) ```bash -Dashboard → Провайдеры → Подключить Gemini CLI +Dashboard → Providers → Connect Gemini CLI → Google OAuth -→ 180K completions/мес + 1K/день +→ 180K completions/month + 1K/day -Модели: +Models: gc/gemini-3-flash-preview gc/gemini-2.5-pro ``` -**Лучшая ценность:** Огромный бесплатный уровень! Используйте перед платными. +**Best Value:** Huge free tier! Use this before paid tiers. ### GitHub Copilot ```bash -Dashboard → Провайдеры → Подключить GitHub -→ OAuth через GitHub -→ Ежемесячный сброс (1-е число) +Dashboard → Providers → Connect GitHub +→ OAuth via GitHub +→ Monthly reset (1st of month) -Модели: +Models: gh/gpt-5 gh/claude-4.5-sonnet gh/gemini-3-pro @@ -1089,95 +1499,95 @@ Dashboard → Провайдеры → Подключить GitHub
-
🔑 Провайдеры по API Key
+🔑 API Key Providers
-### NVIDIA NIM (БЕСПЛАТНО 1000 кредитов!) +### NVIDIA NIM (FREE developer access — 70+ models) -1. Регистрация: [build.nvidia.com](https://build.nvidia.com) -2. Получите бесплатный API key (1000 кредитов включены) -3. Dashboard → Добавить провайдера → NVIDIA NIM: +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` -**Модели:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct` и 50+ других +**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more -**Совет:** OpenAI-совместимый API — работает идеально с трансляцией форматов OmniRoute! +**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation! ### DeepSeek -1. Регистрация: [platform.deepseek.com](https://platform.deepseek.com) -2. Получите API key -3. Dashboard → Добавить провайдера → DeepSeek +1. Sign up: [platform.deepseek.com](https://platform.deepseek.com) +2. Get API key +3. Dashboard → Add Provider → DeepSeek -**Модели:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` +**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` -### Groq (Бесплатный уровень доступен!) +### Groq (Free Tier Available!) -1. Регистрация: [console.groq.com](https://console.groq.com) -2. Получите API key (бесплатный уровень включён) -3. Dashboard → Добавить провайдера → Groq +1. Sign up: [console.groq.com](https://console.groq.com) +2. Get API key (free tier included) +3. Dashboard → Add Provider → Groq -**Модели:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` +**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` -**Совет:** Сверхбыстрый вывод — лучший для программирования в реальном времени! +**Pro Tip:** Ultra-fast inference — best for real-time coding! -### OpenRouter (100+ моделей) +### OpenRouter (100+ Models) -1. Регистрация: [openrouter.ai](https://openrouter.ai) -2. Получите API key -3. Dashboard → Добавить провайдера → OpenRouter +1. Sign up: [openrouter.ai](https://openrouter.ai) +2. Get API key +3. Dashboard → Add Provider → OpenRouter -**Модели:** Доступ к 100+ моделям от всех основных провайдеров через один API key. +**Models:** Access 100+ models from all major providers through a single API key.
-
💰 Дешёвые провайдеры (Бэкап)
+💰 Cheap Providers (Backup)
-### GLM-4.7 (Ежедневный сброс, $0.6/1M) +### GLM-4.7 (Daily reset, $0.6/1M) -1. Регистрация: [Zhipu AI](https://open.bigmodel.cn/) -2. Получите API key из Coding Plan -3. Dashboard → Добавить API Key: - - Провайдер: `glm` +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` -**Используйте:** `glm/glm-4.7` +**Use:** `glm/glm-4.7` -**Совет:** Coding Plan предлагает 3× квоту по цене 1/7! Ежедневный сброс в 10:00. +**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -### MiniMax M2.1 (Сброс 5ч, $0.20/1M) +### MiniMax M2.1 (5h reset, $0.20/1M) -1. Регистрация: [MiniMax](https://www.minimax.io/) -2. Получите API key -3. Dashboard → Добавить API Key +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key +3. Dashboard → Add API Key -**Используйте:** `minimax/MiniMax-M2.1` +**Use:** `minimax/MiniMax-M2.1` -**Совет:** Самый дешёвый вариант для длинного контекста (1M токенов)! +**Pro Tip:** Cheapest option for long context (1M tokens)! -### Kimi K2 ($9/мес фикс) +### Kimi K2 ($9/month flat) -1. Подпишитесь: [Moonshot AI](https://platform.moonshot.ai/) -2. Получите API key -3. Dashboard → Добавить API Key +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key +3. Dashboard → Add API Key -**Используйте:** `kimi/kimi-latest` +**Use:** `kimi/kimi-latest` -**Совет:** Фикс $9/мес за 10M токенов = $0.90/1M эффективная стоимость! +**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
-
🆓 БЕСПЛАТНЫЕ провайдеры (Аварийный бэкап)
+🆓 FREE Providers (Emergency Backup)
-### iFlow (8 БЕСПЛАТНЫХ моделей) +### iFlow (5 FREE models via OAuth) ```bash -Dashboard → Подключить iFlow -→ OAuth вход iFlow -→ Неограниченное использование +Dashboard → Connect iFlow +→ iFlow OAuth login +→ Unlimited usage -Модели: +Models: if/kimi-k2-thinking if/qwen3-coder-plus if/glm-4.7 @@ -1185,26 +1595,26 @@ Dashboard → Подключить iFlow if/deepseek-r1 ``` -### Qwen (3 БЕСПЛАТНЫЕ модели) +### Qwen (4 FREE models via Device Code) ```bash -Dashboard → Подключить Qwen -→ Авторизация по коду устройства -→ Неограниченное использование +Dashboard → Connect Qwen +→ Device code authorization +→ Unlimited usage -Модели: +Models: qw/qwen3-coder-plus qw/qwen3-coder-flash ``` -### Kiro (Claude БЕСПЛАТНО) +### Kiro (Claude FREE) ```bash -Dashboard → Подключить Kiro -→ AWS Builder ID или Google/GitHub -→ Неограниченное использование +Dashboard → Connect Kiro +→ AWS Builder ID or Google/GitHub +→ Unlimited usage -Модели: +Models: kr/claude-sonnet-4.5 kr/claude-haiku-4.5 ``` @@ -1212,51 +1622,51 @@ Dashboard → Подключить Kiro
-
🎨 Создание комбо
+🎨 Create Combos
-### Пример 1: Максимизация подписки → Дешёвый бэкап +### Example 1: Maximize Subscription → Cheap Backup ``` -Dashboard → Комбо → Создать новое +Dashboard → Combos → Create New -Название: premium-coding -Модели: - 1. cc/claude-opus-4-6 (Основная подписка) - 2. glm/glm-4.7 (Дешёвый бэкап, $0.6/1M) - 3. minimax/MiniMax-M2.1 (Самый дешёвый fallback, $0.20/1M) +Name: premium-coding +Models: + 1. cc/claude-opus-4-6 (Subscription primary) + 2. glm/glm-4.7 (Cheap backup, $0.6/1M) + 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M) -Используйте в CLI: premium-coding +Use in CLI: premium-coding ``` -### Пример 2: Только бесплатные (Нулевая стоимость) +### Example 2: Free-Only (Zero Cost) ``` -Название: free-combo -Модели: - 1. gc/gemini-3-flash-preview (180K бесплатно/мес) - 2. if/kimi-k2-thinking (неограниченно) - 3. qw/qwen3-coder-plus (неограниченно) +Name: free-combo +Models: + 1. gc/gemini-3-flash-preview (180K free/month) + 2. if/kimi-k2-thinking (unlimited) + 3. qw/qwen3-coder-plus (unlimited) -Стоимость: $0 навсегда! +Cost: $0 forever! ```
-
---
-## 🐛 Устранение неполадок
+## Устранение неполадок
🔧 Интеграция с CLI
+🔧 CLI Integration
### Cursor IDE ``` -Настройки → Модели → Расширенные: +Settings → Models → Advanced: OpenAI API Base URL: http://localhost:20128/v1 - OpenAI API Key: [из dashboard OmniRoute] + OpenAI API Key: [from OmniRoute dashboard] Model: cc/claude-opus-4-6 ``` ### Claude Code -Используйте страницу **CLI Tools** в dashboard для настройки в один клик, или редактируйте `~/.claude/settings.json` вручную. +Use the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually. ### Codex CLI @@ -1269,13 +1679,13 @@ codex "your prompt" ### OpenClaw -**Вариант 1 — Dashboard (рекомендуется):** +**Option 1 — Dashboard (recommended):** ``` -Dashboard → CLI Tools → OpenClaw → Выбрать модель → Применить +Dashboard → CLI Tools → OpenClaw → Select Model → Apply ``` -**Вариант 2 — Вручную:** Редактируйте `~/.openclaw/openclaw.json`: +**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`: ```json { @@ -1291,155 +1701,420 @@ Dashboard → CLI Tools → OpenClaw → Выбрать модель → При } ``` -> **Примечание:** OpenClaw работает только с локальным OmniRoute. Используйте `127.0.0.1` вместо `localhost` для избежания проблем с IPv6. +> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues. ### Cline / Continue / RooCode ``` -Настройки → Конфигурация API: - Провайдер: OpenAI Compatible +Settings → API Configuration: + Provider: OpenAI Compatible Base URL: http://localhost:20128/v1 - API Key: [из dashboard OmniRoute] + 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. +
-
-- **Runtime**: Node.js 20+
-- **Язык**: TypeScript 5.9 — **100% TypeScript** в `src/` и `open-sse/` (v1.0.6)
+## 🛠️ Tech Stack
+
+Нажмите для раскрытия руководства
+Click to expand troubleshooting guide
-**«Language model did not provide messages»** +**"Language model did not provide messages"** -- Квота провайдера исчерпана → Проверьте трекер квот в dashboard -- Решение: Используйте комбо с fallback или переключитесь на более дешёвый уровень +- Provider quota exhausted → Check dashboard quota tracker +- Solution: Use combo fallback or switch to cheaper tier **Rate limiting** -- Квота подписки исчерпана → Fallback на GLM/MiniMax -- Добавьте комбо: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Subscription quota out → Fallback to GLM/MiniMax +- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -**OAuth-токен истёк** +**OAuth token expired** -- Обновляется автоматически OmniRoute -- Если проблема сохраняется: Dashboard → Провайдер → Переподключить +- Auto-refreshed by OmniRoute +- If issues persist: Dashboard → Provider → Reconnect -**Высокие расходы** +**High costs** -- Проверьте статистику в Dashboard → Расходы -- Переключите основную модель на GLM/MiniMax -- Используйте бесплатный уровень (Gemini CLI, iFlow) для некритичных задач +- Check usage stats in Dashboard → Costs +- Switch primary model to GLM/MiniMax +- Use free tier (Gemini CLI, iFlow) for non-critical tasks -**Dashboard открывается на неправильном порту** +**Dashboard/API ports are wrong** -- Установите `PORT=20128` и `NEXT_PUBLIC_BASE_URL=http://localhost:20128` +- `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** +**Cloud sync errors** -- Проверьте что `BASE_URL` указывает на ваш запущенный экземпляр -- Проверьте что `CLOUD_URL` указывает на правильный облачный endpoint -- Держите значения `NEXT_PUBLIC_*` синхронизированными с серверными значениями +- 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** -- Проверьте `INITIAL_PASSWORD` в `.env` -- Если не задан, пароль по умолчанию `123456` +- Check `INITIAL_PASSWORD` in `.env` +- If unset, fallback password is `123456` -**Нет логов запросов** +**No request logs** -- Установите `ENABLE_REQUEST_LOGS=true` в `.env` +- Set `ENABLE_REQUEST_LOGS=true` in `.env` -**Тест подключения показывает «Invalid» для OpenAI-совместимых провайдеров** +**Connection test shows "Invalid" for OpenAI-compatible providers** -- Многие провайдеры не предоставляют endpoint `/models` -- OmniRoute v1.0.6+ включает fallback-валидацию через chat completions -- Убедитесь что base URL содержит суффикс `/v1` +- 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** + +#### Why does Antigravity / Gemini CLI OAuth fail on remote servers? + +The **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console. + +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 + +# For Gemini CLI: +GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com +GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +``` + +**6. Restart OmniRoute** + +```bash +# npm: +npm run dev + +# Docker: +docker restart omniroute +``` + +**7. Try connecting again** + +Dashboard → Providers → Antigravity (or Gemini CLI) → OAuth + +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. + +--- + +
+
---
-## 🛠️
+🇧🇷 Versão em Português
+ +#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos? + +Os provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo. + +As credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticação com: + +``` +Error 400: redirect_uri_mismatch +``` + +#### Solução: Configure suas próprias credenciais OAuth + +Você precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor. + +#### Passo a passo + +**1. Acesse o Google Cloud Console** + +Abra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) + +**2. Crie um novo OAuth 2.0 Client ID** + +- Clique em **"+ Create Credentials"** → **"OAuth client ID"** +- Tipo de aplicativo: **"Web application"** +- Nome: escolha qualquer nome (ex: `OmniRoute Remote`) + +**3. Adicione as Authorized Redirect URIs** + +No campo **"Authorized redirect URIs"**, adicione: + +``` +https://seu-servidor.com/callback +``` + +> Substitua `seu-servidor.com` pelo domínio ou IP do seu servidor (inclua a porta se necessário, ex: `http://45.33.32.156:20128/callback`). + +**4. Salve e copie as credenciais** + +Após criar, o Google mostrará o **Client ID** e o **Client Secret**. + +**5. Configure as variáveis de ambiente** + +No seu `.env` (ou nas variáveis de ambiente do Docker): + +```bash +# Para Antigravity: +ANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com +ANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret + +# Para Gemini CLI: +GEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com +GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret +GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret +``` + +**6. Reinicie o OmniRoute** + +```bash +# Se usando npm: +npm run dev + +# Se usando Docker: +docker restart omniroute +``` + +**7. Tente conectar novamente** + +Dashboard → Providers → Antigravity (ou Gemini CLI) → OAuth + +Agora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará. + +--- + +#### Workaround temporário (sem configurar credenciais próprias) + +Se não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**: + +1. O OmniRoute abrirá a URL de autorização do Google +2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto) +3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue) +4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute +5. Clique em **"Connect"** + +> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.
+
---
-## 📖 Документация
+## Документация
-| Документ | Описание |
-| ----------------------------------------------- | ------------------------------------------------ |
-| [Руководство пользователя](docs/USER_GUIDE.md) | Провайдеры, комбо, интеграция CLI, деплой |
-| [Справка API](docs/API_REFERENCE.md) | Все endpoints с примерами |
-| [Устранение неполадок](docs/TROUBLESHOOTING.md) | Частые проблемы и решения |
-| [Архитектура](docs/ARCHITECTURE.md) | Архитектура системы и внутреннее устройство |
-| [Как внести вклад](CONTRIBUTING.md) | Настройка разработки и руководящие принципы |
-| [Спецификация OpenAPI](docs/openapi.yaml) | Спецификация OpenAPI 3.0 |
-| [Политика безопасности](SECURITY.md) | Сообщение об уязвимостях и практики безопасности |
+| Document | Description |
+| ---------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 16 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/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
+| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
-## 🗺️
+## 🗺️ Roadmap
-## 👥 Участники
+OmniRoute has **210+ 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, P2C account selection |
+| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |
+| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |
+| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider 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
[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
-### Как внести вклад
+### How to Contribute
-1. Сделайте fork репозитория
-2. Создайте ветку функции (`git checkout -b feature/amazing-feature`)
-3. Зафиксируйте изменения (`git commit -m 'Add amazing feature'`)
-4. Отправьте в ветку (`git push origin feature/amazing-feature`)
-5. Откройте Pull Request
+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
-См. [CONTRIBUTING.md](CONTRIBUTING.md) для подробных рекомендаций.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
-### Выпуск новой версии
+### Releasing a New Version
```bash
-# Создайте релиз — публикация в npm происходит автоматически
-gh release create v1.0.6 --title "v1.0.6" --generate-notes
+# Create a release — npm publish happens automatically
+gh release create v2.0.0 --title "v2.0.0" --generate-notes
```
---
-## 📊 История звёзд
+## 📊 Star History
## Stargazers over time
## [](https://starchart.cc/diegosouzapw/OmniRoute)
-## 🙏 Благодарности
+## 🙏 Acknowledgments
-Особая благодарность **[9router](https://github.com/decolua/9router)** от **[decolua](https://github.com/decolua)** — оригинальному проекту, вдохновившему этот форк. OmniRoute строится на этом невероятном фундаменте с дополнительными функциями, мультимодальными API и полной переписью на TypeScript.
+Special thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.
-Особая благодарность **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — оригинальной реализации на Go, вдохновившей этот порт на JavaScript.
+Special thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.
---
-## 📄 Лицензия
+## Лицензия
-Лицензия MIT — см. [LICENSE](LICENSE) для подробностей.
+MIT License - see [LICENSE](LICENSE) for details.
---
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 -- **База данных**: LowDB (JSON) + SQLite (состояние домена + proxy-логи) -- **Стриминг**: Server-Sent Events (SSE) -- **Аутентификация**: OAuth 2.0 (PKCE) + JWT + API Keys -- **Тестирование**: Node.js test runner (368+ юнит-тестов) -- **CI/CD**: GitHub Actions (авто-публикация npm + Docker Hub при релизе) -- **Сайт**: [omniroute.online](https://omniroute.online) -- **Пакет**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute) +- **Database**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions) +- **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) -- **Устойчивость**: Circuit breaker, экспоненциальный backoff, anti-thundering herd, TLS-спуфинг +- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing + +
- Сделано с ❤️ для разработчиков, которые программируют 24/7
+ Built with ❤️ for developers who code 24/7
omniroute.online
+
diff --git a/docs/i18n/ru/docs/FEATURES.md b/docs/i18n/ru/docs/FEATURES.md
new file mode 100644
index 0000000000..ebd04b398b
--- /dev/null
+++ b/docs/i18n/ru/docs/FEATURES.md
@@ -0,0 +1,145 @@
+# OmniRoute — Dashboard Features Gallery (Русский)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/FEATURES.md) · 🇪🇸 [es](../../es/docs/FEATURES.md) · 🇫🇷 [fr](../../fr/docs/FEATURES.md) · 🇩🇪 [de](../../de/docs/FEATURES.md) · 🇮🇹 [it](../../it/docs/FEATURES.md) · 🇷🇺 [ru](../../ru/docs/FEATURES.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FEATURES.md) · 🇯🇵 [ja](../../ja/docs/FEATURES.md) · 🇰🇷 [ko](../../ko/docs/FEATURES.md) · 🇸🇦 [ar](../../ar/docs/FEATURES.md) · 🇮🇳 [in](../../in/docs/FEATURES.md) · 🇹🇭 [th](../../th/docs/FEATURES.md) · 🇻🇳 [vi](../../vi/docs/FEATURES.md) · 🇮🇩 [id](../../id/docs/FEATURES.md) · 🇲🇾 [ms](../../ms/docs/FEATURES.md) · 🇳🇱 [nl](../../nl/docs/FEATURES.md) · 🇵🇱 [pl](../../pl/docs/FEATURES.md) · 🇸🇪 [sv](../../sv/docs/FEATURES.md) · 🇳🇴 [no](../../no/docs/FEATURES.md) · 🇩🇰 [da](../../da/docs/FEATURES.md) · 🇫🇮 [fi](../../fi/docs/FEATURES.md) · 🇵🇹 [pt](../../pt/docs/FEATURES.md) · 🇷🇴 [ro](../../ro/docs/FEATURES.md) · 🇭🇺 [hu](../../hu/docs/FEATURES.md) · 🇧🇬 [bg](../../bg/docs/FEATURES.md) · 🇸🇰 [sk](../../sk/docs/FEATURES.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FEATURES.md) · 🇮🇱 [he](../../he/docs/FEATURES.md) · 🇵🇭 [phi](../../phi/docs/FEATURES.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FEATURES.md)
+
+---
+
+Visual guide to every section of the OmniRoute dashboard.
+
+---
+
+## 🔌 Providers
+
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
+
+
+
+---
+
+## 🎨 Combos
+
+Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
+
+
+
+---
+
+## 📊 Analytics
+
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
+
+
+
+---
+
+## 🏥 System Health
+
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+
+
+
+---
+
+## 🔧 Translator Playground
+
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
+
+
+
+---
+
+## 🎮 Model Playground _(v2.0.9+)_
+
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
+
+---
+
+## 🎨 Themes _(v2.0.5+)_
+
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
+
+## ⚙️ Settings
+
+Comprehensive settings panel with tabs:
+
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning
+- **Advanced** — Configuration overrides
+
+
+
+---
+
+## 🔧 CLI Tools
+
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
+
+
+
+---
+
+## 🤖 CLI Agents _(v2.0.11+)_
+
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
+
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
+
+---
+
+## 🖼️ Media _(v2.0.3+)_
+
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
+
+## 📝 Request Logs
+
+Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
+
+
+
+---
+
+## 🌐 API Endpoint
+
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
+
+
+
+---
+
+## 🔑 API Key Management
+
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
+
+---
+
+## 📋 Audit Log
+
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
+
+---
+
+## 🖥️ Desktop Application
+
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
+
+Key features:
+
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
+
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.
diff --git a/docs/i18n/sk/README.md b/docs/i18n/sk/README.md
index 22b63f9154..6311e66867 100644
--- a/docs/i18n/sk/README.md
+++ b/docs/i18n/sk/README.md
@@ -1,24 +1,94 @@
-omniroute.online
-
-
- # 🚀 OmniRoute — bezplatná brána AI
+# 🚀 OmniRoute — The Free AI Gateway (Slovenčina)
-### Nikdy neprestávajte kódovať. Inteligentné smerovanie na **BEZPLATNÉ a nízkonákladové modely AI** s automatickým vrátením.
-
-_Váš univerzálny proxy server API – jeden koncový bod, 36+ poskytovateľov, nulové prestoje._
-
-**Dokončenia četov • Vkladanie • Generovanie obrázkov • Zvuk • Zmena hodnotenia • 100 % TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Bezplatný poskytovateľ AI pre vašich obľúbených kódovacích agentov
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Pripojte akýkoľvek nástroj IDE alebo CLI poháňaný AI cez OmniRoute – bezplatnú bránu API pre neobmedzené kódovanie._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+` tags no longer leak to clients in SSE streaming responses (#585) |
+| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with per-provider/account quota enforcement, idempotency, SHA-256 storage, and optional GitHub issue reporting |
+| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG → generic fallback chain |
+| 🔄 **Model Auto-Sync** | 24h scheduler and manual UI toggle to sync model lists for built-in and custom OpenAI-compatible providers |
+| 🌐 **OpenCode Zen/Go** | Two new providers from @kang-heewon via PR #530: free tier + subscription tier via `OpencodeExecutor` |
+| 🐛 **Gemini CLI OAuth** | Actionable error when `GEMINI_OAUTH_CLIENT_SECRET` is missing in Docker (was cryptic Google error) |
+| 🐛 **OpenCode config** | `saveOpenCodeConfig()` now correctly writes TOML to `XDG_CONFIG_HOME` |
+| 🐛 **Pinned model override** | `body.model` correctly set to `pinnedModel` on context-cache protection |
+| 🐛 **Codex/Claude loop** | `tool_result` blocks now converted to text to stop infinite loops |
+| 🐛 **Login redirect** | Login no longer freezes after skipping password setup |
+| 🐛 **Windows paths** | MSYS2/Git-Bash paths (`/c/...`) normalized to `C:\...` automatically |
+
+---
+
+## 🖼️ Main Dashboard
+
+
-📡 Všetci agenti sa pripájajú cez ` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**Stop wasting money and hitting limits:**
-### 🆕 What's New in v3.0.0
+- Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**OmniRoute solves this:**
+
+- ✅ **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
+- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool
---
-[](https://www.npmjs.com/package/omniroute)
-[](https://hub.docker.com/r/diegosouzapw/omniroute)
-[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
-[](https://omniroute.online)
-[](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
+## 📧 Support
-[🌐 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)
+> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.
-🌐 **Available in:** 🇺🇸 [English](../../README.md) | 🇧🇷 [Português (Brasil)](../pt-BR/README.md) | 🇪🇸 [Español](../es/README.md) | 🇫🇷 [Français](../fr/README.md) | 🇮🇹 [Italiano](../it/README.md) | 🇷🇺 [Русский](../ru/README.md) | 🇨🇳 [中文 (简体)](../zh-CN/README.md) | 🇩🇪 [Deutsch](../de/README.md) | 🇮🇳 [हिन्दी](../in/README.md) | 🇹🇭 [ไทย](../th/README.md) | 🇺🇦 [Українська](../uk-UA/README.md) | 🇸🇦 [العربية](../ar/README.md) | 🇯🇵 [日本語](../ja/README.md) | 🇻🇳 [Tiếng Việt](../vi/README.md) | 🇧🇬 [Български](../bg/README.md) | 🇩🇰 [Dansk](../da/README.md) | 🇫🇮 [Suomi](../fi/README.md) | 🇮🇱 [עברית](../he/README.md) | 🇭🇺 [Magyar](../hu/README.md) | 🇮🇩 [Bahasa Indonesia](../id/README.md) | 🇰🇷 [한국어](../ko/README.md) | 🇲🇾 [Bahasa Melayu](../ms/README.md) | 🇳🇱 [Nederlands](../nl/README.md) | 🇳🇴 [Norsk](../no/README.md) | 🇵🇹 [Português (Portugal)](../pt/README.md) | 🇷🇴 [Română](../ro/README.md) | 🇵🇱 [Polski](../pl/README.md) | 🇸🇰 [Slovenčina](../sk/README.md) | 🇸🇪 [Svenska](../sv/README.md) | 🇵🇭 [Filipino](../phi/README.md)
-
-
-
----
-
-## 🖼️
-
-
-
- # 🚀 OmniRoute — bezplatná brána AI
+# 🚀 OmniRoute — The Free AI Gateway (Slovenčina)
-### Nikdy neprestávajte kódovať. Inteligentné smerovanie na **BEZPLATNÉ a nízkonákladové modely AI** s automatickým vrátením.
-
-_Váš univerzálny proxy server API – jeden koncový bod, 36+ poskytovateľov, nulové prestoje._
-
-**Dokončenia četov • Vkladanie • Generovanie obrázkov • Zvuk • Zmena hodnotenia • 100 % TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Bezplatný poskytovateľ AI pre vašich obľúbených kódovacích agentov
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Pripojte akýkoľvek nástroj IDE alebo CLI poháňaný AI cez OmniRoute – bezplatnú bránu API pre neobmedzené kódovanie._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+
+
+[](https://www.npmjs.com/package/omniroute)
+[](https://www.npmjs.com/package/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
+[](https://omniroute.online)
+[](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)
+
+
+
+🌐 **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)
+
+---
+
+## 🆕 What's New in v3.0.0
+
+> **Upgrading from v2.9.5?** — See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes.
+
+| Area | Change |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection remediation |
+| ✅ **Route Validation** | All 176 API routes now validated with Zod schemas + `validateBody()` — CI `check:route-validation:t06` passes |
+| 🐛 **omniModel Tag Leak** | Internal `
+
+
+
+---
+
+## 📸 Dashboard Preview
+
+
+
+
+
+---
+
+### 🤖 Free AI Provider for your favorite coding agents
+
+_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._
Click to see dashboard screenshots
+ +| Page | Screenshot | +| -------------- | ------------------------------------------------- | +| **Providers** |  | +| **Combos** |  | +| **Analytics** |  | +| **Health** |  | +| **Translator** |  | +| **Settings** |  | +| **CLI Tools** |  | +| **Usage Logs** |  | +| **Endpoints** |  | + +|
-
+
OpenClaw @@ -92,113 +162,52 @@ _Pripojte akýkoľvek nástroj IDE alebo CLI poháňaný AI cez OmniRoute – be |
http://localhost:20128/v1 alebo http://cloud.omniroute one/v1 modely a kvóta
+📡 All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 — one config, unlimited models and quota
---
-### 🆕 What's New in v3.0.0
+## 🤔 Why OmniRoute?
-| Area | Change |
-| ------------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal ` Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `
-
-
-
----
-
-## 📸
-
-
-
-
-
----
-
-## 🤔 Prečo OmniRoute?
-
-**Prestaňte plytvať peniazmi a dosahovať limity:**
-
-- ...
- -| # | # | -| ----- | ---------------------------------------- | -| **1** |  | -| **2** |  | -| **3** |  | -| **4** |  | -| **5** |  | -| **6** |  | -| **7** |  | -| **8** |  | -| **9** |  | - - Kvóta odberu vyprší nevyužitá každý mesiac
-- Obmedzenia sadzieb vás zastavia uprostred kódovania
-- drahé rozhrania API (20 – 50 USD mesačne na poskytovateľa)
-- Manuálne prepínanie medzi poskytovateľmi
-
-**OmniRoute to rieši:**
-
-- ✅ **Maximalizujte odbery** - Sledujte kvótu, pred resetovaním použite každý bit
-- ✅ **Automatická záloha** - Predplatné → Kľúč API → Lacné → Bezplatne, nulové prestoje
-- ✅ **Viaceré účty** - Obojstranne medzi účtami na poskytovateľa
-- ✅ **Universal** - Funguje s Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, akýmkoľvek nástrojom CLI
-
----
-
-## 📧 Podpora
-
-> 💬 **Pripojte sa k našej komunite!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Získajte pomoc, zdieľajte tipy a buďte informovaní.
-
-- **Web**: [omniroute.online](https://omniroute.online)
+- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Problémy**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Pôvodný projekt**: [9router by decolua](https://github.com/decolua/9router)
+- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 Ako to funguje
+## 🔄 How It Works
```
┌─────────────┐
@@ -227,455 +236,453 @@ Result: Never stop coding, minimal cost
---
-## 🎯 Čo OmniRoute rieši — 30 bodov skutočnej bolesti a prípadov použitia
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **Každý vývojár, ktorý používa nástroje AI, čelí týmto problémom denne.** OmniRoute bol vytvorený tak, aby ich všetky vyriešil – od prekročenia nákladov po regionálne bloky, od prerušených tokov OAuth po operácie protokolov a pozorovateľnosť podniku.
+> **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.
-
💸 1. „Platím za drahé predplatné, ale stále ma prerušujú limity“
+💸 1. "I pay for an expensive subscription but still get interrupted by limits"
-Vývojári platia za Claude Pro, Codex Pro alebo GitHub Copilot 20 – 200 dolárov mesačne. Aj pri platení má kvóta strop – 5 hodín používania, týždenné limity alebo limity za minútu. Počas relácie kódovania poskytovateľ prestane reagovať a vývojár stráca tok a produktivitu. +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. -**Ako to rieši OmniRoute:** +**How OmniRoute solves it:** -- **Inteligentný 4-úrovňový záložný systém** – Ak sa vyčerpá kvóta predplatného, automaticky sa presmeruje na kľúč API → Lacné → Zadarmo s nulovým manuálnym zásahom -- **Sledovanie kvóty v reálnom čase** – Zobrazuje spotrebu tokenov v reálnom čase s resetovaným odpočítavaním (5 hodín, denne, týždenne) - – **Podpora viacerých účtov** – Viacero účtov na poskytovateľa s automatickým opakovaním – keď sa jeden minie, prepne sa na ďalší - – **Vlastné kombá** – Prispôsobiteľné záložné reťazce so 6 stratégiami vyvažovania (najskôr vyplniť, opakovane, P2C, náhodné, najmenej používané, nákladovo optimalizované) -- **Codex Business Quotas** — Monitorovanie kvót pracovného priestoru pre firmy/tím priamo na paneli +- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention +- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly) +- **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 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
-` z modelov ako DeepSeek R1 do štandardizovaných `reasoning_content`
-- **Štruktúrovaný výstup pre Gemini** — `json_schema` → automatická konverzia `responseMimeType`/`responseSchema`
-- **`stream` predvolene je `false`** — Zosúladí sa so špecifikáciou OpenAI, čím sa zabráni neočakávanému SSE v súpravách Python/Rust/Go SDK
+- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 67+ 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
🔌 2. „Potrebujem použiť viacerých poskytovateľov, ale každý má iné API“
+🔌 2. "I need to use multiple providers but each has a different API"
-OpenAI používa jeden formát, Claude (Anthropic) iný a Gemini ďalší. Ak chce vývojár testovať modely od rôznych poskytovateľov alebo medzi nimi záložné riešenie, musí prekonfigurovať súpravy SDK, zmeniť koncové body, vysporiadať sa s nekompatibilnými formátmi. Vlastní poskytovatelia (FriendLI, NIM) majú neštandardné modelové koncové body. +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. -**Ako to rieši OmniRoute:** +**How OmniRoute solves it:** -- **Unified Endpoint** – Jediný `http://localhost:20128/v1` slúži ako proxy pre všetkých 36+ poskytovateľov -- **Formátový preklad** — Automatický a transparentný: OpenAI ↔ Claude ↔ Gemini ↔ Responses API - – **Dezinfekcia odozvy** – Odstráni neštandardné polia (`x_groq`, `usage_breakdown`, `service_tier`), ktoré porušujú OpenAI SDK v1.83+ -- **Normalizácia rolí** – Konvertuje `developer` → `system` pre poskytovateľov, ktorí nie sú OpenAI; `system` → `user` pre GLM/ERNIE - – **Think Tag Extraction** – Extrahuje bloky `
-
🌐 3. „Môj poskytovateľ AI blokuje môj región/krajinu“
+🌐 3. "My AI provider blocks my region/country"
-Poskytovatelia ako OpenAI/Codex blokujú prístup z určitých geografických oblastí. Používatelia dostanú chyby ako `unsupported_country_region_territory` počas pripojení OAuth a API. To je frustrujúce najmä pre vývojárov z rozvojových krajín. +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. -**Ako to rieši OmniRoute:** +**How OmniRoute solves it:** -- **Konfigurácia proxy servera na troch úrovniach** – Konfigurovateľný server proxy na 3 úrovniach: globálny (celá prevádzka), podľa jednotlivých poskytovateľov (iba jeden poskytovateľ) a podľa pripojenia/kľúča -- **Farebné odznaky proxy** — Vizuálne indikátory: 🢢 globálny proxy, 🟡 proxy poskytovateľa, 🔵 proxy pripojenia, vždy zobrazuje IP - – **Výmena tokenov OAuth cez proxy** – tok OAuth prechádza aj cez proxy, čím sa rieši `unsupported_country_region_territory` -- **Testy pripojenia cez proxy** – Testy pripojenia používajú nakonfigurovaný proxy (už žiadne priame obchádzanie) -- **Podpora SOCKS5** — Úplná podpora proxy SOCKS5 pre odchádzajúce smerovanie -- **TLS Fingerprint Spoofing** – Odtlačok prsta TLS podobný prehliadaču cez `wreq-js` na obídenie detekcie robotov +- **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
-` prefix
-- **Len bezplatné kombá** — Reťaz `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = 0 USD/mesiac s nulovými prestojmi
-- **Bezplatné kredity NVIDIA NIM** – integrovaných 1 000 bezplatných kreditov
-- **Cost Optimized Strategy** – Stratégia smerovania, ktorá automaticky vyberie najlacnejšieho dostupného poskytovateľa
+- **Free-Only Combos** — Chain `gc/gemini-3-flash → 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
🆓 4. „Chcem použiť AI na kódovanie, ale nemám peniaze“
+🆓 4. "I want to use AI for coding but I have no money"
-Nie každý môže platiť 20 – 200 $ mesačne za predplatné AI. Študenti, vývojári z rozvíjajúcich sa krajín, fanúšikovia a nezávislí pracovníci potrebujú prístup ku kvalitným modelom za nulové náklady. +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. -**Ako to rieši OmniRoute:** +**How OmniRoute solves it:** -- **Zabudovaní poskytovatelia bezplatnej úrovne** — Natívna podpora pre 100 % bezplatných poskytovateľov: iFlow (8 neobmedzených modelov), Qwen (3 neobmedzené modely), Kiro (Claude zdarma), Gemini CLI (180 000/mesiac zdarma) +- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free) - **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/
-
🔒 5. „Potrebujem chrániť svoju bránu AI pred neoprávneným prístupom“
+🔒 5. "I need to protect my AI gateway from unauthorized access"
-Pri vystavení brány AI do siete (LAN, VPS, Docker) môže ktokoľvek s adresou spotrebovať tokeny/kvótu vývojára. Bez ochrany sú rozhrania API náchylné na nesprávne použitie, rýchle vloženie a zneužitie. +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. -**Ako to rieši OmniRoute:** +**How OmniRoute solves it:** -– **Správa kľúčov API** – Generovanie, rotácia a rozsah podľa poskytovateľa s vyhradenou stránkou `/dashboard/api-manager` -– **Povolenia na úrovni modelu** – Obmedzenie kľúčov API na konkrétne modely (`openai/*`, vzory zástupných znakov) s prepínačom Povoliť všetko/Obmedziť -– **API Endpoint Protection** – Vyžadovať kľúč pre `/v1/models` a blokovať konkrétnych poskytovateľov zo zoznamu - -- **Auth Guard + ochrana CSRF** - Všetky trasy na dashboarde sú chránené middlevérom `withAuth` + tokenmi CSRF -- **Rate Limiter** — Obmedzenie rýchlosti na IP pomocou konfigurovateľných okien -- **IP Filtering** — Zoznam povolených/blokovaných pre riadenie prístupu -- **Prompt Injection Guard** – Dezinfekcia proti škodlivým vzorom výzvy -- **Šifrovanie AES-256-GCM** — Prihlasovacie údaje sú v pokoji zašifrované +- **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. „Môj poskytovateľ zlyhal a stratil som tok kódovania“
+🛑 6. "My provider went down and I lost my coding flow"
-Poskytovatelia AI sa môžu stať nestabilnými, vrátiť chyby 5xx alebo dosiahnuť dočasné limity sadzieb. Ak vývojár závisí od jedného poskytovateľa, bude prerušený. Bez ističov môžu opakované pokusy zlyhať aplikáciu. +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. -**Ako to rieši OmniRoute:** +**How OmniRoute solves it:** -- **Istič pre každého poskytovateľa** — Automatické otváranie/zatváranie s konfigurovateľnými prahmi a chladením (zatvorené/otvorené/polootvorené) -- **Exponenciálne stiahnutie** — Postupné oneskorenie opakovania -- **Anti-Thundering Herd** - ochrana Mutex + semafor proti súbežným opakovaným búrkam -- **Combo Fallback Chains** – Ak primárny poskytovateľ zlyhá, automaticky prepadne reťazcom bez akéhokoľvek zásahu -- **Combo Circuit Breaker** – Automaticky deaktivuje zlyhávajúcich poskytovateľov v rámci kombinovaného reťazca - | 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format | - – **Health Dashboard** – Monitorovanie dostupnosti, stavy ističov, blokovania, štatistiky vyrovnávacej pamäte, latencia p50/p95/p99 +- **Circuit Breaker per-model** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks +- **Exponential Backoff** — Progressive retry delays +- **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 +- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain +- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
-
🔧 7. „Konfigurácia každého nástroja AI je únavná a opakovaná“
+🔧 7. "Configuring each AI tool is tedious and repetitive"
-Vývojári používajú Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Každý nástroj potrebuje inú konfiguráciu (API endpoint, kľúč, model). Prekonfigurovanie pri zmene poskytovateľa alebo modelu je strata času. +Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time. -**Ako to rieši OmniRoute:** +**How OmniRoute solves it:** -- **CLI Tools Dashboard** – Vyhradená stránka s nastavením jedným kliknutím pre Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline - – **GitHub Copilot Config Generator** – Generuje `chatLanguageModels.json` pre kód VS s hromadným výberom modelu -- **Sprievodca registráciou** – Sprievodca nastavením v 4 krokoch pre začínajúcich používateľov - – **Jeden koncový bod, všetky modely** – Nakonfigurujte `http://localhost:20128/v1` raz a získajte prístup k viac ako 36 poskytovateľom +- **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 67+ providers
-
🔑 8. „Správa tokenov OAuth od viacerých poskytovateľov je peklo“
+🔑 8. "Managing OAuth tokens from multiple providers is hell"
-Claude Code, Codex, Gemini CLI, Copilot – všetky používajú OAuth 2.0 s tokenmi, ktorých platnosť sa končí. Vývojári sa musia neustále znovu overovať, riešiť `client_secret is missing`, `redirect_uri_mismatch` a zlyhania na vzdialených serveroch. Obzvlášť problematické je OAuth na LAN/VPS. +Claude Code, Codex, Gemini CLI, 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. -**Ako to rieši OmniRoute:** +**How OmniRoute solves it:** -- **Automatická obnova tokenov** – Tokeny OAuth sa pred vypršaním platnosti obnovujú na pozadí -- **Vstavaný OAuth 2.0 (PKCE)** – Automatický tok pre Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow - – **Multi-Auth OAuth** – Viaceré účty na poskytovateľa prostredníctvom extrakcie tokenov JWT/ID -- **Oprava OAuth LAN/Remote** — Detekcia súkromnej adresy IP pre `redirect_uri` + manuálny režim adresy URL pre vzdialené servery -- **OAuth Behind Nginx** - Používa `window.location.origin` na reverznú kompatibilitu proxy - – **Príručka vzdialeného OAuth** – Podrobný sprievodca povereniami Google Cloud na VPS/Docker +- **Auto Token Refresh** — OAuth tokens refresh in background before expiration +- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow +- **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. "Neviem, koľko míňam alebo kde"
+📊 9. "I don't know how much I'm spending or where"
-Vývojári využívajú viacerých platených poskytovateľov, ale nemajú jednotný pohľad na výdavky. Každý poskytovateľ má svoj vlastný informačný panel fakturácie, ale neexistuje žiadne konsolidované zobrazenie. Neočakávané náklady sa môžu nahromadiť. +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. -**Ako to rieši OmniRoute:** +**How OmniRoute solves it:** -– **Informačný panel analýzy nákladov** – sledovanie nákladov na token a správa rozpočtu podľa poskytovateľa - -- **Obmedzenia rozpočtu na úroveň** – Strop výdavkov na úroveň, ktorý spúšťa automatické záložné právo -- **Konfigurácia cien za model** – Konfigurovateľné ceny za model -- **Štatistiky používania na kľúč API** – Počet žiadostí a časová pečiatka posledného použitia na kľúč - – **Panel Analytics** – štatistické karty, graf používania modelu, tabuľka poskytovateľov s mierami úspešnosti a latenciou +- **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. „Nedokážem diagnostikovať chyby a problémy vo volaniach AI“
+🐛 10. "I can't diagnose errors and problems in AI calls"
-Keď hovor zlyhá, vývojár nevie, či to bol limit sadzby, vypršaný token, nesprávny formát alebo chyba poskytovateľa. Fragmentované protokoly cez rôzne terminály. Bez pozorovateľnosti je ladenie metódou pokus-omyl. +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. -**Ako to rieši OmniRoute:** +**How OmniRoute solves it:** -– **Panel jednotných protokolov** – 4 karty: Protokoly žiadostí, Protokoly proxy, Protokoly auditu, Konzola - -- **Console Log Viewer** — Prehliadač v štýle terminálu v reálnom čase s farebne odlíšenými úrovňami, automatickým posúvaním, vyhľadávaním a filtrovaním -- **Proxy protokoly SQLite** — Trvalé protokoly, ktoré prežijú reštart servera -- **Translator Playground** – 4 režimy ladenia: Playground (preklad formátu), Chat Tester (spiatočný), Test Bench (dávka), Live Monitor (v reálnom čase) - – **Požiadať o telemetriu** – latencia p50/p95/p99 + sledovanie X-request-Id - – **Protokolovanie založené na súboroch s rotáciou** – Konzolový zachytávač zachytáva všetko do protokolu JSON s rotáciou na základe veľkosti +- **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 Proxy Logs** — Persistent logs that survive server restarts +- **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 Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation +- **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. „Nasadenie a údržba brány je zložitá“
+🏗️ 11. "Deploying and maintaining the gateway is complex"
-Inštalácia, konfigurácia a údržba AI proxy v rôznych prostrediach (lokálne, VPS, Docker, cloud) je náročná na prácu. Problémy ako pevne zakódované cesty, `EACCES` v adresároch, konflikty portov a zostavy naprieč platformami zvyšujú trenie. +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. -**Ako to rieši OmniRoute:** +**How OmniRoute solves it:** -- **Globálna inštalácia npm** — `npm install -g omniroute && omniroute` — hotovo -- **Docker Multi-Platform** – natívne AMD64 + ARM64 (Apple Silicon, AWS Graviton, Raspberry Pi) -- **Profily Docker Compose** — `base` (bez nástrojov CLI) a `cli` (s Claude Code, Codex, OpenClaw) -- **Electron Desktop App** – natívna aplikácia pre Windows/macOS/Linux so systémovou lištou, automatickým spustením, offline režimom -- **Split-Port Mode** – API a Dashboard na samostatných portoch pre pokročilé scenáre (reverzný proxy, kontajnerová sieť) -- **Cloud Sync** — Synchronizácia konfigurácie medzi zariadeniami cez Cloudflare Workers -- **DB Backups** — Automatické zálohovanie, obnovenie, export a import všetkých nastavení +- **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
-
🌍 12. „Rozhranie je len v angličtine a môj tím nehovorí po anglicky“
+🌍 12. "The interface is English-only and my team doesn't speak English"
-Tímy v neanglicky hovoriacich krajinách, najmä v Latinskej Amerike, Ázii a Európe, zápasia s rozhraním iba v angličtine. Jazykové bariéry znižujú prijatie a zvyšujú chyby v konfigurácii. +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. -**Ako to rieši OmniRoute:** +**How OmniRoute solves it:** -- **Dashboard i18n — 30 jazykov** — Všetkých 500+ kláves preložených vrátane arabčiny, bulharčiny, dánčiny, nemčiny, španielčiny, fínčiny, francúzštiny, hebrejčiny, hindčiny, maďarčiny, indonézštiny, taliančiny, japončiny, kórejčiny, malajčiny, holandčiny, nórčiny, poľštiny, portugalčiny (PT/BR), rumunčiny, ruštiny, slovenčiny, švédčiny, thajčiny, ukrajinčiny, vietnamčiny, angličtiny -- **Podpora RTL** — Podpora sprava doľava pre arabčinu a hebrejčinu -- **Viacjazyčné README** — 30 kompletných prekladov dokumentácie -- **Language Selector** – ikona zemegule v hlavičke pre prepínanie v reálnom čase +- **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. „Potrebujem viac ako chat – potrebujem vloženie, obrázky, zvuk“
+🔄 13. "I need more than chat — I need embeddings, images, audio"
-AI nie je len dokončenie chatu. Vývojári potrebujú generovať obrázky, prepisovať zvuk, vytvárať vloženia pre RAG, meniť hodnotenie dokumentov a moderovať obsah. Každé API má iný koncový bod a formát. +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. -**Ako to rieši OmniRoute:** +**How OmniRoute solves it:** -- **Vloženie** — `/v1/embeddings` so 6 poskytovateľmi a 9+ modelmi -- **Generácia obrazu** — `/v1/images/generations` s 10 poskytovateľmi a 20+ modelmi (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI) -- **Text-to-Video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) a SD WebUI +- **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) -- **Prepis zvuku** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3 -- **Text-to-Speech** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, Inworld, Cartesia, PlayHT a + existujúci poskytovatelia -- **Moderácie** — `/v1/moderations` — Kontroly bezpečnosti obsahu -- **Zmena poradia** — `/v1/rerank` — Zmena poradia relevantnosti dokumentu -- **Responses API** – plná podpora `/v1/responses` pre kódex +- **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. „Nemám možnosť testovať a porovnávať kvalitu medzi modelmi“
+🧪 14. "I have no way to test and compare quality across models"
-Vývojári chcú vedieť, ktorý model je pre ich prípad použitia najlepší – kód, preklad, zdôvodnenie – ale manuálne porovnávanie je pomalé. Neexistujú žiadne integrované nástroje hodnotenia. +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. -**Ako to rieši OmniRoute:** +**How OmniRoute solves it:** -- **Hodnotenia LLM** – testovanie zlatej sady s 10 predinštalovanými prípadmi zahŕňajúcimi pozdravy, matematiku, geografiu, generovanie kódu, súlad s JSON, preklad, označenie, odmietnutie bezpečnosti -- **4 stratégie zhody** — `exact`, `contains`, `regex`, `custom` (funkcia JS) -- **Testovacia lavica pre prekladateľské ihrisko** – dávkové testovanie s viacerými vstupmi a očakávanými výstupmi, porovnanie medzi poskytovateľmi -- **Chat Tester** – celý spiatočný výlet s vykresľovaním vizuálnej odozvy -- **Live Monitor** – tok všetkých požiadaviek prechádzajúcich cez server proxy v reálnom čase +- **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. „Potrebujem škálovať bez straty výkonu“
+📈 15. "I need to scale without losing performance"
-Keďže objem žiadostí rastie, bez ukladania rovnakých otázok do vyrovnávacej pamäte vznikajú duplicitné náklady. Bez idempotencie duplikát požaduje spracovanie odpadu. Musia sa dodržiavať limity sadzieb na poskytovateľa. +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. -**Ako to rieši OmniRoute:** +**How OmniRoute solves it:** -- **Sémantická vyrovnávacia pamäť** – Dvojvrstvová vyrovnávacia pamäť (podpis + sémantická) znižuje náklady a latenciu -- **Idempotencia požiadavky** – 5-sekundové deduplikačné okno pre identické požiadavky - – **Detekcia limitu rýchlosti** – RPM, minimálna medzera a maximálne súbežné sledovanie jednotlivých poskytovateľov -- **Upraviteľné limity frekvencie** – Konfigurovateľné predvolené hodnoty v Nastaveniach → Odolnosť s perzistenciou -- **Cache na overenie kľúča API** — 3-vrstvová vyrovnávacia pamäť pre produkčný výkon - – **Panel zdravia s telemetriou** – latencia p50/p95/p99, štatistiky vyrovnávacej pamäte, doba prevádzky +- **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 +- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence +- **API Key Validation Cache** — 3-tier cache for production performance +- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
-
🤖 16. „Chcem globálne ovládať správanie modelu“
+🤖 16. "I want to control model behavior globally"
-Vývojári, ktorí chcú všetky odpovede v konkrétnom jazyku, so špecifickým tónom alebo chcú obmedziť tokeny uvažovania. Konfigurovať to v každom nástroji/požiadavke je nepraktické. +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. -**Ako to rieši OmniRoute:** +**How OmniRoute solves it:** -- **System Prompt Injection** – Globálna výzva aplikovaná na všetky požiadavky - – **Thinking Budget Validation** – Zdôvodnenie riadenia prideľovania tokenov na žiadosť (priechodné, automatické, vlastné, adaptívne) -- **6 stratégií smerovania** — Globálne stratégie, ktoré určujú spôsob distribúcie požiadaviek -- **Wildcard Router** — Vzory `provider/*` smerujú dynamicky k akémukoľvek poskytovateľovi -- **Prepínač povoliť/zakázať kombo** — Prepínajte kombinácie priamo z ovládacieho panela -- **Provider Toggle** — Povolenie/zakázanie všetkých pripojení pre poskytovateľa jedným kliknutím - – **Blokovaní poskytovatelia** – vylúčte konkrétnych poskytovateľov zo zoznamu `/v1/models` +- **System Prompt Injection** — Global prompt applied to all requests +- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive) +- **6 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 +- **Provider Toggle** — Enable/disable all connections for a provider with one click +- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
-
🧰 17. "Potrebujem nástroje MCP ako prvotriedne možnosti produktu"
+🧰 17. "I need MCP tools as first-class product capabilities"
-Mnohé brány AI odhaľujú MCP iba ako skrytý detail implementácie. Tímy potrebujú viditeľnú a spravovateľnú operačnú vrstvu. +Many AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer. -**Ako to rieši OmniRoute:** +**How OmniRoute solves it:** -- MCP sa zobrazí na navigačnom paneli a na karte protokolu koncového bodu -- Vyhradená stránka správy MCP s procesmi, nástrojmi, rozsahmi a auditom -- Vstavaný rýchly štart pre `omniroute --mcp` a registráciu klienta +- 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. "Potrebujem orchestráciu A2A s cestami synchronizácie + streamovania"
+🧠 18. "I need A2A orchestration with sync + stream task paths"
-Pracovné postupy agentov vyžadujú priame odpovede a dlhotrvajúce streamované vykonávanie s kontrolou životného cyklu. +Agent workflows need both direct replies and long-running streamed execution with lifecycle control. -**Ako to rieši OmniRoute:** +**How OmniRoute solves it:** -- Koncový bod A2A JSON-RPC (`POST /a2a`) s `message/send` a `message/stream` -- SSE streaming so šírením koncového stavu -- Rozhrania API životného cyklu úloh pre `tasks/get` a `tasks/cancel` +- 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. „Potrebujem skutočné zdravie procesu MCP, nie uhádnutý stav“
+🛰️ 19. "I need real MCP process health, not guessed status"
-Operačné tímy potrebujú vedieť, či je MCP skutočne nažive, nielen to, či je dostupné API. +Operational teams need to know if MCP is actually alive, not just whether an API is reachable. -**Ako to rieši OmniRoute:** +**How OmniRoute solves it:** -- Súbor srdcového tepu za behu s PID, časovými pečiatkami, transportom, počtom nástrojov a režimom rozsahu -- Stavové rozhranie MCP API, ktoré kombinuje srdcový tep + nedávnu aktivitu -- Stavové karty používateľského rozhrania pre sviežosť procesu / dostupnosti / tepu +- 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. "Potrebujem auditovateľné spustenie nástroja MCP"
+📋 20. "I need auditable MCP tool execution"
-Keď nástroje mutujú konfiguráciu alebo spúšťajú akcie operácií, tímy potrebujú forenznú sledovateľnosť. +When tools mutate config or trigger ops actions, teams need forensic traceability. -**Ako to rieši OmniRoute:** +**How OmniRoute solves it:** -- Záznamy auditu podporované SQLite pre volania nástrojov MCP -- Filtre podľa nástroja, úspechu/neúspechu, kľúča API a stránkovania -- Tabuľka auditu palubnej dosky + štatistické koncové body pre automatizáciu +- 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. "Potrebujem povolenia MCP v rozsahu na jednu integráciu"
+🔐 21. "I need scoped MCP permissions per integration"
-Rôzni klienti by mali mať najmenej privilegovaný prístup ku kategóriám nástrojov. +Different clients should have least-privilege access to tool categories. -**Ako to rieši OmniRoute:** +**How OmniRoute solves it:** -- 9 zrnitých rozsahov MCP pre kontrolovaný prístup k nástrojom -- Presadzovanie rozsahu a viditeľnosť v používateľskom rozhraní správy MCP -- Bezpečná východisková poloha pre prevádzkové nástroje +- 9 granular MCP scopes for controlled tool access +- Scope enforcement and visibility in MCP management UI +- Safe default posture for operational tooling
-
⚙️ 22. „Potrebujem prevádzkové ovládacie prvky bez premiestňovania“
+⚙️ 22. "I need operational controls without redeploying"
-Tímy potrebujú rýchle zmeny runtime počas incidentov alebo nákladových udalostí. +Teams need quick runtime changes during incidents or cost events. -**Ako to rieši OmniRoute:** +**How OmniRoute solves it:** -- Aktivácia komba prepínača priamo z ovládacieho panela MCP -- Použite profily odolnosti z preddefinovaných balíkov politík -- Resetujte stav ističa z rovnakého ovládacieho panela +- Switch combo activation directly from MCP dashboard +- Apply resilience profiles from pre-defined policy packs +- Reset circuit breaker state from the same operations panel
-
🔄 23. „Potrebujem viditeľnosť a zrušenie životného cyklu úlohy A2A“
+🔄 23. "I need live A2A task lifecycle visibility and cancellation"
-Bez viditeľnosti životného cyklu sa incidenty úloh ťažko triedia. +Without lifecycle visibility, task incidents become hard to triage. -**Ako to rieši OmniRoute:** +**How OmniRoute solves it:** -- Zoznam úloh / filtrovanie podľa stavu / zručnosti so stránkovaním -- Rozbalenie metadát úloh, udalostí a artefaktov -- Koncový bod zrušenia úlohy a akcia používateľského rozhrania s potvrdením +- 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. „Potrebujem aktívne metriky streamu pre načítanie A2A“
+🌊 24. "I need active stream metrics for A2A load"
-Streamovanie pracovných tokov vyžaduje operačný prehľad o súbežnosti a živých pripojeniach. +Streaming workflows require operational insight into concurrency and live connections. -**Ako to rieši OmniRoute:** +**How OmniRoute solves it:** -- Aktívne počítadlá toku integrované do stavu A2A -- Časová pečiatka poslednej úlohy a počet jednotlivých štátov -- Karty palubnej dosky A2A na monitorovanie operácií v reálnom čase +- Active stream counters integrated into A2A status +- Last task timestamp and per-state counts +- A2A dashboard cards for real-time ops monitoring
-
🪪 25. "Potrebujem štandardné vyhľadávanie agentov pre klientov"
+🪪 25. "I need standard agent discovery for clients"
-Externí klienti a orchestrátori potrebujú strojovo čitateľné metadáta na integráciu. +External clients and orchestrators need machine-readable metadata for onboarding. -**Ako to rieši OmniRoute:** +**How OmniRoute solves it:** -- Karta agenta vystavená na `/.well-known/agent.json` -- Schopnosti a zručnosti zobrazené v používateľskom rozhraní správy -- API stavu A2A obsahuje metaúdaje zisťovania pre automatizáciu +- Agent Card exposed at `/.well-known/agent.json` +- Capabilities and skills shown in management UI +- A2A status API includes discovery metadata for automation
-
🧭 26. "Potrebujem zistiteľnosť protokolu v UX produktu"
+🧭 26. "I need protocol discoverability in the product UX"
-Ak používatelia nemôžu objaviť povrchy protokolov, kvalita prijatia a podpory klesá. +If users cannot discover protocol surfaces, adoption and support quality drop. -**Ako to rieši OmniRoute:** +**How OmniRoute solves it:** -- Položky na bočnom paneli pre MCP a A2A -- Koncový bod Karta Protokoly s rýchlym spustením a stavom -- Odkazy z prehľadu na špecializované riadiace panely +- 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. "Potrebujem komplexné overenie protokolu so skutočnými klientmi"
+🧪 27. "I need end-to-end protocol validation with real clients"
-Falošné testy nestačia na overenie kompatibility protokolu pred vydaním. +Mock tests are not enough to validate protocol compatibility before release. -**Ako to rieši OmniRoute:** +**How OmniRoute solves it:** -- E2E balík, ktorý spúšťa aplikáciu a využíva skutočný prenos klienta MCP SDK -- Klient A2A testuje toky zisťovania, odosielania, streamovania, získavania a rušenia -- Krížová kontrola tvrdení proti auditu MCP a API úloh A2A +- 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. „Potrebujem jednotnú pozorovateľnosť naprieč všetkými rozhraniami“
+📡 28. "I need unified observability across all interfaces"
-Rozdelenie pozorovateľnosti podľa protokolu vytvára slepé miesta a dlhšie MTTR. +Splitting observability by protocol creates blind spots and longer MTTR. -**Ako to rieši OmniRoute:** +**How OmniRoute solves it:** -- Zjednotené informačné panely / protokoly / analýzy v jednom produkte -- Zdravie + audit + telemetria požiadaviek cez vrstvy OpenAI, MCP a A2A -- Operačné API pre stav a automatizáciu +- Unified dashboards/logs/analytics in one product +- Health + audit + request telemetry across OpenAI, MCP, and A2A layers +- Operational APIs for status and automation
-
💼 29. "Potrebujem jeden runtime pre proxy + nástroje + orchestráciu agentov"
+💼 29. "I need one runtime for proxy + tools + agent orchestration"
-Prevádzka mnohých samostatných služieb zvyšuje prevádzkové náklady a spôsoby zlyhania. +Running many separate services increases operational cost and failure modes. -**Ako to rieši OmniRoute:** +**How OmniRoute solves it:** -- Proxy, server MCP a server A2A kompatibilný s OpenAI v jednom zásobníku -- Zdieľaná autentifikácia, odolnosť, ukladanie údajov a pozorovateľnosť -- Konzistentný model politiky na všetkých interakčných plochách +- 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
-
-### Príklady príručiek (integrované prípady použitia)
+### Example Playbooks (Integrated Use Cases)
-**Príručka A: Maximalizujte platené predplatné + lacné zálohovanie**
+**Playbook A: Maximize paid subscription + cheap backup**
```txt
Combo: "maximize-claude"
@@ -687,7 +694,7 @@ Monthly cost: $20 + small backup spend
Outcome: higher quality, near-zero interruption
```
-**Príručka B: Balík kódovania s nulovými nákladmi**
+**Playbook B: Zero-cost coding stack**
```txt
Combo: "free-forever"
@@ -699,7 +706,7 @@ Monthly cost: $0
Outcome: stable free coding workflow
```
-**Príručka C: 24/7 vždy zapnutý záložný reťazec**
+**Playbook C: 24/7 always-on fallback chain**
```txt
Combo: "always-on"
@@ -712,65 +719,132 @@ Combo: "always-on"
Outcome: deep fallback depth for deadline-critical workloads
```
-**Príručka D: Operačný program agenta s MCP + A2A**
+**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/mcp and /dashboard/a2a
-4) Control incidents with resilience profile + task cancellation
+3) Observe via /dashboard/endpoint (MCP and A2A tabs)
+4) Toggle services via inline status controls
```
---
-## ⚡ Rýchly štart
+## 🆓 Start Free — Zero Configuration Cost
-**1. Inštalovať globálne:**
+> 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 **iFlow** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |
+| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |
+| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |
+| 5 | `/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).
+
+## Rýchly štart
+
+### 1) Install and run
```bash
npm install -g omniroute
omniroute
```
-🎉 Dashboard sa otvára o `http://localhost:20128`
+> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:
+>
+> ```bash
+> pnpm install -g omniroute
+> pnpm approve-builds -g # Select all packages → approve
+> omniroute
+> ```
-| Príkaz | Popis |
-| ----------------------- | -------------------------------------- |
-| `omniroute` | Spustiť server (predvolený port 20128) |
-| `omniroute --port 3000` | Použiť vlastný port |
-| `omniroute --no-open` | Neotvárať automaticky prehliadač |
-| `omniroute --help` | Zobraziť pomoc |
+Dashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.
-**2. Pripojte BEZPLATNÉHO poskytovateľa:**
+| 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 |
-Dashboard → Poskytovatelia → Pripojiť **Claude Code** alebo **Antigravity** → Prihlásenie OAuth → Hotovo!
+Optional split-port mode:
-**3. Použitie v nástroji CLI:**
-
-```
-Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Settings:
- Endpoint: http://localhost:20128/v1
- API Key: [copy from dashboard]
- Model: if/kimi-k2-thinking
+```bash
+PORT=20128 DASHBOARD_PORT=20129 omniroute
+# API: http://localhost:20128/v1
+# Dashboard: http://localhost:20129
```
-**To je všetko!** Začnite kódovať s modelmi AI ZDARMA.
+### 2) Connect providers and create your API key
-**Alternatíva – spustiť zo zdroja:**
+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
+
+```txt
+Base URL: http://localhost:20128/v1
+API Key: [copy from Endpoint page]
+Model: if/kimi-k2-thinking (or any provider/model prefix)
+```
+
+Works with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.
+
+### 4) Enable and validate protocols (v2.0)
+
+**MCP (for tool-driven operations):**
+
+```bash
+omniroute --mcp
+```
+
+Then connect your MCP client over `stdio` and test tools like:
+
+- `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 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
+PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev
```
---
## 🐳 Docker
-OmniRoute je k dispozícii ako verejný obrázok Docker na [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
+OmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
-**Rýchly beh:**
+**Quick run:**
```bash
docker run -d \
@@ -781,7 +855,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**So súborom prostredia:**
+**With environment file:**
```bash
# Copy and edit .env first
@@ -796,7 +870,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Pomocou Docker Compose:**
+**Using Docker Compose:**
```bash
# Base profile (no CLI tools)
@@ -806,256 +880,550 @@ docker compose --profile base up -d
docker compose --profile cli up -d
```
-| Obrázok | Tag | Veľkosť | Popis |
-| ------------------------ | -------- | ------- | -------------------------- |
-| `diegosouzapw/omniroute` | `latest` | ~250 MB | Najnovšie stabilné vydanie |
-| `diegosouzapw/omniroute` | `1.0.3` | ~250 MB | Aktuálna verzia |
+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.
+- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.
+- 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` | `1.0.3` | ~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
+### Rýchly štart
+
```bash
-npm run electron:dev # Development mode
+# 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)
+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)
---
-## 💰 Prehľad cien
+## 💰 Pricing at a Glance
-| Úroveň | Poskytovateľ | Náklady | Obnovenie kvóty | Najlepšie pre |
-| ----------------- | ----------------- | --------------------------- | ---------------------------- | --------------------------- |
-| **💳 PREDPLATNÉ** | Claude Code (Pro) | 20 USD/mesiac | 5h + týždenne | Už prihlásené |
-| | Codex (Plus/Pro) | 20 – 200 USD/mesiac | 5h + týždenne | Používatelia OpenAI |
-| | Gemini CLI | **ZADARMO** | 180 tis./mesiac + 1 tis./deň | Všetci! |
-| | GitHub Copilot | 10 – 19 USD/mes. | Mesačne | Používatelia GitHubu |
-| **🔑 API KEY** | NVIDIA NIM | **ZADARMO** (1000 kreditov) | Jednorazovo | Bezplatné testovanie úrovní |
-| | DeepSeek | Platba za použitie | Žiadne | Najlepšia cena/kvalita |
-| | Groq | Voľná úroveň + platené | Obmedzená sadzba | Ultra-rýchle odvodenie |
-| | xAI (Grok) | Platba za použitie | Žiadne | Modely Grok |
-| | Mistral | Voľná úroveň + platené | Obmedzená sadzba | Európska AI |
-| | OpenRouter | Platba za použitie | Žiadne | 100+ modelov |
-| **💰 LACNO** | GLM-4,7 | 0,6 USD/1 milión | Denne 10:00 | Záloha rozpočtu |
-| | MiniMax M2.1 | 0,2 USD/1 milión | 5-hodinové valcovanie | Najlacnejšia možnosť |
-| | Kimi K2 | 9 USD/mesiac byt | 10 miliónov tokenov/mesiac | Predvídateľné náklady |
-| **🆓 ZDARMA** | iFlow | 0 USD | Neobmedzené | 8 modelov zadarmo |
-| | Qwen | 0 USD | Neobmedzené | 3 modely zadarmo |
-| | Kiro | 0 USD | Neobmedzené | Claude zadarmo |
+| 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 |
+| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |
+| | 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** | iFlow | **$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 |
-**💡 Tip pre profesionálov:** Začnite s kombináciou Gemini CLI (180 000 zadarmo/mesiac) + iFlow (neobmedzene zadarmo) = cena 0 $!
+> 🆕 **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
+iFlow (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.
---
-## 💡 Kľúčové vlastnosti
+---
-### 🧠 Základné smerovanie a inteligencia
+## 🆓 Free Models — What You Actually Get
-| Funkcia | Čo to robí |
-| --------------------------------------------- | ----------------------------------------------------------------------------------------------- |
-| 🎯 **Inteligentná 4-úrovňová núdzová záloha** | Automatická trasa: Predplatné → Kľúč API → Lacné → Zadarmo |
-| 📊 **Sledovanie kvóty v reálnom čase** | Živý počet tokenov + reset odpočítavania na poskytovateľa |
-| 🔄 **Formátový preklad** | OpenAI ↔ Claude ↔ Gemini ↔ Kurzor ↔ Kiro bezšvové + dezinfekcia |
-| 👥 **Podpora viacerých účtov** | Viac účtov na poskytovateľa s inteligentným výberom |
-| 🔄 **Automatická obnova tokenov** | Tokeny OAuth sa automaticky obnovia s opätovným pokusom |
-| 🎨 **Vlastné kombá** | 6 stratégií: fill-first, round-robin, p2c, random, najmenej používané, nákladovo optimalizované |
-| 🧩 **Vlastné modely** | Pridajte akékoľvek ID modelu k akémukoľvek poskytovateľovi |
-| 🌐 **Wildcard Router** | Dynamicky smerujte vzory `provider/*` k akémukoľvek poskytovateľovi |
-| 🧠 **Premýšľajúci rozpočet** | Priechodný, automatický, vlastný a adaptívny režim pre modely uvažovania |
-| 🔀 **Model Aliases** | Auto-forward deprecated model IDs to current replacements (built-in + custom) |
-| ⚡ **Background Degradation** | Auto-route background tasks (titles, summaries) to cheaper models |
-| 💬 **Promptné vstrekovanie systému** | Globálna systémová výzva aplikovaná na všetky požiadavky |
-| 📄 **Responses API** | Plná podpora OpenAI Responses API (`/v1/responses`) pre Codex |
+> 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.
-### 🎵 Multimodálne API
+### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)
-| Funkcia | Čo to robí |
-| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 🖼️ **Generovanie obrázkov** | `/v1/images/generations` — 4 poskytovatelia, 9+ modelov |
-| 📐 **Vloženie** | `/v1/embeddings` — 6 poskytovateľov, 9+ modelov |
-| 🎤 **Prepis zvuku** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |
-| 🔊 **Prevod textu na reč** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) |
-| 🛡️ **Moderovania** | `/v1/moderations` — Kontroly bezpečnosti obsahu |
-| 🔀 **Reranking** | `/v1/rerank` — Zmena poradia relevantnosti dokumentu |
+| 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 |
-### 🛡️ Odolnosť a bezpečnosť
+### 🟢 IFLOW MODELS (Free OAuth — No Credit Card)
-| Funkcia | Čo to robí |
-| ------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| 🔌 **Istič** | Automatické otváranie/zatváranie podľa poskytovateľa s konfigurovateľnými prahmi |
-| 🛡️ **Anti-hromové stádo** | Mutex + limit rýchlosti semaforu pre poskytovateľov kľúčov API |
-| 🧠 **Sémantická vyrovnávacia pamäť** | Dvojvrstvová vyrovnávacia pamäť (podpis + sémantika) znižuje náklady a latenciu |
-| ⚡ **Požiadajte o idempotenciu** | 5-sekundové okno na odstránenie duplicitných požiadaviek |
-| 🔒 ** Spoofing odtlačkov prstov TLS** | Obíďte detekciu botov na báze TLS cez wreq-js |
-| 🌐 **Filtrovanie IP** | Zoznam povolených/blokovaných pre riadenie prístupu API |
-| 📊 **Upraviteľné limity sadzieb** | Konfigurovateľné otáčky za minútu, minimálna medzera a maximálna súbežná rýchlosť na systémovej úrovni |
-| 💾 **Rate Limit Persistence** | Learned limits survive restarts via SQLite with 60s debounce + 24h staleness |
-| 🔄 **Token Refresh Resilience** | Per-provider circuit breaker (5 fails→30min) + 30s timeout per attempt |
-| 🛡 **API Endpoint Protection** | Auth gating + blokovanie poskytovateľa pre koncový bod `/models` |
-| 🔒 **Viditeľnosť proxy** | Farebne rozlíšené odznaky: 🟢 globálne, 🟡 poskytovateľ, 🔵 na pripojenie s IP displejom |
-| 🌐 **3-úrovňová konfigurácia proxy** | Nakonfigurujte proxy na globálnej úrovni, na úrovni jednotlivých poskytovateľov alebo na úrovni pripojenia |
+| 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 |
-### 📊 Pozorovateľnosť a analytika
+### 🟡 QWEN MODELS (Device Code Auth)
-| Funkcia | Čo to robí |
-| ------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
-| 📝 **Požiadať o prihlásenie** | Režim ladenia s úplnými protokolmi požiadaviek/odpovedí |
-| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |
-| 💾 **Proxy protokoly SQLite** | Trvalé protokoly proxy prežijú reštart servera |
-| 📊 **Hlavný panel služby Analytics** | Poháňané recharts: štatistické karty, graf používania modelu, tabuľka poskytovateľov |
-| 📈 **Sledovanie pokroku** | Prihlásiť udalosti priebehu SSE pre streamovanie |
-| 🧪 **Hodnotenia LLM** | Testovanie zlatého setu so 4 stratégiami zápasu |
-| 🔍 **Požiadať o telemetriu** | p50/p95/p99 agregácia latencie + sledovanie X-request-Id |
-| 📋 **Hlavný panel denníkov** | Jednotná 4-kartová stránka: Protokoly požiadaviek, Protokoly proxy, Protokoly auditu, Konzola |
-| 🖥️ **Prehliadač denníka konzoly** | Prehliadač v terminálovom štýle v reálnom čase s filtrom úrovní, vyhľadávaním, automatickým posúvaním |
-| 📑 **Protokolovanie založené na súboroch** | Konzolový zachytávač zachytáva všetok výstup do súboru protokolu JSON s rotáciou |
-| 🏥 **Panel zdravia** | Doba prevádzky systému, stavy ističov, uzamknutia, štatistiky vyrovnávacej pamäte |
-| 💰 **Sledovanie nákladov** | Správa rozpočtu + konfigurácia cien podľa modelu |
+| 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) |
-### ☁️ Nasadenie a synchronizácia
+### 🟣 GEMINI CLI (Google OAuth)
-| Funkcia | Čo to robí |
-| ------------------------------ | ------------------------------------------------------------------------------- |
-| 💾 **Cloud Sync** | Synchronizujte konfiguráciu medzi zariadeniami cez Cloudflare Workers |
-| 🌐 **Nasadenie kdekoľvek** | Localhost, VPS, Docker, Cloudflare Workers |
-| 🔑 **Správa kľúčov API** | Generovanie, rotácia a rozsah kľúčov API podľa poskytovateľa |
-| 🧙 **Sprievodca onboardingom** | 4-krokové vedené nastavenie pre začínajúcich používateľov |
-| 🔧 **CLI Tools Dashboard** | Konfigurácia Claude, Codex, Cline, OpenClaw, Kilo, Antigravity jedným kliknutím |
-| 🔄 **Zálohy DB** | Automatické zálohovanie, obnovenie, export a import všetkých nastavení |
-| 🌐 **Internacionalizácia** | Plný i18n s next-intl — podpora angličtiny + portugalčiny (Brazília) |
-| 🌍 **Výber jazyka** | Ikona zemegule v hlavičke na prepínanie jazyka v reálnom čase (🇺🇸/🇧🇷) |
-| 🧹 **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` env var na prepísanie predvolenej cesty úložiska `~/.omniroute` |
+| Model | Prefix | Limit | Rate Limit |
+| ------------------------ | ------ | --------------------------- | ------------- |
+| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |
+| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |
+
+### ⚫ 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
+> iFlow (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 v2.0 is built as an operational platform, not just a relay proxy.
+
+### 🆕 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 Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |
+| 🤖 **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 (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) |
+| 🤝 **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** | 9 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 combo, apply resilience profiles, reset breakers from one control surface |
+
+### 🧠 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** | 6 balancing strategies + fallback chain control |
+| 🌐 **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) |
+| 💬 **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 |
+| ----------------------------------- | -------------------------------------------------------------------------------------- |
+| 🔌 **Circuit Breakers** | Per-model trip/recover with threshold controls |
+| 🎯 **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 |
+| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |
+| 🔑 **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 |
+
+### 📊 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 |
+| 📋 **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 |
+
+### ☁️ Deployment & Platform
+
+| Feature | What It Does |
+| ----------------------------- | --------------------------------------------------------- |
+| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |
+| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |
+| 💾 **Cloud Sync** | Configuration sync via cloud worker |
+| 🔄 **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 |
+
+### Feature Deep Dive
+
+#### Smart fallback with practical cost control
+
+```txt
+Combo: "my-coding-stack"
+ 1. cc/claude-opus-4-6
+ 2. nvidia/llama-3.3-70b
+ 3. glm/glm-4.7
+ 4. if/kimi-k2-thinking
+```
+
+When quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.
+
+#### 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)
+
+#### 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)
🚀 30. „Potrebujem odoslať agentské pracovné postupy bez roztiahnutia kódu lepidla“
+🚀 30. "I need to ship agentic workflows without glue-code sprawl"
-Tímy strácajú rýchlosť pri spájaní viacerých ad-hoc služieb a skriptov. +Teams lose velocity when stitching multiple ad-hoc services and scripts. -**Ako to rieši OmniRoute:** +**How OmniRoute solves it:** -- Jednotná stratégia koncových bodov pre klientov a agentov -- Vstavané používateľské rozhrania na správu protokolov a cesty overovania dymu -- Základy pripravené na výrobu (zabezpečenie, protokolovanie, odolnosť, zálohovanie) +- Unified endpoint strategy for clients and agents +- Built-in protocol management UIs and smoke validation paths +- Production-ready foundations (security, logging, resilience, backup)
-` bloky → `reasoning_content` pre modely myslenia
-- **Štruktúrovaný výstup** — `json_schema` → Gemini's `responseMimeType`/`responseSchema`
-
-### 👥 Podpora viacerých účtov
-
-- Pridajte viac účtov na poskytovateľa
-- Automatické cyklické alebo prioritné smerovanie
-- Návrat k ďalšiemu účtu, keď jeden dosiahne kvótu
-
-### 🔄 Automatické obnovenie tokenu
-
-- Tokeny OAuth sa pred vypršaním platnosti automaticky obnovujú
-- Nie je potrebné manuálne opätovné overenie
-- Bezproblémové skúsenosti u všetkých poskytovateľov
-
-### 🎨 Vlastné kombinácie
-
-- Vytvárajte neobmedzené kombinácie modelov
-- 6 stratégií: vyplňte najskôr, cyklicky, sila dvoch možností, náhodné, najmenej používané, nákladovo optimalizované
-- Zdieľajte kombinácie medzi zariadeniami pomocou synchronizácie cloudu
-
-### 🏥 Panel zdravia
-
-- Stav systému (čas prevádzky, verzia, využitie pamäte)
-- Stavy ističov podľa poskytovateľa (zatvorené/otvorené/polootvorené)
-- Stav limitu sadzby a aktívne blokovania
-- Štatistika vyrovnávacej pamäte podpisov
-- Telemetria latencie (p50/p95/p99) + prompt cache
-- Obnovte zdravotný stav jedným kliknutím
-
-### 🔧 Ihrisko pre prekladateľov
-
-OmniRoute obsahuje výkonné vstavané ihrisko pre prekladateľov so **4 režimami** na ladenie, testovanie a monitorovanie prekladov API:
-
-| Režim | Popis |
-| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **💻 Ihrisko** | Priamy preklad formátu — vložte ľubovoľné telo požiadavky API a okamžite uvidíte, ako ju OmniRoute preloží medzi formátmi poskytovateľov (OpenAI ↔ Claude ↔ Gemini ↔ Responses API). Zahŕňa vzorové šablóny a automatickú detekciu formátu. |
-| **💬 Tester chatu** | Pošlite skutočné žiadosti o rozhovor cez OmniRoute a pozrite si celý spiatočný výlet: svoj vstup, preloženú žiadosť, odpoveď poskytovateľa a preloženú odpoveď späť. Neoceniteľné pre overenie kombinovaného smerovania. |
-| **🧪 Testovacia lavica** | Režim dávkového testovania – definujte viacero testovacích prípadov s rôznymi vstupmi a očakávanými výstupmi, spustite ich všetky naraz a porovnajte výsledky medzi poskytovateľmi a modelmi. |
-| **📱 Živý monitor** | Monitorovanie požiadaviek v reálnom čase – sledujte prichádzajúce požiadavky, ako prechádzajú cez OmniRoute, sledujte, ako prebiehajú preklady formátu naživo, a okamžite identifikujte problémy. |
-
-**Prístup:** Hlavný panel → Prekladač (bočný panel)
-
-### 💾 Cloud Sync
-
-- Synchronizujte poskytovateľov, kombinácie a nastavenia medzi zariadeniami
-- Automatická synchronizácia na pozadí
-- Bezpečné šifrované úložisko
+- `GET /api/mcp/status`
+- `GET /api/mcp/tools`
+- `GET /api/mcp/audit`
+- `GET /api/mcp/audit/stats`
-## 🧪 Hodnotenia (Evals)
+📖 Podrobnosti funkcie
+🧩 MCP Setup (Model Context Protocol)
-### 🎯 Inteligentná 4-úrovňová núdzová záloha +Start MCP transport in stdio mode: -Vytvorte kombá s automatickým núdzovým nastavením: - -``` -Combo: "my-coding-stack" - 1. cc/claude-opus-4-6 (your subscription) - 2. nvidia/llama-3.3-70b (free NVIDIA API) - 3. glm/glm-4.7 (cheap backup, $0.6/1M) - 4. if/kimi-k2-thinking (free fallback) - -→ Auto switches when quota runs out or errors occur +```bash +omniroute --mcp ``` -### 📊 Sledovanie kvóty v reálnom čase +Recommended validation flow: -- Spotreba tokenov na poskytovateľa -- Vynulovať odpočítavanie (5 hodín, denne, týždenne) -- Odhad nákladov pre platené úrovne -- Mesačné správy o výdavkoch +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. -### 🔄 Preklad formátu +Useful APIs for automation: -Bezproblémový preklad medzi formátmi: - -– **OpenAI** ↔ **Claude** ↔ **Blíženci** ↔ **Odpovede OpenAI** - -- Váš nástroj CLI odošle formát OpenAI → OmniRoute preloží → Poskytovateľ dostane natívny formát -- Funguje s akýmkoľvek nástrojom, ktorý podporuje vlastné koncové body OpenAI -- **Dezinfekcia odozvy** – Odstráni neštandardné polia pre prísnu kompatibilitu OpenAI SDK -- **Normalizácia rolí** — `developer` → `system` pre iné ako OpenAI; `system` → `user` pre modely GLM/ERNIE -- **Extrahovanie značiek myslenia** — `
+
🤝 A2A Setup (Agent2Agent)
-OmniRoute obsahuje vstavaný hodnotiaci rámec na testovanie kvality odozvy LLM oproti zlatému súboru. Prístup k nej získate cez **Analytics → Evals** na hlavnom paneli. +Discover the agent: -### Vstavaná zlatá súprava +```bash +curl http://localhost:20128/.well-known/agent.json +``` -Predinštalovaná sada „OmniRoute Golden Set“ obsahuje 10 testovacích prípadov, ktoré zahŕňajú: +Send a task: -- Pozdravy, matematika, geografia, generovanie kódu -- Súlad s formátom JSON, preklad, zníženie -- Bezpečnostné odmietnutie (škodlivý obsah), počítanie, booleovská logika +```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."}]}}' +``` -### Stratégie hodnotenia +Manage lifecycle: -| Stratégia | Popis | Príklad | -| ---------- | ---------------------------------------------------------------------- | -------------------------------- | -| `exact` | Výstup sa musí presne zhodovať | `"4"` | -| `contains` | Výstup musí obsahovať podreťazec (nerozlišujú sa malé a veľké písmená) | `"Paris"` | -| `regex` | Výstup musí zodpovedať vzoru regulárneho výrazu | `"1.*2.*3"` | -| `custom` | Vlastná funkcia JS vracia true/false | `(output) => output.length > 10` | +- `GET /api/a2a/status` +- `GET /api/a2a/tasks` +- `GET /api/a2a/tasks/:id` +- `POST /api/a2a/tasks/:id/cancel` ---- +Operational UI: -## 📖 Sprievodca nastavením +- `/dashboard/a2a` for task/state/stream observability and smoke actions + +
-
+
+💳 Poskytovatelia predplatného
+🧪 End-to-end protocol validation
+ +Validate both protocols with real clients: + +```bash +npm run test:protocols:e2e +``` + +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) @@ -1070,7 +1438,7 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Tip pre profesionálov:** Používajte Opus na zložité úlohy, Sonnet na rýchlosť. OmniRoute sleduje kvótu na model! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! ### OpenAI Codex (Plus/Pro) @@ -1084,7 +1452,24 @@ Models: cx/gpt-5.1-codex-max ``` -### Gemini CLI (ZADARMO 180 000/mesiac!) +#### 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). + +### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -1096,9 +1481,9 @@ Models: gc/gemini-2.5-pro ``` -**Najlepšia hodnota:** Obrovská bezplatná úroveň! Použite to pred platenými úrovňami. +**Best Value:** Huge free tier! Use this before paid tiers. -### Kopilot GitHub +### GitHub Copilot ```bash Dashboard → Providers → Connect GitHub @@ -1114,88 +1499,88 @@ Models:
-
🔑 Kľúčoví poskytovatelia API
+🔑 API Key Providers
-### NVIDIA NIM (1 000 kreditov ZDARMA!) +### NVIDIA NIM (FREE developer access — 70+ models) -1. Zaregistrujte sa: [build.nvidia.com](https://build.nvidia.com) -2. Získajte bezplatný kľúč API (vrátane 1 000 kreditov na odvodenie) -3. Ovládací panel → Pridať poskytovateľa → NVIDIA NIM: - - Kľúč API: `nvapi-your-key` +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` -**Modely:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct` a 50+ ďalších +**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more -**Tip pre profesionálov:** API kompatibilné s OpenAI – bezproblémovo funguje s prekladom formátu OmniRoute! +**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation! ### DeepSeek -1. Zaregistrujte sa: [platform.deepseek.com](https://platform.deepseek.com) -2. Získajte kľúč API -3. Dashboard → Pridať poskytovateľa → DeepSeek +1. Sign up: [platform.deepseek.com](https://platform.deepseek.com) +2. Get API key +3. Dashboard → Add Provider → DeepSeek -**Modely:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` +**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` -### Groq (dostupná bezplatná úroveň!) +### Groq (Free Tier Available!) -1. Zaregistrujte sa: [console.groq.com](https://console.groq.com) -2. Získajte kľúč API (vrátane bezplatnej úrovne) -3. Dashboard → Pridať poskytovateľa → Groq +1. Sign up: [console.groq.com](https://console.groq.com) +2. Get API key (free tier included) +3. Dashboard → Add Provider → Groq -**Modely:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` +**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` -**Tip pre profesionálov:** Ultra rýchle odvodenie – najlepšie pre kódovanie v reálnom čase! +**Pro Tip:** Ultra-fast inference — best for real-time coding! -### OpenRouter (100+ modelov) +### OpenRouter (100+ Models) -1. Zaregistrujte sa: [openrouter.ai](https://openrouter.ai) -2. Získajte kľúč API -3. Dashboard → Pridať poskytovateľa → OpenRouter +1. Sign up: [openrouter.ai](https://openrouter.ai) +2. Get API key +3. Dashboard → Add Provider → OpenRouter -**Modely:** Získajte prístup k viac ako 100 modelom od všetkých hlavných poskytovateľov prostredníctvom jediného kľúča API. +**Models:** Access 100+ models from all major providers through a single API key.
-
💰 Lacní poskytovatelia (záložné)
+💰 Cheap Providers (Backup)
-### GLM-4,7 (denný reset, 0,6 $/1 milión) +### GLM-4.7 (Daily reset, $0.6/1M) -1. Zaregistrujte sa: [Zhipu AI](https://open.bigmodel.cn/) -2. Získajte kľúč API z plánu kódovania -3. Panel → Pridať kľúč API: - – Poskytovateľ: `glm` - - API kľúč: `your-key` +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` -**Použitie:** `glm/glm-4.7` +**Use:** `glm/glm-4.7` -**Tip pre profesionálov:** Kódovací plán ponúka 3× kvótu za 1/7 cenu! Resetovať denne o 10:00. +**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. Zaregistrujte sa: [MiniMax](https://www.minimax.io/) -2. Získajte kľúč API -3. Panel → Pridať kľúč API +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key +3. Dashboard → Add API Key -**Použitie:** `minimax/MiniMax-M2.1` +**Use:** `minimax/MiniMax-M2.1` -**Tip pre profesionálov:** Najlacnejšia možnosť pre dlhý kontext (1 milión tokenov)! +**Pro Tip:** Cheapest option for long context (1M tokens)! -### Kimi K2 (9 USD/mesiac) +### Kimi K2 ($9/month flat) -1. Prihlásiť sa na odber: [Moonshot AI](https://platform.moonshot.ai/) -2. Získajte kľúč API -3. Panel → Pridať kľúč API +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key +3. Dashboard → Add API Key -**Použitie:** `kimi/kimi-latest` +**Use:** `kimi/kimi-latest` -**Tip pre profesionálov:** Pevné 9 $/mesiac za 10 miliónov tokenov = 0,90 $/1 milión efektívnych nákladov! +**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
-
🆓 BEZPLATNÍ poskytovatelia (núdzové zálohovanie)
+🆓 FREE Providers (Emergency Backup)
-### iFlow (8 modelov ZDARMA) +### iFlow (5 FREE models via OAuth) ```bash Dashboard → Connect iFlow @@ -1210,7 +1595,7 @@ Models: if/deepseek-r1 ``` -### Qwen (3 modely ZDARMA) +### Qwen (4 FREE models via Device Code) ```bash Dashboard → Connect Qwen @@ -1237,9 +1622,9 @@ Models:
-
---
-## 🐛 Riešenie problémov
+## Riešenie problémov
Prenumerationskvoten löper ut oanvänd varje månad
-- Hastighetsgränser stoppar dig mellankodning
-- Dyra API:er ($20-50/månad per leverantör)
-- Manuellt byte mellan leverantörer
-
-**OmniRoute löser detta:**
-
-- ✅ **Maximera prenumerationer** - Spåra kvot, använd varje bit innan återställning
-- ✅ **Automatisk reserv** - Prenumeration → API-nyckel → Billigt → Gratis, noll driftstopp
-- ✅ **Multi-konto** - Round-robin mellan konton per leverantör
-- ✅ **Universal** - Fungerar med Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, vilket CLI-verktyg som helst
+- ✅ **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
+- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool
---
## 📧 Support
-> 💬 **Gå med i vår community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Få hjälp, dela tips och håll dig uppdaterad.
+> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.
-- **Webbplats**: [omniroute.online](https://omniroute.online)
+- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Frågor**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Originalprojekt**: [9router by decolua](https://github.com/decolua/9router)
+- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 Hur det fungerar
+## 🔄 How It Works
```
┌─────────────┐
@@ -227,451 +236,453 @@ Result: Never stop coding, minimal cost
---
-## 🎯 Vad OmniRoute löser — 30 verkliga smärtpunkter och användningsfall
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **Varje utvecklare som använder AI-verktyg möter dessa problem dagligen.** OmniRoute byggdes för att lösa dem alla — från kostnadsöverskridanden till regionala block, från trasiga OAuth-flöden till protokolloperationer och observerbarhet i företag.
+> **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.
🎨 Vytvoriť kombá
+🎨 Create Combos
-### Príklad 1: Maximalizujte predplatné → Lacné zálohovanie +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -1253,7 +1638,7 @@ Models: Use in CLI: premium-coding ``` -### Príklad 2: Iba zadarmo (nulové náklady) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -1270,7 +1655,7 @@ Cost: $0 forever!🔧 CLI Integration
-### IDE kurzora +### Cursor IDE ``` Settings → Models → Advanced: @@ -1281,9 +1666,9 @@ Settings → Models → Advanced: ### Claude Code -Na konfiguráciu jedným kliknutím použite stránku **CLI Tools** na informačnom paneli alebo upravte `~/.claude/settings.json` manuálne. +Use the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually. -### Kódex CLI +### Codex CLI ```bash export OPENAI_BASE_URL="http://localhost:20128" @@ -1294,13 +1679,13 @@ codex "your prompt" ### OpenClaw -**Možnosť 1 – Dashboard (odporúčané):** +**Option 1 — Dashboard (recommended):** ``` Dashboard → CLI Tools → OpenClaw → Select Model → Apply ``` -**Možnosť 2 – Manuálne:** Upraviť `~/.openclaw/openclaw.json`: +**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`: ```json { @@ -1316,9 +1701,9 @@ Dashboard → CLI Tools → OpenClaw → Select Model → Apply } ``` -> **Poznámka:** OpenClaw funguje iba s lokálnou OmniRoute. Použite `127.0.0.1` namiesto `localhost`, aby ste sa vyhli problémom s rozlíšením IPv6. +> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues. -### Cline / Pokračovať / RooCode +### Cline / Continue / RooCode ``` Settings → API Configuration: @@ -1328,108 +1713,243 @@ Settings → API Configuration: 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. +
-
-- **Runtime**: Node.js 18–22 LTS (⚠️ Node.js 24+ nie je **podporovaný** — `better-sqlite3` natívne binárne súbory sú nekompatibilné)
- – **Jazyk**: TypeScript 5.9 — **100 % TypeScript** v `src/` a `open-sse/` (v1.0.6)
- – **Framework**: Next.js 16 + React 19 + Tailwind CSS 4
-- **Databáza**: LowDB (JSON) + SQLite (stav domény + protokoly proxy)
-- **Streamovanie**: Server-Sent Events (SSE)
-- **Auth**: OAuth 2.0 (PKCE) + JWT + kľúče API
-- **Testovanie**: Testovací program Node.js (viac ako 368 testov jednotiek)
-- **CI/CD**: Akcie GitHub (automatické zverejňovanie npm + Docker Hub pri vydaní)
-- **Web**: [omniroute.online](https://omniroute.online)
-- **Balík**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
-- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
-- **Odolnosť**: Istič, exponenciálny ústup, stádo proti hromu, spoofing TLS
-
----
-
-## 📖 Dokumentácia
-
-| Dokument | Popis |
-| -------------------------------------------- | -------------------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Poskytovatelia, kombá, integrácia CLI, nasadenie |
-| [API Reference](docs/API_REFERENCE.md) | Všetky koncové body s príkladmi |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Bežné problémy a riešenia |
-| [Architecture](docs/ARCHITECTURE.md) | Architektúra systému a vnútorné vybavenie |
-| [Contributing](CONTRIBUTING.md) | Nastavenie vývoja a usmernenia |
-| [OpenAPI Spec](docs/openapi.yaml) | Špecifikácia OpenAPI 3.0 |
-| [Security Policy](SECURITY.md) | Nahlasovanie zraniteľnosti a bezpečnostné postupy |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Kompletný sprievodca: nastavenie VM + nginx + Cloudflare |
-| [Features Gallery](docs/FEATURES.md) | Vizuálna prehliadka prístrojového panela so snímkami obrazovky |
-
-### 📸 Ukážka hlavného panela
+## 🛠️ Tech Stack
Kliknutím rozbalíte sprievodcu riešením problémov
+Click to expand troubleshooting guide
-**„Jazykový model neposkytol správy“** +**"Language model did not provide messages"** -- Kvóta poskytovateľa je vyčerpaná → Skontrolujte sledovanie kvót na paneli -- Riešenie: Použite záložnú kombináciu alebo prejdite na lacnejšiu úroveň +- Provider quota exhausted → Check dashboard quota tracker +- Solution: Use combo fallback or switch to cheaper tier -**Obmedzenie sadzby** +**Rate limiting** -- Vyčerpaná kvóta predplatného → Návrat na GLM/MiniMax -- Pridať kombináciu: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Subscription quota out → Fallback to GLM/MiniMax +- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -**Platnosť tokenu OAuth vypršala** +**OAuth token expired** -- Automaticky obnovuje OmniRoute -- Ak problémy pretrvávajú: Dashboard → Provider → Reconnect +- Auto-refreshed by OmniRoute +- If issues persist: Dashboard → Provider → Reconnect -**Vysoké náklady** +**High costs** -- Skontrolujte štatistiky používania v hlavnom paneli → Náklady -- Prepnite primárny model na GLM/MiniMax -- Používajte bezplatnú vrstvu (Gemini CLI, iFlow) pre nekritické úlohy +- Check usage stats in Dashboard → Costs +- Switch primary model to GLM/MiniMax +- Use free tier (Gemini CLI, iFlow) for non-critical tasks -**Palubná doska sa otvára na nesprávnom porte** +**Dashboard/API ports are wrong** -- Nastavte `PORT=20128` a `NEXT_PUBLIC_BASE_URL=http://localhost:20128` +- `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) -**Chyby synchronizácie v cloude** +**Cloud sync errors** -- Overte `BASE_URL` body na vašu spustenú inštanciu - – Overte `CLOUD_URL` bodov k očakávanému koncovému bodu cloudu -- Ponechajte hodnoty `NEXT_PUBLIC_*` zarovnané s hodnotami na strane servera +- 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 -**Prvé prihlásenie nefunguje** +**First login not working** -- Skontrolujte `INITIAL_PASSWORD` v `.env` - – Ak nie je nastavené, záložné heslo je `123456` +- Check `INITIAL_PASSWORD` in `.env` +- If unset, fallback password is `123456` -**Žiadne záznamy žiadostí** +**No request logs** -- Nastaviť `ENABLE_REQUEST_LOGS=true` v `.env` +- Set `ENABLE_REQUEST_LOGS=true` in `.env` -**Test pripojenia ukazuje „Neplatné“ pre poskytovateľov kompatibilných s OpenAI** +**Connection test shows "Invalid" for OpenAI-compatible providers** -- Mnohí poskytovatelia nevystavujú koncový bod `/models` -- OmniRoute v1.0.6+ zahŕňa záložné overenie prostredníctvom dokončenia chatu -- Uistite sa, že základná adresa URL obsahuje príponu `/v1` +- 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 +### 🔐 OAuth on a Remote Server + -> **⚠️ DÔLEŽITÉ pre používateľov s OmniRoute a diaľkovým ovládaním VPS/Docker/servidor** +> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server** -### OAuth +#### Why does Antigravity / Gemini CLI OAuth fail on remote servers? -Osvedčuje **Antigravity** a **Gemini CLI** používame **Google OAuth 2.0** ako autentifikáciu. O Google exige que a `redirect_uri` usada no fluxo OAuth saja **exatamente** uma das URI pre-kadastradas no Google Cloud Console to use. +The **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console. -Ako credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para `localhost`**. K dispozícii máte prístup k OmniRoute k vzdialenému servisu (napr.: `https://omniroute.meuservidor.com`), alebo k autenticite spoločnosti Google: +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 ``` -### Riešenie: Konfigurácia proprias poverenia OAuth +#### Solution: Configure your own OAuth credentials -Presný kód je **OAuth 2.0 Client ID** bez služby Google Cloud Console s identifikátorom URI. +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 + +# For Gemini CLI: +GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com +GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +``` + +**6. Restart OmniRoute** + +```bash +# npm: +npm run dev + +# Docker: +docker restart omniroute +``` + +**7. Try connecting again** + +Dashboard → Providers → Antigravity (or Gemini CLI) → OAuth + +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. + +--- + +
+
---
-## 🛠️
+🇧🇷 Versão em Português
+ +#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos? + +Os provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo. + +As credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticação com: + +``` +Error 400: redirect_uri_mismatch +``` + +#### Solução: Configure suas próprias credenciais OAuth + +Você precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor. #### Passo a passo -**1. Prístup k službe Google Cloud Console** +**1. Acesse o Google Cloud Console** Abra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) **2. Crie um novo OAuth 2.0 Client ID** -- Kliknite na **"+ Vytvoriť poverenia"** → **"ID klienta OAuth"** -- Tipo de aplicativo: **"Webová aplikácia"** - – Nome: escolha qualquer nome (napr.: `OmniRoute Remote`) +- Clique em **"+ Create Credentials"** → **"OAuth client ID"** +- Tipo de aplicativo: **"Web application"** +- Nome: escolha qualquer nome (ex: `OmniRoute Remote`) -**3. Adicione ako Authorized Redirect URI** +**3. Adicione as Authorized Redirect URIs** -Žiadne pole **"URI autorizovaného presmerovania"**, adicione: +No campo **"Authorized redirect URIs"**, adicione: ``` https://seu-servidor.com/callback ``` -> Substitua `seu-servidor.com` pelo domínio ou IP do seu servidor (inclua a porta se necessário, napr.: `http://45.33.32.156:20128/callback`). +> Substitua `seu-servidor.com` pelo domínio ou IP do seu servidor (inclua a porta se necessário, ex: `http://45.33.32.156:20128/callback`). -**4. Uložiť a kópiu ako poverenie** +**4. Salve e copie as credenciais** Após criar, o Google mostrará o **Client ID** e o **Client Secret**. -**5. Konfigurovať ako variáveis de ambiente** +**5. Configure as variáveis de ambiente** No seu `.env` (ou nas variáveis de ambiente do Docker): @@ -1444,7 +1964,7 @@ GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret ``` -**6. Reinicie alebo OmniRoute** +**6. Reinicie o OmniRoute** ```bash # Se usando npm: @@ -1456,150 +1976,145 @@ docker restart omniroute **7. Tente conectar novamente** -Dashboard → Poskytovatelia → Antigravitácia (alebo Gemini CLI) → OAuth +Dashboard → Providers → Antigravity (ou Gemini CLI) → OAuth -Agora alebo Google presmerovaný korretamente pre `https://seu-servidor.com/callback` a autentické funkcie. +Agora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará. --- -### Alternatívne dočasné riešenie (sem configurar credenciais próprias) +#### Workaround temporário (sem configurar credenciais próprias) -Ak chcete získať prístup k dôvere, môžete použiť **príručku URL**: +Se não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**: -1. O OmniRoute abrirá a URL autorização Google +1. O OmniRoute abrirá a URL de autorização do Google 2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto) -3. **Skopírujte úplnú webovú adresu** da barra de endereço do seu browser (mesmo que a pagina não carregue) +3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue) 4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute -5. Kliknite na **"Pripojiť"** +5. Clique em **"Connect"** -> Toto riešenie funguje pomocou autorizačného kódu na adrese URL a nezávislého presmerovania. +> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.
-
---
-## 🗺️
+## Dokumentácia
-OmniRoute má naplánovaných **210+ funkcií** vo viacerých fázach vývoja. Tu sú kľúčové oblasti:
-
-| Kategória | Plánované funkcie | Najdôležitejšie |
-| ------------------------------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------- |
-| 🧠 **Routovanie a inteligencia** | 25+ | Smerovanie s najnižšou latenciou, smerovanie založené na značkách, predbežná kontrola kvóty, výber účtu P2C |
-| 🔒 **Bezpečnosť a dodržiavanie predpisov** | 20+ | Spevnenie SSRF, maskovanie poverení, limit rýchlosti na koncový bod, rozsah kľúča riadenia |
-| 📊 **Pozorovateľnosť** | 15+ | Integrácia OpenTelemetry, monitorovanie kvót v reálnom čase, sledovanie nákladov na model |
-| 🔄 **Integrácie poskytovateľov** | 20+ | Register dynamických modelov, cooldowny poskytovateľov, kódex pre viacero účtov, analýza kvót Copilota |
-| ⚡ **Výkon** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API |
-| 🌐 **Ekosystém** | 10+ | WebSocket API, rýchle opätovné načítanie konfigurácie, distribuovaný ukladací priestor konfigurácií, komerčný režim |
-
-### 🔜 Už čoskoro
-
-- 🔗 **Integrácia OpenCode** – podpora natívneho poskytovateľa pre IDE kódovania OpenCode AI
-- 🔗 **Integrácia TRAE** – Úplná podpora vývojového rámca TRAE AI
-- 📦 **Batch API** – Asynchrónne dávkové spracovanie pre hromadné požiadavky
-- 🎯 ** Smerovanie založené na značkách** – Smerujte požiadavky na základe vlastných značiek a metadát
-- 💰 **Stratégia najnižšej ceny** — Automaticky vyberte najlacnejšieho dostupného poskytovateľa
-
-> 📝 Úplné špecifikácie funkcií sú k dispozícii v [link](docs/new-features/) (217 podrobných špecifikácií)
+| Document | Description |
+| ---------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 16 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/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
+| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
-## 👥 Prispievatelia
+## 🗺️ Roadmap
+
+OmniRoute has **210+ 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, P2C account selection |
+| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |
+| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |
+| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider 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
[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
-### Ako prispieť
+### How to Contribute
-1. Fork úložisko
-2. Vytvorte si pobočku funkcií (`git checkout -b feature/amazing-feature`)
-3. Potvrďte zmeny (`git commit -m 'Add amazing feature'`)
-4. Zatlačte na pobočku (`git push origin feature/amazing-feature`)
-5. Otvorte požiadavku na stiahnutie
+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
-Podrobné pokyny nájdete na stránke [CONTRIBUTING.md](CONTRIBUTING.md).
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
-### Vydanie novej verzie
+### Releasing a New Version
```bash
# Create a release — npm publish happens automatically
-gh release create v1.0.6 --title "v1.0.6" --generate-notes
+gh release create v2.0.0 --title "v2.0.0" --generate-notes
```
---
-## 📊 História hviezd
+## 📊 Star History
## Stargazers over time
## [](https://starchart.cc/diegosouzapw/OmniRoute)
-## 🙏 Poďakovanie
+## 🙏 Acknowledgments
-Špeciálne poďakovanie patrí **[9router](https://github.com/decolua/9router)** od **[decolua](https://github.com/decolua)** – pôvodnému projektu, ktorý inšpiroval túto vidličku. OmniRoute stavia na tomto neuveriteľnom základe s ďalšími funkciami, multimodálnymi API a úplným prepísaním TypeScript.
+Special thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.
-Špeciálne poďakovanie patrí **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** – pôvodnej implementácii Go, ktorá inšpirovala tento port JavaScript.
+Special thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.
---
-## 📄 Licencia
+## Licencia
-Licencia MIT – podrobnosti nájdete na stránke [LICENSE](LICENSE).
+MIT License - see [LICENSE](LICENSE) for details.
---
Kliknutím zobrazíte snímky obrazovky hlavného panela
+Click to expand tech stack details
-| Strana | Snímka obrazovky | -| ---------------------- | ------------------------------------------------- | -| **Poskytovatelia** |  | -| **Kombá** |  | -| **Analytika** |  | -| **Zdravie** |  | -| **Prekladateľ** |  | -| **Nastavenia** |  | -| **Nástroje CLI** |  | -| **Denníky používania** |  | -| **Koncový bod** |  | +- **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**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions) +- **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
- Vytvorené pomocou ❤️ pre vývojárov, ktorí kódujú 24/7
+ Built with ❤️ for developers who code 24/7
omniroute.online
+
diff --git a/docs/i18n/sk/docs/FEATURES.md b/docs/i18n/sk/docs/FEATURES.md
new file mode 100644
index 0000000000..1f03969952
--- /dev/null
+++ b/docs/i18n/sk/docs/FEATURES.md
@@ -0,0 +1,145 @@
+# OmniRoute — Dashboard Features Gallery (Slovenčina)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/FEATURES.md) · 🇪🇸 [es](../../es/docs/FEATURES.md) · 🇫🇷 [fr](../../fr/docs/FEATURES.md) · 🇩🇪 [de](../../de/docs/FEATURES.md) · 🇮🇹 [it](../../it/docs/FEATURES.md) · 🇷🇺 [ru](../../ru/docs/FEATURES.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FEATURES.md) · 🇯🇵 [ja](../../ja/docs/FEATURES.md) · 🇰🇷 [ko](../../ko/docs/FEATURES.md) · 🇸🇦 [ar](../../ar/docs/FEATURES.md) · 🇮🇳 [in](../../in/docs/FEATURES.md) · 🇹🇭 [th](../../th/docs/FEATURES.md) · 🇻🇳 [vi](../../vi/docs/FEATURES.md) · 🇮🇩 [id](../../id/docs/FEATURES.md) · 🇲🇾 [ms](../../ms/docs/FEATURES.md) · 🇳🇱 [nl](../../nl/docs/FEATURES.md) · 🇵🇱 [pl](../../pl/docs/FEATURES.md) · 🇸🇪 [sv](../../sv/docs/FEATURES.md) · 🇳🇴 [no](../../no/docs/FEATURES.md) · 🇩🇰 [da](../../da/docs/FEATURES.md) · 🇫🇮 [fi](../../fi/docs/FEATURES.md) · 🇵🇹 [pt](../../pt/docs/FEATURES.md) · 🇷🇴 [ro](../../ro/docs/FEATURES.md) · 🇭🇺 [hu](../../hu/docs/FEATURES.md) · 🇧🇬 [bg](../../bg/docs/FEATURES.md) · 🇸🇰 [sk](../../sk/docs/FEATURES.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FEATURES.md) · 🇮🇱 [he](../../he/docs/FEATURES.md) · 🇵🇭 [phi](../../phi/docs/FEATURES.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FEATURES.md)
+
+---
+
+Visual guide to every section of the OmniRoute dashboard.
+
+---
+
+## 🔌 Providers
+
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
+
+
+
+---
+
+## 🎨 Combos
+
+Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
+
+
+
+---
+
+## 📊 Analytics
+
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
+
+
+
+---
+
+## 🏥 System Health
+
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+
+
+
+---
+
+## 🔧 Translator Playground
+
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
+
+
+
+---
+
+## 🎮 Model Playground _(v2.0.9+)_
+
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
+
+---
+
+## 🎨 Themes _(v2.0.5+)_
+
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
+
+## ⚙️ Settings
+
+Comprehensive settings panel with tabs:
+
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning
+- **Advanced** — Configuration overrides
+
+
+
+---
+
+## 🔧 CLI Tools
+
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
+
+
+
+---
+
+## 🤖 CLI Agents _(v2.0.11+)_
+
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
+
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
+
+---
+
+## 🖼️ Media _(v2.0.3+)_
+
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
+
+## 📝 Request Logs
+
+Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
+
+
+
+---
+
+## 🌐 API Endpoint
+
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
+
+
+
+---
+
+## 🔑 API Key Management
+
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
+
+---
+
+## 📋 Audit Log
+
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
+
+---
+
+## 🖥️ Desktop Application
+
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
+
+Key features:
+
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
+
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.
diff --git a/docs/i18n/sv/README.md b/docs/i18n/sv/README.md
index 59341232fd..e623ed0597 100644
--- a/docs/i18n/sv/README.md
+++ b/docs/i18n/sv/README.md
@@ -1,24 +1,94 @@
-omniroute.online
-
-
- # 🚀 OmniRoute — Den kostnadsfria AI-gatewayen
+# 🚀 OmniRoute — The Free AI Gateway (Svenska)
-### Sluta aldrig koda. Smart routing till **GRATIS & lågkostnads AI-modeller** med automatisk reserv.
-
-_Din universella API-proxy — en slutpunkt, 36+ leverantörer, noll driftstopp._
-
-**Slutförda chatt • Inbäddningar • Bildgenerering • Ljud • Omrankning • 100 % TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Gratis AI-leverantör för dina favoritkodningsagenter
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Anslut alla AI-drivna IDE- eller CLI-verktyg via OmniRoute — gratis API-gateway för obegränsad kodning._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+` tags no longer leak to clients in SSE streaming responses (#585) |
+| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with per-provider/account quota enforcement, idempotency, SHA-256 storage, and optional GitHub issue reporting |
+| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG → generic fallback chain |
+| 🔄 **Model Auto-Sync** | 24h scheduler and manual UI toggle to sync model lists for built-in and custom OpenAI-compatible providers |
+| 🌐 **OpenCode Zen/Go** | Two new providers from @kang-heewon via PR #530: free tier + subscription tier via `OpencodeExecutor` |
+| 🐛 **Gemini CLI OAuth** | Actionable error when `GEMINI_OAUTH_CLIENT_SECRET` is missing in Docker (was cryptic Google error) |
+| 🐛 **OpenCode config** | `saveOpenCodeConfig()` now correctly writes TOML to `XDG_CONFIG_HOME` |
+| 🐛 **Pinned model override** | `body.model` correctly set to `pinnedModel` on context-cache protection |
+| 🐛 **Codex/Claude loop** | `tool_result` blocks now converted to text to stop infinite loops |
+| 🐛 **Login redirect** | Login no longer freezes after skipping password setup |
+| 🐛 **Windows paths** | MSYS2/Git-Bash paths (`/c/...`) normalized to `C:\...` automatically |
+
+---
+
+## 🖼️ Main Dashboard
+
+
-📡 Alla agenter ansluter via ` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**Stop wasting money and hitting limits:**
-### 🆕 What's New in v3.0.0
+- Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**OmniRoute solves this:**
----
-
-[](https://www.npmjs.com/package/omniroute)
-[](https://hub.docker.com/r/diegosouzapw/omniroute)
-[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
-[](https://omniroute.online)
-[](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)
-
-🌐 **Available in:** 🇺🇸 [English](../../README.md) | 🇧🇷 [Português (Brasil)](../pt-BR/README.md) | 🇪🇸 [Español](../es/README.md) | 🇫🇷 [Français](../fr/README.md) | 🇮🇹 [Italiano](../it/README.md) | 🇷🇺 [Русский](../ru/README.md) | 🇨🇳 [中文 (简体)](../zh-CN/README.md) | 🇩🇪 [Deutsch](../de/README.md) | 🇮🇳 [हिन्दी](../in/README.md) | 🇹🇭 [ไทย](../th/README.md) | 🇺🇦 [Українська](../uk-UA/README.md) | 🇸🇦 [العربية](../ar/README.md) | 🇯🇵 [日本語](../ja/README.md) | 🇻🇳 [Tiếng Việt](../vi/README.md) | 🇧🇬 [Български](../bg/README.md) | 🇩🇰 [Dansk](../da/README.md) | 🇫🇮 [Suomi](../fi/README.md) | 🇮🇱 [עברית](../he/README.md) | 🇭🇺 [Magyar](../hu/README.md) | 🇮🇩 [Bahasa Indonesia](../id/README.md) | 🇰🇷 [한국어](../ko/README.md) | 🇲🇾 [Bahasa Melayu](../ms/README.md) | 🇳🇱 [Nederlands](../nl/README.md) | 🇳🇴 [Norsk](../no/README.md) | 🇵🇹 [Português (Portugal)](../pt/README.md) | 🇷🇴 [Română](../ro/README.md) | 🇵🇱 [Polski](../pl/README.md) | 🇸🇰 [Slovenčina](../sk/README.md) | 🇸🇪 [Svenska](../sv/README.md) | 🇵🇭 [Filipino](../phi/README.md)
-
-
-
----
-
-## 🖼️
-
-
-
- # 🚀 OmniRoute — Den kostnadsfria AI-gatewayen
+# 🚀 OmniRoute — The Free AI Gateway (Svenska)
-### Sluta aldrig koda. Smart routing till **GRATIS & lågkostnads AI-modeller** med automatisk reserv.
-
-_Din universella API-proxy — en slutpunkt, 36+ leverantörer, noll driftstopp._
-
-**Slutförda chatt • Inbäddningar • Bildgenerering • Ljud • Omrankning • 100 % TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Gratis AI-leverantör för dina favoritkodningsagenter
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Anslut alla AI-drivna IDE- eller CLI-verktyg via OmniRoute — gratis API-gateway för obegränsad kodning._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+
+
+[](https://www.npmjs.com/package/omniroute)
+[](https://www.npmjs.com/package/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
+[](https://omniroute.online)
+[](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)
+
+
+
+🌐 **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)
+
+---
+
+## 🆕 What's New in v3.0.0
+
+> **Upgrading from v2.9.5?** — See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes.
+
+| Area | Change |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection remediation |
+| ✅ **Route Validation** | All 176 API routes now validated with Zod schemas + `validateBody()` — CI `check:route-validation:t06` passes |
+| 🐛 **omniModel Tag Leak** | Internal `
+
+
+
+---
+
+## 📸 Dashboard Preview
+
+
+
+
+
+---
+
+### 🤖 Free AI Provider for your favorite coding agents
+
+_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._
Click to see dashboard screenshots
+ +| Page | Screenshot | +| -------------- | ------------------------------------------------- | +| **Providers** |  | +| **Combos** |  | +| **Analytics** |  | +| **Health** |  | +| **Translator** |  | +| **Settings** |  | +| **CLI Tools** |  | +| **Usage Logs** |  | +| **Endpoints** |  | + +|
-
+
OpenClaw @@ -92,113 +162,52 @@ _Anslut alla AI-drivna IDE- eller CLI-verktyg via OmniRoute — gratis API-gatew |
http://localhost:20128/v1 eller http://cloud.omniroute.online/v1, —limited one config_245\_\_ kvot
+📡 All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 — one config, unlimited models and quota
---
-### 🆕 What's New in v3.0.0
+## 🤔 Why OmniRoute?
-| Area | Change |
-| ------------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal ` Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `
-
-
-
----
-
-## 📸
-
-
-
-
-
----
-
-## 🤔 Varför OmniRoute?
-
-**Sluta slösa pengar och nå gränser:**
-
-- ...
- -| # | # | -| ----- | ---------------------------------------- | -| **1** |  | -| **2** |  | -| **3** |  | -| **4** |  | -| **5** |  | -| **6** |  | -| **7** |  | -| **8** |  | -| **9** |  | - - Prenumerationskvoten löper ut oanvänd varje månad
-- Hastighetsgränser stoppar dig mellankodning
-- Dyra API:er ($20-50/månad per leverantör)
-- Manuellt byte mellan leverantörer
-
-**OmniRoute löser detta:**
-
-- ✅ **Maximera prenumerationer** - Spåra kvot, använd varje bit innan återställning
-- ✅ **Automatisk reserv** - Prenumeration → API-nyckel → Billigt → Gratis, noll driftstopp
-- ✅ **Multi-konto** - Round-robin mellan konton per leverantör
-- ✅ **Universal** - Fungerar med Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, vilket CLI-verktyg som helst
+- ✅ **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
+- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool
---
## 📧 Support
-> 💬 **Gå med i vår community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Få hjälp, dela tips och håll dig uppdaterad.
+> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.
-- **Webbplats**: [omniroute.online](https://omniroute.online)
+- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Frågor**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Originalprojekt**: [9router by decolua](https://github.com/decolua/9router)
+- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 Hur det fungerar
+## 🔄 How It Works
```
┌─────────────┐
@@ -227,451 +236,453 @@ Result: Never stop coding, minimal cost
---
-## 🎯 Vad OmniRoute löser — 30 verkliga smärtpunkter och användningsfall
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **Varje utvecklare som använder AI-verktyg möter dessa problem dagligen.** OmniRoute byggdes för att lösa dem alla — från kostnadsöverskridanden till regionala block, från trasiga OAuth-flöden till protokolloperationer och observerbarhet i företag.
+> **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.
-
💸 1. "Jag betalar för ett dyrt abonnemang men blir ändå avbruten av limits"
+💸 1. "I pay for an expensive subscription but still get interrupted by limits"
-Utvecklare betalar $20–200/månad för Claude Pro, Codex Pro eller GitHub Copilot. Även om du betalar har kvoten ett tak - 5 timmars användning, veckogränser eller gränser per minut. Mid-coding session, leverantören slutar svara och utvecklaren tappar flöde och produktivitet. +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. -**Hur OmniRoute löser det:** +**How OmniRoute solves it:** -- **Smart 4-lagers fallback** — Om prenumerationskvoten tar slut, omdirigeras automatiskt till API-nyckel → Billigt → Gratis med noll manuellt ingrepp -- **Kvotspårning i realtid** — Visar tokenförbrukning i realtid med återställningsnedräkning (5 timmar, dagligen, veckovis) -- **Multi-Account Support** — Flera konton per leverantör med automatisk round-robin — när ett tar slut, byter du till nästa -- **Anpassade kombinationer** — Anpassningsbara reservkedjor med 6 balanseringsstrategier (fill-first, round-robin, P2C, slumpmässig, minst använda, kostnadsoptimerad) -- **Codex Business Quotas** — Övervakning av företags-/teamarbetsutrymmeskvoter direkt i instrumentpanelen +- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention +- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly) +- **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 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
-`-block från modeller som DeepSeek R1 till standardiserade `reasoning_content`
-- **Structured Output for Gemini** — `json_schema` → `responseMimeType`/`responseSchema` automatisk konvertering
-- **`stream` är standard till `false`** — Justerar med OpenAI-specifikationen, undviker oväntad SSE i Python/Rust/Go SDK:er
+- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 67+ 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
🔌 2. "Jag måste använda flera leverantörer men alla har olika API"
+🔌 2. "I need to use multiple providers but each has a different API"
-OpenAI använder ett format, Claude (Anthropic) använder ett annat, Gemini ännu ett annat. Om en utvecklare vill testa modeller från olika leverantörer eller fallback mellan dem måste de konfigurera om SDK:er, ändra slutpunkter, hantera inkompatibla format. Anpassade leverantörer (FriendLI, NIM) har icke-standardiserade modellslutpunkter. +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. -**Hur OmniRoute löser det:** +**How OmniRoute solves it:** -- **Unified Endpoint** — En enda `http://localhost:20128/v1` fungerar som proxy för alla 36+ leverantörer -- **Formatöversättning** — Automatisk och transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API -- **Responssanering** — Tar bort icke-standardiserade fält (`x_groq`, `usage_breakdown`, `service_tier`) som bryter OpenAI SDK v1.83+ -- **Rollnormalisering** — Konverterar `developer` → `system` för icke-OpenAI-leverantörer; `system` → `user` för GLM/ERNIE -- **Think Tag Extraction** — Extraherar `
-
🌐 3. "Min AI-leverantör blockerar min region/land"
+🌐 3. "My AI provider blocks my region/country"
-Leverantörer som OpenAI/Codex blockerar åtkomst från vissa geografiska regioner. Användare får fel som `unsupported_country_region_territory` under OAuth- och API-anslutningar. Detta är särskilt frustrerande för utvecklare från utvecklingsländer. +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. -**Hur OmniRoute löser det:** +**How OmniRoute solves it:** -- **3-Level Proxy Config** — Konfigurerbar proxy på 3 nivåer: global (all trafik), per leverantör (endast en leverantör) och per anslutning/nyckel -- **Färgkodade proxymärken** — Visuella indikatorer: 🟢 global proxy, 🟡 leverantörsproxy, 🔵 anslutningsproxy, visar alltid IP:n -- **OAuth Token Exchange Through Proxy** — OAuth-flödet går också genom proxyn, vilket löser `unsupported_country_region_territory` -- **Anslutningstester via proxy** — Anslutningstester använder den konfigurerade proxyn (ingen mer direkt förbikoppling) -- **SOCKS5-stöd** — Fullständigt SOCKS5-proxystöd för utgående routing -- **TLS Fingerprint Spoofing** — Webbläsarliknande TLS-fingeravtryck via `wreq-js` för att kringgå botdetektering +- **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
-` prefix
-- **Free-Only Combos** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/månad utan stilleståndstid
-- **NVIDIA NIM gratis krediter** — 1000 gratis krediter integrerade
-- **Kostnadsoptimerad strategi** — Routingstrategi som automatiskt väljer den billigaste tillgängliga leverantören
+- **Free-Only Combos** — Chain `gc/gemini-3-flash → 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
🆓 4. "Jag vill använda AI för kodning men jag har inga pengar"
+🆓 4. "I want to use AI for coding but I have no money"
-Alla kan inte betala $20–200/månad för AI-prenumerationer. Studenter, utvecklare från tillväxtländer, hobbyister och frilansare behöver tillgång till kvalitetsmodeller utan kostnad. +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. -**Hur OmniRoute löser det:** +**How OmniRoute solves it:** -- **Gratis leverantörer inbyggda** — Inbyggt stöd för 100 % gratis leverantörer: iFlow (8 obegränsade modeller), Qwen (3 obegränsade modeller), Kiro (Claude gratis), Gemini CLI (180K/månad gratis) +- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free) - **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/
-
🔒 5. "Jag behöver skydda min AI-gateway från obehörig åtkomst"
+🔒 5. "I need to protect my AI gateway from unauthorized access"
-När du exponerar en AI-gateway för nätverket (LAN, VPS, Docker) kan vem som helst med adressen konsumera utvecklarens tokens/kvot. Utan skydd är API:er sårbara för missbruk, snabb injektion och missbruk. +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. -**Hur OmniRoute löser det:** +**How OmniRoute solves it:** -- **API Key Management** — Generering, rotation och omfattning per leverantör med en dedikerad `/dashboard/api-manager`-sida -- **Behörigheter på modellnivå** — Begränsa API-nycklar till specifika modeller (`openai/*`, jokerteckenmönster), med växlaren Tillåt allt/Begränsa -- **API Endpoint Protection** — Kräv en nyckel för `/v1/models` och blockera specifika leverantörer från listan -- **Auth Guard + CSRF Protection** — Alla instrumentpanelsrutter skyddade med `withAuth` middleware + CSRF-tokens -- **Rate Limiter** — Per-IP-hastighetsbegränsning med konfigurerbara fönster -- **IP-filtrering** — Tillåtelselista/blockeringslista för åtkomstkontroll -- **Prompt Injection Guard** — Sanering mot skadliga promptmönster -- **AES-256-GCM-kryptering** — Autentiseringsuppgifter krypterade i vila +- **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. "Min leverantör gick ner och jag tappade mitt kodningsflöde"
+🛑 6. "My provider went down and I lost my coding flow"
-AI-leverantörer kan bli instabila, returnera 5xx-fel eller nå tillfälliga hastighetsgränser. Om en utvecklare är beroende av en enskild leverantör avbryts de. Utan strömbrytare kan upprepade försök krascha programmet. +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. -**Hur OmniRoute löser det:** +**How OmniRoute solves it:** -- **Circuit Breaker per leverantör** — Autoöppning/stängning med konfigurerbara trösklar och nedkylning (stängd/öppen/halvöppen) -- **Exponentiell backoff** — Progressiva fördröjningar igen -- **Anti-Thundering Herd** — Mutex + semaforskydd mot samtidiga stormar igen -- **Combo reservkedjor** — Om den primära leverantören misslyckas, faller den automatiskt genom kedjan utan ingrepp -- **Combo Circuit Breaker** - Inaktiverar automatiskt felande leverantörer inom en kombinationskedja -- **Health Dashboard** — Drifttidsövervakning, strömbrytartillstånd, låsningar, cachestatistik, p50/p95/p99 latens +- **Circuit Breaker per-model** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks +- **Exponential Backoff** — Progressive retry delays +- **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 +- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain +- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
-
🔧 7. "Att konfigurera varje AI-verktyg är tråkigt och repetitivt"
+🔧 7. "Configuring each AI tool is tedious and repetitive"
-Utvecklare använder Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Varje verktyg behöver en annan konfiguration (API-slutpunkt, nyckel, modell). Att konfigurera om när man byter leverantör eller modell är ett slöseri med tid. +Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time. -**Hur OmniRoute löser det:** +**How OmniRoute solves it:** -- **CLI Tools Dashboard** — Dedikerad sida med ett-klicksinställningar för Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline -- **GitHub Copilot Config Generator** — Genererar `chatLanguageModels.json` för VS-kod med bulkmodellval -- **Onboarding Wizard** — Guidad 4-stegs installation för förstagångsanvändare -- **En slutpunkt, alla modeller** — Konfigurera `http://localhost:20128/v1` en gång, få tillgång till 36+ leverantörer +- **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 67+ providers
-
🔑 8. "Hantera OAuth-tokens från flera leverantörer är ett helvete"
+🔑 8. "Managing OAuth tokens from multiple providers is hell"
-Claude Code, Codex, Gemini CLI, Copilot — alla använder OAuth 2.0 med utgående tokens. Utvecklare måste autentisera på nytt hela tiden, hantera `client_secret is missing`, `redirect_uri_mismatch` och fel på fjärrservrar. OAuth på LAN/VPS är särskilt problematiskt. +Claude Code, Codex, Gemini CLI, 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. -**Hur OmniRoute löser det:** +**How OmniRoute solves it:** -- **Automatisk uppdatering av token** — OAuth-tokens uppdateras i bakgrunden innan de löper ut -- **OAuth 2.0 (PKCE) Inbyggd** — Automatiskt flöde för Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow -- **Multi-Account OAuth** — Flera konton per leverantör via JWT/ID-tokenextraktion -- **OAuth LAN/Remote Fix** — Privat IP-detektering för `redirect_uri` + manuellt URL-läge för fjärrservrar -- **OAuth Behind Nginx** — Använder `window.location.origin` för omvänd proxykompatibilitet -- **Remote OAuth Guide** — Steg-för-steg-guide för Google Cloud-uppgifter på VPS/Docker +- **Auto Token Refresh** — OAuth tokens refresh in background before expiration +- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow +- **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. "Jag vet inte hur mycket jag spenderar eller var"
+📊 9. "I don't know how much I'm spending or where"
-Utvecklare använder flera betalleverantörer men har ingen enhetlig syn på utgifter. Varje leverantör har sin egen faktureringspanel, men det finns ingen konsoliderad vy. Oväntade kostnader kan hopa sig. +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. -**Hur OmniRoute löser det:** +**How OmniRoute solves it:** -- **Kostnadsanalysinstrumentpanel** — Kostnadsspårning per token och budgethantering per leverantör -- **Budgetgränser per nivå** — Utgiftstak per nivå som utlöser automatisk reserv -- **Priskonfiguration per modell** — Konfigurerbara priser per modell -- **Användningsstatistik per API-nyckel** — Antal förfrågningar och senast använda tidsstämpel per nyckel -- **Analytics Dashboard** — Statistikkort, modellanvändningsdiagram, leverantörstabell med framgångsfrekvens och latens +- **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. "Jag kan inte diagnostisera fel och problem i AI-samtal"
+🐛 10. "I can't diagnose errors and problems in AI calls"
-När ett samtal misslyckas vet inte utvecklaren om det var en hastighetsgräns, utgången token, fel format eller leverantörsfel. Fragmenterade loggar över olika terminaler. Utan observerbarhet är felsökning att trial-and-error. +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. -**Hur OmniRoute löser det:** +**How OmniRoute solves it:** -- **Unified Logs Dashboard** — 4 flikar: Request Logs, Proxy Logs, Audit Logs, Console -- **Console Log Viewer** — Viewer i realtid i terminalstil med färgkodade nivåer, automatisk rullning, sökning, filtrering -- **SQLite Proxy-loggar** — Beständiga loggar som överlever serverstarter -- **Translator Playground** — 4 felsökningslägen: Playground (formatöversättning), Chat Tester (tur och retur), Testbänk (batch), Live Monitor (realtid) -- **Request Telemetri** — p50/p95/p99 latens + X-Request-Id-spårning -- **Filbaserad loggning med rotation** — Konsolinterceptor fångar allt till JSON-logg med storleksbaserad rotation +- **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 Proxy Logs** — Persistent logs that survive server restarts +- **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 Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation +- **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. "Det är komplext att distribuera och underhålla gatewayen"
+🏗️ 11. "Deploying and maintaining the gateway is complex"
-Att installera, konfigurera och underhålla en AI-proxy i olika miljöer (lokalt, VPS, Docker, moln) är arbetskrävande. Problem som hårdkodade sökvägar, `EACCES` på kataloger, portkonflikter och plattformsoberoende konstruktioner ger friktion. +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. -**Hur OmniRoute löser det:** +**How OmniRoute solves it:** -- **npm global installation** — `npm install -g omniroute && omniroute` — klar -- **Docker Multi-Platform** — AMD64 + ARM64 inbyggt (Apple Silicon, AWS Graviton, Raspberry Pi) -- **Docker Compose Profiles** — `base` (inga CLI-verktyg) och `cli` (med Claude Code, Codex, OpenClaw) -- **Electron Desktop App** — Inbyggd app för Windows/macOS/Linux med systemfältet, autostart, offlineläge -- **Split-Port Mode** — API och Dashboard på separata portar för avancerade scenarier (omvänd proxy, containernätverk) -- **Cloud Sync** — Konfigurera synkronisering mellan enheter via Cloudflare Workers -- **DB-säkerhetskopior** — Automatisk säkerhetskopiering, återställning, export och import av alla inställningar +- **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
-
🌍 12. "Gränssnittet är endast engelska och mitt team talar inte engelska"
+🌍 12. "The interface is English-only and my team doesn't speak English"
-Lag i icke-engelsktalande länder, särskilt i Latinamerika, Asien och Europa, kämpar med enbart engelska gränssnitt. Språkbarriärer minskar användningen och ökar konfigurationsfelen. +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. -**Hur OmniRoute löser det:** +**How OmniRoute solves it:** -- **Dashboard i18n — 30 språk** — Alla 500+ nycklar översatta, inklusive arabiska, bulgariska, danska, tyska, spanska, finska, franska, hebreiska, hindi, ungerska, indonesiska, italienska, japanska, koreanska, malaysiska, holländska, norska, polska, portugisiska (PT/BR), rumänska, ryska, thailändska, ukrainska, ukrainska, kinesiska, engelska, ukrainska, vietnamesiska, ukrainska, svenska, ukrainska -- **RTL-stöd** — Höger-till-vänster-stöd för arabiska och hebreiska -- **Multi-Language READMEs** — 30 fullständiga dokumentationsöversättningar -- **Språkväljare** — Globikon i rubriken för växling i realtid +- **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. "Jag behöver mer än chatt — jag behöver inbäddningar, bilder, ljud"
+🔄 13. "I need more than chat — I need embeddings, images, audio"
-AI är inte bara att slutföra chatt. Utvecklare måste generera bilder, transkribera ljud, skapa inbäddningar för RAG, ranka om dokument och moderera innehåll. Varje API har olika slutpunkt och format. +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. -**Hur OmniRoute löser det:** +**How OmniRoute solves it:** -- **Inbäddningar** — `/v1/embeddings` med 6 leverantörer och 9+ modeller -- **Bildgenerering** — `/v1/images/generations` med 10 leverantörer och 20+ modeller (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI) -- **Text-till-video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) och SD WebUI +- **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) -- **Ljudtranskription** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3 -- **Text-till-tal** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, Inworld, Cartesia, PlayHT, + befintliga leverantörer -- **Moderationer** — `/v1/moderations` — Innehållssäkerhetskontroller -- **Omrankning** — `/v1/rerank` — Omrankning av dokumentrelevans -- **Responses API** — Fullständigt `/v1/responses`-stöd för Codex +- **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. "Jag har inget sätt att testa och jämföra kvalitet mellan olika modeller"
+🧪 14. "I have no way to test and compare quality across models"
-Utvecklare vill veta vilken modell som är bäst för deras användningsfall - kod, översättning, resonemang - men det går långsamt att jämföra manuellt. Det finns inga integrerade utvärderingsverktyg. +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. -**Hur OmniRoute löser det:** +**How OmniRoute solves it:** -- **LLM-utvärderingar** — Golden set-testning med 10 förinstallerade fall som täcker hälsningar, matematik, geografi, kodgenerering, JSON-efterlevnad, översättning, markdown, säkerhetsvägran -- **4 matchningsstrategier** — `exact`, `contains`, `regex`, `custom` (JS-funktion) -- **Translator Playground Test Bench** — Batchtestning med flera ingångar och förväntade utgångar, jämförelse mellan olika leverantörer -- **Chatttestare** — Fullständig tur och retur med visuell responsåtergivning -- **Live Monitor** — Realtidsström av alla förfrågningar som flödar genom proxyn +- **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. "Jag behöver skala utan att förlora prestanda"
+📈 15. "I need to scale without losing performance"
-När förfrågningsvolymen ökar, utan att cachelagra genererar samma frågor dubbla kostnader. Utan idempotens, dubbletter begär avfallshantering. Prisgränser per leverantör måste respekteras. +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. -**Hur OmniRoute löser det:** +**How OmniRoute solves it:** -- **Semantisk cache** — Tvåskiktscache (signatur + semantisk) minskar kostnaden och fördröjningen -- **Request Idempotency** — 5s dedupliceringsfönster för identiska förfrågningar -- **Rate Limit Detection** — RPM per leverantör, min gap och max samtidig spårning -- **Redigerbara hastighetsgränser** — Konfigurerbara standardinställningar i Inställningar → Motståndskraft med uthållighet -- **API Key Validation Cache** — 3-lagers cache för produktionsprestanda -- **Hälsoinstrumentpanel med telemetri** — p50/p95/p99 latens, cachestatistik, drifttid +- **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 +- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence +- **API Key Validation Cache** — 3-tier cache for production performance +- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
-
🤖 16. "Jag vill kontrollera modellens beteende globalt"
+🤖 16. "I want to control model behavior globally"
-Utvecklare som vill ha alla svar på ett specifikt språk, med en specifik ton, eller som vill begränsa resonemangstokens. Att konfigurera detta i varje verktyg/förfrågan är opraktiskt. +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. -**Hur OmniRoute löser det:** +**How OmniRoute solves it:** -- **System Prompt Injection** — Global prompt tillämpas på alla förfrågningar +- **System Prompt Injection** — Global prompt applied to all requests - **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive) -- **6 routingstrategier** — Globala strategier som avgör hur förfrågningar distribueras -- **Wildcard Router** — `provider/*`-mönster dirigerar dynamiskt till vilken leverantör som helst -- **Kombo Aktivera/Inaktivera Växla** — Växla kombinationer direkt från instrumentpanelen -- **Visa leverantör** — Aktivera/inaktivera alla anslutningar för en leverantör med ett klick -- **Blockerade leverantörer** — Uteslut specifika leverantörer från `/v1/models`-listan +- **6 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 +- **Provider Toggle** — Enable/disable all connections for a provider with one click +- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
-
🧰 17. "Jag behöver MCP-verktyg som förstklassiga produktegenskaper"
+🧰 17. "I need MCP tools as first-class product capabilities"
-Många AI-gateways exponerar MCP endast som en dold implementeringsdetalj. Team behöver ett synligt, hanterbart driftlager. +Many AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer. -**Hur OmniRoute löser det:** +**How OmniRoute solves it:** -- MCP visas på navigeringspanelen och fliken för slutpunktsprotokoll -- Dedikerad MCP-hanteringssida med process, verktyg, omfattningar och revision -- Inbyggd snabbstart för `omniroute --mcp` och klientintroduktion +- 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. "Jag behöver A2A-orkestrering med synkronisering + strömningsuppgiftsvägar"
+🧠 18. "I need A2A orchestration with sync + stream task paths"
-Agentarbetsflöden kräver både direkta svar och långvarig streamad exekvering med livscykelkontroll. +Agent workflows need both direct replies and long-running streamed execution with lifecycle control. -**Hur OmniRoute löser det:** +**How OmniRoute solves it:** -- A2A JSON-RPC-ändpunkt (`POST /a2a`) med `message/send` och `message/stream` -- SSE-strömning med terminaltillståndspridning -- Task lifecycle API:er för `tasks/get` och `tasks/cancel` +- 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. "Jag behöver riktig MCP-processhälsa, inte gissad status"
+🛰️ 19. "I need real MCP process health, not guessed status"
-Operativa team måste veta om MCP faktiskt lever, inte bara om ett API är tillgängligt. +Operational teams need to know if MCP is actually alive, not just whether an API is reachable. -**Hur OmniRoute löser det:** +**How OmniRoute solves it:** -- Runtime heartbeat-fil med PID, tidsstämplar, transport, verktygsräkning och scope-läge -- MCP status API som kombinerar hjärtslag + senaste aktivitet -- UI-statuskort för process/upptid/hjärtslagsnyhet +- 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. "Jag behöver revisionsbart MCP-verktygsexekvering"
+📋 20. "I need auditable MCP tool execution"
-När verktyg muterar konfiguration eller utlöser operationsåtgärder behöver team rättsmedicinsk spårbarhet. +When tools mutate config or trigger ops actions, teams need forensic traceability. -**Hur OmniRoute löser det:** +**How OmniRoute solves it:** -- SQLite-stödd revisionsloggning för MCP-verktygsanrop -- Filtrerar efter verktyg, framgång/misslyckande, API-nyckel och paginering -- Dashboard revisionstabell + statistikslutpunkter för automatisering +- 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. "Jag behöver scoped MCP-behörigheter per integration"
+🔐 21. "I need scoped MCP permissions per integration"
-Olika klienter bör ha minst privilegierad åtkomst till verktygskategorier. +Different clients should have least-privilege access to tool categories. -**Hur OmniRoute löser det:** +**How OmniRoute solves it:** -- 9 granulära MCP-scopes för kontrollerad verktygsåtkomst -- Tillämpning av omfattning och synlighet i MCP-hanteringsgränssnitt -- Säker standardställning för operativa verktyg +- 9 granular MCP scopes for controlled tool access +- Scope enforcement and visibility in MCP management UI +- Safe default posture for operational tooling
-
⚙️ 22. "Jag behöver driftskontroller utan att omdistribuera"
+⚙️ 22. "I need operational controls without redeploying"
-Team behöver snabba körtidsförändringar under incidenter eller kostnadshändelser. +Teams need quick runtime changes during incidents or cost events. -**Hur OmniRoute löser det:** +**How OmniRoute solves it:** -- Växla kombinationsaktivering direkt från MCP-instrumentpanelen -- Tillämpa motståndskraftsprofiler från fördefinierade policypaket -- Återställ strömbrytarens tillstånd från samma manöverpanel +- Switch combo activation directly from MCP dashboard +- Apply resilience profiles from pre-defined policy packs +- Reset circuit breaker state from the same operations panel
-
🔄 23. "I need live A2A task lifecycle synibility and cancellation"
+🔄 23. "I need live A2A task lifecycle visibility and cancellation"
-Utan livscykelsynlighet blir uppgiftsincidenter svåra att triage. +Without lifecycle visibility, task incidents become hard to triage. -**Hur OmniRoute löser det:** +**How OmniRoute solves it:** -- Uppgiftslista/filtrering efter stat/färdighet med sidnumrering -- Drill down på uppgiftens metadata, händelser och artefakter -- Slutpunkt för annullering av uppgifter och gränssnittsåtgärd med bekräftelse +- 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. "Jag behöver mätvärden för aktiv strömning för A2A-laddning"
+🌊 24. "I need active stream metrics for A2A load"
-Strömmande arbetsflöden kräver operativ insikt i samtidighet och direktanslutningar. +Streaming workflows require operational insight into concurrency and live connections. -**Hur OmniRoute löser det:** +**How OmniRoute solves it:** -- Aktiva strömräknare integrerade i A2A-status -- Tidsstämpel för senaste uppgift och antal per stat -- A2A instrumentpanelskort för operationsövervakning i realtid +- Active stream counters integrated into A2A status +- Last task timestamp and per-state counts +- A2A dashboard cards for real-time ops monitoring
-
🪪 25. "Jag behöver standardagentupptäckt för klienter"
+🪪 25. "I need standard agent discovery for clients"
-Externa klienter och orkestratorer behöver maskinläsbar metadata för onboarding. +External clients and orchestrators need machine-readable metadata for onboarding. -**Hur OmniRoute löser det:** +**How OmniRoute solves it:** -- Agentkort exponerat på `/.well-known/agent.json` -- Förmåga och färdigheter som visas i ledningsgränssnittet -- A2A status API inkluderar upptäcktsmetadata för automatisering +- Agent Card exposed at `/.well-known/agent.json` +- Capabilities and skills shown in management UI +- A2A status API includes discovery metadata for automation
-
🧭 26. "Jag behöver protokollupptäckbarhet i produktens UX"
+🧭 26. "I need protocol discoverability in the product UX"
-Om användare inte kan upptäcka protokollytor, sjunker kvaliteten på adoption och support. +If users cannot discover protocol surfaces, adoption and support quality drop. -**Hur OmniRoute löser det:** +**How OmniRoute solves it:** -- Sidofältsposter för MCP och A2A -- Slutpunktssida Protokoll-fliken med snabbstart och status -- Länkar från översikt till dedikerade hanteringspaneler +- 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. "Jag behöver end-to-end protokollvalidering med riktiga klienter"
+🧪 27. "I need end-to-end protocol validation with real clients"
-Mock-tester räcker inte för att validera protokollkompatibilitet före release. +Mock tests are not enough to validate protocol compatibility before release. -**Hur OmniRoute löser det:** +**How OmniRoute solves it:** -- E2E-svit som startar appen och använder riktig MCP SDK-klienttransport -- A2A-klient testar för upptäckt, skicka, streama, hämta och avbryta flöden -- Korskontrollera påståenden mot MCP-revision och A2A-uppgifter API:er +- 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. "Jag behöver enhetlig observerbarhet över alla gränssnitt"
+📡 28. "I need unified observability across all interfaces"
-Att dela upp observerbarheten enligt protokoll skapar blinda fläckar och längre MTTR. +Splitting observability by protocol creates blind spots and longer MTTR. -**Hur OmniRoute löser det:** +**How OmniRoute solves it:** -- Enhetliga instrumentpaneler/loggar/analyser i en produkt -- Hälsa + revision + begäran om telemetri över OpenAI-, MCP- och A2A-lager -- Operativa API:er för status och automatisering +- Unified dashboards/logs/analytics in one product +- Health + audit + request telemetry across OpenAI, MCP, and A2A layers +- Operational APIs for status and automation
-
💼 29. "Jag behöver en körtid för proxy + verktyg + agentorkestrering"
+💼 29. "I need one runtime for proxy + tools + agent orchestration"
-Att köra många separata tjänster ökar driftskostnaderna och fellägen. +Running many separate services increases operational cost and failure modes. -**Hur OmniRoute löser det:** +**How OmniRoute solves it:** -- OpenAI-kompatibel proxy, MCP-server och A2A-server i en stack -- Delad autentisering, resiliens, datalagring och observerbarhet -- Konsekvent policymodell över alla interaktionsytor +- 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
-
-### Exempel på Playbooks (integrerade användningsfall)
+### Example Playbooks (Integrated Use Cases)
-**Playbook A: Maximera betald prenumeration + billig backup**
+**Playbook A: Maximize paid subscription + cheap backup**
```txt
Combo: "maximize-claude"
@@ -683,7 +694,7 @@ Monthly cost: $20 + small backup spend
Outcome: higher quality, near-zero interruption
```
-**Playbook B: Noll-kostnad kodningsstack**
+**Playbook B: Zero-cost coding stack**
```txt
Combo: "free-forever"
@@ -695,7 +706,7 @@ Monthly cost: $0
Outcome: stable free coding workflow
```
-**Playbook C: 24/7 alltid-på reservkedja**
+**Playbook C: 24/7 always-on fallback chain**
```txt
Combo: "always-on"
@@ -708,65 +719,132 @@ Combo: "always-on"
Outcome: deep fallback depth for deadline-critical workloads
```
-**Playbook D: Agent ops med MCP + A2A**
+**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/mcp and /dashboard/a2a
-4) Control incidents with resilience profile + task cancellation
+3) Observe via /dashboard/endpoint (MCP and A2A tabs)
+4) Toggle services via inline status controls
```
---
-## ⚡ Snabbstart
+## 🆓 Start Free — Zero Configuration Cost
-**1. Installera globalt:**
+> 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 **iFlow** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |
+| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |
+| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |
+| 5 | `/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).
+
+## Snabbstart
+
+### 1) Install and run
```bash
npm install -g omniroute
omniroute
```
-🎉 Instrumentpanelen öppnar kl. `http://localhost:20128`
+> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:
+>
+> ```bash
+> pnpm install -g omniroute
+> pnpm approve-builds -g # Select all packages → approve
+> omniroute
+> ```
-| Kommando | Beskrivning |
-| ----------------------- | ---------------------------------- |
-| `omniroute` | Startserver (standardport 20128) |
-| `omniroute --port 3000` | Använd anpassad port |
-| `omniroute --no-open` | Öppna inte webbläsaren automatiskt |
-| `omniroute --help` | Visa hjälp |
+Dashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.
-**2. Anslut en GRATIS leverantör:**
+| 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 |
-Dashboard → Leverantörer → Anslut **Claude Code** eller **Antigravity** → OAuth-inloggning → Klar!
+Optional split-port mode:
-**3. Använd i ditt CLI-verktyg:**
-
-```
-Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Settings:
- Endpoint: http://localhost:20128/v1
- API Key: [copy from dashboard]
- Model: if/kimi-k2-thinking
+```bash
+PORT=20128 DASHBOARD_PORT=20129 omniroute
+# API: http://localhost:20128/v1
+# Dashboard: http://localhost:20129
```
-**Det var allt!** Börja koda med GRATIS AI-modeller.
+### 2) Connect providers and create your API key
-**Alternativ – kör från källan:**
+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
+
+```txt
+Base URL: http://localhost:20128/v1
+API Key: [copy from Endpoint page]
+Model: if/kimi-k2-thinking (or any provider/model prefix)
+```
+
+Works with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.
+
+### 4) Enable and validate protocols (v2.0)
+
+**MCP (for tool-driven operations):**
+
+```bash
+omniroute --mcp
+```
+
+Then connect your MCP client over `stdio` and test tools like:
+
+- `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 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
+PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev
```
---
-## 🐳 Hamnarbetare
+## 🐳 Docker
-OmniRoute är tillgänglig som en offentlig Docker-bild på [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
+OmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
-**Snabbkörning:**
+**Quick run:**
```bash
docker run -d \
@@ -777,7 +855,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Med miljöfil:**
+**With environment file:**
```bash
# Copy and edit .env first
@@ -792,7 +870,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Använda Docker Compose:**
+**Using Docker Compose:**
```bash
# Base profile (no CLI tools)
@@ -802,257 +880,550 @@ docker compose --profile base up -d
docker compose --profile cli up -d
```
-| Bild | Tagga | Storlek | Beskrivning |
-| ------------------------ | -------- | ------- | ----------------------- |
-| `diegosouzapw/omniroute` | `latest` | ~250MB | Senaste stabila utgåvan |
-| `diegosouzapw/omniroute` | `1.0.3` | ~250MB | Aktuell version |
+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.
+- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.
+- 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` | `1.0.3` | ~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
+### Snabbstart
+
```bash
-npm run electron:dev # Development mode
+# 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)
+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)
---
-## 💰 Prissättning i en överblick
+## 💰 Pricing at a Glance
-| Nivå | Leverantör | Kostnad | Kvotåterställning | Bäst för |
-| -------------------- | ----------------- | ----------------------- | ------------------------ | ----------------------- |
-| **💳 PRENUMERATION** | Claude Code (Pro) | 20 USD/månad | 5h + veckovis | Har redan prenumererat |
-| | Codex (Plus/Pro) | 20-200 USD/månad | 5h + veckovis | OpenAI-användare |
-| | Gemini CLI | **GRATIS** | 180K/månad + 1K/dag | Alla! |
-| | GitHub Copilot | 10-19 USD/månad | Månatlig | GitHub-användare |
-| **🔑 API-NYCKEL** | NVIDIA NIM | **GRATIS** (1000 poäng) | Engång | Gratis nivåtestning |
-| | DeepSeek | Betala per användning | Inga | Bästa pris/kvalitet |
-| | Groq | Gratis nivå + betald | Begränsat pris | Ultrasnabb slutledning |
-| | xAI (Grok) | Betala per användning | Inga | Grok modeller |
-| | Mistral | Gratis nivå + betald | Begränsat pris | Europeisk AI |
-| | OpenRouter | Betala per användning | Inga | 100+ modeller |
-| **💰 BILLIGT** | GLM-4.7 | $0,6/1M | Dagligen 10:00 | Budget backup |
-| | MiniMax M2.1 | $0,2/1M | 5-timmars rullande | Billigaste alternativet |
-| | Kimi K2 | 9 USD/mån lägenhet | 10 miljoner tokens/månad | Förutsägbar kostnad |
-| **🆓 GRATIS** | iFlow | $0 | Obegränsad | 8 modeller gratis |
-| | Qwen | $0 | Obegränsad | 3 modeller gratis |
-| | Kiro | $0 | Obegränsad | Claude gratis |
+| 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 |
+| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |
+| | 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** | iFlow | **$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 |
-**💡 Proffstips:** Börja med Gemini CLI (180K gratis/månad) + iFlow (obegränsat gratis) combo = $0 kostnad!
+> 🆕 **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
+iFlow (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.
---
-## 💡 Nyckelfunktioner
+---
-### 🧠 Core Routing & Intelligence
+## 🆓 Free Models — What You Actually Get
-| Funktion | Vad det gör |
-| ------------------------------ | ----------------------------------------------------------------------------------------- |
-| 🎯 **Smart 4-lagers reserv** | Automatisk rutt: Prenumeration → API-nyckel → Billigt → Gratis |
-| 📊 **Kvotspårning i realtid** | Live token count + återställ nedräkning per leverantör |
-| 🔄 **Formatöversättning** | OpenAI ↔ Claude ↔ Gemini ↔ Markör ↔ Kiro sömlös + sanering av svar |
-| 👥 **Multi-Account Support** | Flera konton per leverantör med intelligent urval |
-| 🔄 **Auto Token Refresh** | OAuth-tokens uppdateras automatiskt med försök igen |
-| 🎨 **Anpassade kombinationer** | 6 strategier: fill-first, round-robin, p2c, slumpmässig, minst använda, kostnadsoptimerad |
-| 🧩 **Anpassade modeller** | Lägg till valfritt modell-ID till valfri leverantör |
-| 🌐 **Wildcard-router** | Dirigera `provider/*`-mönster till valfri leverantör dynamiskt |
-| 🧠 **Tänkande budget** | Genomgång, auto, anpassade och adaptiva lägen för resonerande modeller |
-| 🔀 **Model Aliases** | Auto-forward deprecated model IDs to current replacements (built-in + custom) |
-| ⚡ **Background Degradation** | Auto-route background tasks (titles, summaries) to cheaper models |
-| 💬 **System Prompt Injection** | Global systemprompt tillämpas på alla förfrågningar |
-| 📄 **Responses API** | Fullständigt stöd för OpenAI Responses API (`/v1/responses`) för Codex |
+> 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.
-### 🎵 Multimodala API:er
+### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)
-| Funktion | Vad det gör |
-| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 🖼️ **Bildgenerering** | `/v1/images/generations` — 4 leverantörer, 9+ modeller |
-| 📐 **Inbäddningar** | `/v1/embeddings` — 6 leverantörer, 9+ modeller |
-| 🎤 **Ljudtranskription** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |
-| 🔊 **Text-till-tal** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) |
-| 🛡️ **Moderationer** | `/v1/moderations` — Innehållssäkerhetskontroller |
-| 🔀 **Omrankning** | `/v1/rerank` — Omrankning av dokumentrelevans |
+| 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 |
-### 🛡️ Motståndskraft och säkerhet
+### 🟢 IFLOW MODELS (Free OAuth — No Credit Card)
-| Funktion | Vad det gör |
-| -------------------------------------- | -------------------------------------------------------------------------------------- |
-| 🔌 **Circuit Breaker** | Autoöppna/stäng per leverantör med konfigurerbara trösklar |
-| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |
-| 🛡️ **Anti-ånflock** | Mutex + semaforhastighetsgräns för API-nyckelleverantörer |
-| 🧠 **Semantisk cache** | Tvåskiktscache (signatur + semantisk) minskar kostnaden och fördröjningen |
-| ⚡ **Begär idempotens** | 5s dedup-fönster för dubblettförfrågningar |
-| 🔒 **TLS Fingerprint Spoofing** | Förbi TLS-baserad botdetektering via wreq-js |
-| 🔏 **CLI Fingerprint Matching** | Matches native CLI request signatures — **reduces ban risk while preserving proxy IP** |
-| 🌐 **IP-filtrering** | Tillåtelselista/blockeringslista för API-åtkomstkontroll |
-| 📊 **Redigerbara hastighetsgränser** | Konfigurerbart RPM, min gap och max samtidiga på systemnivå |
-| 💾 **Rate Limit Persistence** | Learned limits survive restarts via SQLite with 60s debounce + 24h staleness |
-| 🔄 **Token Refresh Resilience** | Per-provider circuit breaker (5 fails→30min) + 30s timeout per attempt |
-| 🛡 **API Endpoint Protection** | Auth gating + leverantörsblockering för `/models` slutpunkt |
-| 🔒 **Proxysynlighet** | Färgkodade märken: 🟢 global, 🟡 leverantör, 🔵 per anslutning med IP-display |
-| 🌐 **Proxykonfiguration med 3 nivåer** | Konfigurera proxyservrar på global nivå, per leverantör eller per anslutningsnivå |
+| 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 |
-### 📊 Observerbarhet och analys
+### 🟡 QWEN MODELS (Device Code Auth)
-| Funktion | Vad det gör |
-| -------------------------------- | ----------------------------------------------------------------------------- |
-| 📝 **Begär loggning** | Felsökningsläge med fullständiga förfrågnings-/svarsloggar |
-| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |
-| 💾 **SQLite proxyloggar** | Beständiga proxyloggar överlever serverstarter |
-| 📊 **Analytics Dashboard** | Recharts-driven: statistikkort, modellanvändningsdiagram, leverantörstabell |
-| 📈 **Förloppsspårning** | Opt-in SSE-förloppshändelser för streaming |
-| 🧪 **LLM-utvärderingar** | Golden set testning med 4 matchstrategier |
-| 🔍 **Begär telemetri** | p50/p95/p99 latensaggregation + X-Request-Id-spårning |
-| 📋 **Dashboard för loggar** | Enad sida med 4 flikar: Begäranloggar, Proxyloggar, Granskningsloggar, Konsol |
-| 🖥️ **Konsolloggvisare** | Realtidsvisare i terminalstil med nivåfilter, sökning, automatisk rullning |
-| 📑 **Filbaserad loggning** | Console Interceptor fångar all utdata till JSON-loggfilen med rotation |
-| 🏥 **Hälsoinstrumentpanel** | Systemupptid, strömbrytartillstånd, låsningar, cachestatistik |
-| 💰 **Kostnadsspårning** | Budgethantering + prissättning per modell |
+| 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) |
-### ☁️ Implementering och synkronisering
+### 🟣 GEMINI CLI (Google OAuth)
-| Funktion | Vad det gör |
-| -------------------------------- | -------------------------------------------------------------------------------------- |
-| 💾 **Cloud Sync** | Synkronisera konfiguration mellan enheter via Cloudflare Workers |
-| 🌐 **Distribuera var som helst** | Localhost, VPS, Docker, Cloudflare Workers |
-| 🔑 **API-nyckelhantering** | Generera, rotera och omfång API-nycklar per leverantör |
-| 🧙 **Onboarding Wizard** | 4-stegs guidad installation för förstagångsanvändare |
-| 🔧 **CLI Tools Dashboard** | Konfigurera med ett klick Claude, Codex, Cline, OpenClaw, Kilo, Antigravity |
-| 🔄 **DB-säkerhetskopior** | Automatisk säkerhetskopiering, återställning, export och import för alla inställningar |
-| 🌐 **Internationalisering** | Fullständig i18n med nästa-intl — stöd för engelska + portugisiska (Brasilien) |
-| 🌍 **Språkväljare** | Globikon i rubriken för språkväxling i realtid (🇺🇸/🇧🇷) |
-| 🧹 **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 |
-| 📂 **Anpassad datakatalog** | `DATA_DIR` env var för att åsidosätta standard `~/.omniroute` lagringssökväg |
+| Model | Prefix | Limit | Rate Limit |
+| ------------------------ | ------ | --------------------------- | ------------- |
+| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |
+| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |
+
+### ⚫ 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
+> iFlow (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 v2.0 is built as an operational platform, not just a relay proxy.
+
+### 🆕 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 Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |
+| 🤖 **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 (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) |
+| 🤝 **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** | 9 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 combo, apply resilience profiles, reset breakers from one control surface |
+
+### 🧠 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** | 6 balancing strategies + fallback chain control |
+| 🌐 **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) |
+| 💬 **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 |
+| ----------------------------------- | -------------------------------------------------------------------------------------- |
+| 🔌 **Circuit Breakers** | Per-model trip/recover with threshold controls |
+| 🎯 **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 |
+| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |
+| 🔑 **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 |
+
+### 📊 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 |
+| 📋 **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 |
+
+### ☁️ Deployment & Platform
+
+| Feature | What It Does |
+| ----------------------------- | --------------------------------------------------------- |
+| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |
+| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |
+| 💾 **Cloud Sync** | Configuration sync via cloud worker |
+| 🔄 **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 |
+
+### Feature Deep Dive
+
+#### Smart fallback with practical cost control
+
+```txt
+Combo: "my-coding-stack"
+ 1. cc/claude-opus-4-6
+ 2. nvidia/llama-3.3-70b
+ 3. glm/glm-4.7
+ 4. if/kimi-k2-thinking
+```
+
+When quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.
+
+#### 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)
+
+#### 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)
🚀 30. "Jag behöver skicka agentiska arbetsflöden utan limkodsprawl"
+🚀 30. "I need to ship agentic workflows without glue-code sprawl"
-Lag tappar hastighet när de sammanfogar flera ad-hoc-tjänster och skript. +Teams lose velocity when stitching multiple ad-hoc services and scripts. -**Hur OmniRoute löser det:** +**How OmniRoute solves it:** -- Enhetlig slutpunktsstrategi för kunder och agenter -- Inbyggda gränssnitt för protokollhantering och rökvalideringsvägar -- Produktionsfärdiga grunder (säkerhet, loggning, resiliens, backup) +- Unified endpoint strategy for clients and agents +- Built-in protocol management UIs and smoke validation paths +- Production-ready foundations (security, logging, resilience, backup)
-` block → `reasoning_content` för tänkande modeller
-- **Structured output** — `json_schema` → Gemini's `responseMimeType`/`responseSchema`
-
-### 👥 Support för flera konton
-
-- Lägg till flera konton per leverantör
-- Auto round-robin eller prioritetsbaserad routing
-- Fallback till nästa konto när man når kvoten
-
-### 🔄 Auto Token Refresh
-
-- OAuth-tokens uppdateras automatiskt innan utgången
-- Ingen manuell återautentisering behövs
-- Sömlös upplevelse hos alla leverantörer
-
-### 🎨 Anpassade kombinationer
-
-- Skapa obegränsade modellkombinationer
-- 6 strategier: fyll-först, round-robin, kraft-av-två-val, slumpmässig, minst använda, kostnadsoptimerad
-- Dela kombinationer mellan enheter med Cloud Sync
-
-### 🏥 Health Dashboard
-
-- Systemstatus (upptid, version, minnesanvändning)
-- Strömbrytarstatus per leverantör (stängd/öppen/halvöppen)
-- Prisgränsstatus och aktiva låsningar
-- Signaturcachestatistik
-- Latens-telemetri (p50/p95/p99) + promptcache
-- Återställ hälsostatus med ett klick
-
-### 🔧 Översättarlekplats
-
-OmniRoute inkluderar en kraftfull inbyggd översättarlekplats med **4 lägen** för felsökning, testning och övervakning av API-översättningar:
-
-| Läge | Beskrivning |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **💻 Lekplats** | Direkt formatöversättning — klistra in valfri API-begäran och se direkt hur OmniRoute översätter den mellan leverantörsformat (OpenAI ↔ Claude ↔ Gemini ↔ Responses API). Inkluderar exempelmallar och automatisk identifiering av format. |
-| **💬 Chattestare** | Skicka riktiga chattförfrågningar genom OmniRoute och se hela tur och retur: din input, den översatta begäran, leverantörens svar och det översatta svaret tillbaka. Ovärderligt för att validera combo routing. |
-| **🧪 Testbänk** | Batchtestläge — definiera flera testfall med olika ingångar och förväntade utgångar, kör dem alla på en gång och jämför resultat mellan leverantörer och modeller. |
-| **📱 Live Monitor** | Bevakning av förfrågningar i realtid — titta på inkommande förfrågningar när de flödar genom OmniRoute, se formatöversättningar som sker live och identifiera problem direkt. |
-
-**Åtkomst:** Instrumentpanel → Översättare (sidofält)
-
-### 💾 Cloud Sync
-
-- Synkronisera leverantörer, kombinationer och inställningar mellan enheter
-- Automatisk bakgrundssynkronisering
-- Säker krypterad lagring
+- `GET /api/mcp/status`
+- `GET /api/mcp/tools`
+- `GET /api/mcp/audit`
+- `GET /api/mcp/audit/stats`
-## 🧪 Utvärderingar (Evals)
+📖 Funktionsdetaljer
+🧩 MCP Setup (Model Context Protocol)
-### 🎯 Smart 4-lagers reserv +Start MCP transport in stdio mode: -Skapa kombinationer med automatisk reserv: - -``` -Combo: "my-coding-stack" - 1. cc/claude-opus-4-6 (your subscription) - 2. nvidia/llama-3.3-70b (free NVIDIA API) - 3. glm/glm-4.7 (cheap backup, $0.6/1M) - 4. if/kimi-k2-thinking (free fallback) - -→ Auto switches when quota runs out or errors occur +```bash +omniroute --mcp ``` -### 📊 Kvotspårning i realtid +Recommended validation flow: -- Tokenförbrukning per leverantör -- Återställ nedräkningen (5 timmar, dagligen, veckovis) -- Kostnadsuppskattning för betalda nivåer -- Månatliga utgiftsrapporter +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. -### 🔄 Formatöversättning +Useful APIs for automation: -Sömlös översättning mellan format: - -- **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **OpenAI-svar** -- Ditt CLI-verktyg skickar OpenAI-format → OmniRoute översätter → Leverantör tar emot inbyggt format -- Fungerar med alla verktyg som stöder anpassade OpenAI-slutpunkter -- **Responssanering** — Tar bort icke-standardiserade fält för strikt OpenAI SDK-kompatibilitet -- **Rollnormalisering** — `developer` → `system` för icke-OpenAI; `system` → `user` för GLM/ERNIE-modeller -- **Think tag extrahering** — `
+
🤝 A2A Setup (Agent2Agent)
-OmniRoute inkluderar ett inbyggt utvärderingsramverk för att testa LLM-svarskvalitet mot en gyllene uppsättning. Få åtkomst till det via **Analytics → Evals** i instrumentpanelen. +Discover the agent: -### Inbyggt gyllene set +```bash +curl http://localhost:20128/.well-known/agent.json +``` -Det förinstallerade "OmniRoute Golden Set" innehåller 10 testfall som täcker: +Send a task: -- Hälsningar, matematik, geografi, kodgenerering -- JSON-formatöverensstämmelse, översättning, markdown -- Säkerhetsvägran (skadligt innehåll), räkning, boolesk logik +```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."}]}}' +``` -### Utvärderingsstrategier +Manage lifecycle: -| Strategi | Beskrivning | Exempel | -| ---------- | ---------------------------------------------------- | -------------------------------- | -| `exact` | Utdata måste matcha exakt | `"4"` | -| `contains` | Utdata måste innehålla delsträng (skiftlägeskänslig) | `"Paris"` | -| `regex` | Utdata måste matcha regexmönster | `"1.*2.*3"` | -| `custom` | Anpassad JS-funktion returnerar true/false | `(output) => output.length > 10` | +- `GET /api/a2a/status` +- `GET /api/a2a/tasks` +- `GET /api/a2a/tasks/:id` +- `POST /api/a2a/tasks/:id/cancel` ---- +Operational UI: -## 📖 Installationsguide +- `/dashboard/a2a` for task/state/stream observability and smoke actions + +
-
+
+💳 Prenumerationsleverantörer
+🧪 End-to-end protocol validation
+ +Validate both protocols with real clients: + +```bash +npm run test:protocols:e2e +``` + +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) @@ -1067,7 +1438,7 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Proffstips:** Använd Opus för komplexa uppgifter, Sonnet för snabbhet. OmniRoute spårar kvot per modell! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! ### OpenAI Codex (Plus/Pro) @@ -1081,7 +1452,24 @@ Models: cx/gpt-5.1-codex-max ``` -### Gemini CLI (GRATIS 180K/månad!) +#### 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). + +### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -1093,7 +1481,7 @@ Models: gc/gemini-2.5-pro ``` -**Bäst värde:** Enorma gratis nivå! Använd detta före betalda nivåer. +**Best Value:** Huge free tier! Use this before paid tiers. ### GitHub Copilot @@ -1111,88 +1499,88 @@ Models:
-
🔑 API-nyckelleverantörer
+🔑 API Key Providers
-### NVIDIA NIM (GRATIS 1000 krediter!) +### NVIDIA NIM (FREE developer access — 70+ models) -1. Registrera dig: [build.nvidia.com](https://build.nvidia.com) -2. Få gratis API-nyckel (1000 slutsatspoäng ingår) -3. Dashboard → Lägg till leverantör → NVIDIA NIM: - - API-nyckel: `nvapi-your-key` +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` -**Modeller:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct` och 50+ till +**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more -**Proffstips:** OpenAI-kompatibelt API — fungerar sömlöst med OmniRoutes formatöversättning! +**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation! ### DeepSeek -1. Registrera dig: [platform.deepseek.com](https://platform.deepseek.com) -2. Hämta API-nyckel -3. Dashboard → Lägg till leverantör → DeepSeek +1. Sign up: [platform.deepseek.com](https://platform.deepseek.com) +2. Get API key +3. Dashboard → Add Provider → DeepSeek -**Modeller:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` +**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` -### Groq (gratis nivå tillgänglig!) +### Groq (Free Tier Available!) -1. Registrera dig: [console.groq.com](https://console.groq.com) -2. Skaffa API-nyckel (gratis nivå ingår) -3. Dashboard → Lägg till leverantör → Groq +1. Sign up: [console.groq.com](https://console.groq.com) +2. Get API key (free tier included) +3. Dashboard → Add Provider → Groq -**Modeller:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` +**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` -**Proffstips:** Ultrasnabb slutledning — bäst för realtidskodning! +**Pro Tip:** Ultra-fast inference — best for real-time coding! -### OpenRouter (100+ modeller) +### OpenRouter (100+ Models) -1. Registrera dig: [openrouter.ai](https://openrouter.ai) -2. Hämta API-nyckel -3. Dashboard → Lägg till leverantör → OpenRouter +1. Sign up: [openrouter.ai](https://openrouter.ai) +2. Get API key +3. Dashboard → Add Provider → OpenRouter -**Modeller:** Få tillgång till 100+ modeller från alla större leverantörer genom en enda API-nyckel. +**Models:** Access 100+ models from all major providers through a single API key.
-
💰 Billiga leverantörer (backup)
+💰 Cheap Providers (Backup)
-### GLM-4.7 (Daglig återställning, $0,6/1M) +### GLM-4.7 (Daily reset, $0.6/1M) -1. Registrera dig: [Zhipu AI](https://open.bigmodel.cn/) -2. Hämta API-nyckel från Coding Plan -3. Instrumentpanel → Lägg till API-nyckel: - - Leverantör: `glm` - - API-nyckel: `your-key` +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` -**Använd:** `glm/glm-4.7` +**Use:** `glm/glm-4.7` -**Proffstips:** Coding Plan erbjuder 3× kvot till 1/7 kostnad! Återställ dagligen 10:00. +**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -### MiniMax M2.1 (5 timmars återställning, $0,20/1M) +### MiniMax M2.1 (5h reset, $0.20/1M) -1. Registrera dig: [MiniMax](https://www.minimax.io/) -2. Hämta API-nyckel -3. Instrumentpanel → Lägg till API-nyckel +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key +3. Dashboard → Add API Key -**Använd:** `minimax/MiniMax-M2.1` +**Use:** `minimax/MiniMax-M2.1` -**Proffstips:** Billigaste alternativet för långa sammanhang (1M tokens)! +**Pro Tip:** Cheapest option for long context (1M tokens)! -### Kimi K2 ($9/månad platt) +### Kimi K2 ($9/month flat) -1. Prenumerera: [Moonshot AI](https://platform.moonshot.ai/) -2. Hämta API-nyckel -3. Instrumentpanel → Lägg till API-nyckel +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key +3. Dashboard → Add API Key -**Använd:** `kimi/kimi-latest` +**Use:** `kimi/kimi-latest` -**Proffstips:** Fast $9/månad för 10 miljoner tokens = $0,90/1 miljon effektiv kostnad! +**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
-
🆓 GRATIS leverantörer (nödbackup)
+🆓 FREE Providers (Emergency Backup)
-### iFlow (8 GRATIS modeller) +### iFlow (5 FREE models via OAuth) ```bash Dashboard → Connect iFlow @@ -1207,7 +1595,7 @@ Models: if/deepseek-r1 ``` -### Qwen (3 GRATIS modeller) +### Qwen (4 FREE models via Device Code) ```bash Dashboard → Connect Qwen @@ -1234,9 +1622,9 @@ Models:
-
🎨 Skapa kombinationer
+🎨 Create Combos
-### Exempel 1: Maximera prenumeration → Billig backup +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -1250,7 +1638,7 @@ Models: Use in CLI: premium-coding ``` -### Exempel 2: Endast gratis (noll kostnad) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -1265,9 +1653,9 @@ Cost: $0 forever!
-
---
-## 🐛 Felsökning
+## Felsökning
🔧 CLI-integration
+🔧 CLI Integration
-### Markör IDE +### Cursor IDE ``` Settings → Models → Advanced: @@ -1278,7 +1666,7 @@ Settings → Models → Advanced: ### Claude Code -Använd sidan **CLI Tools** i instrumentpanelen för konfiguration med ett klick, eller redigera `~/.claude/settings.json` manuellt. +Use the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually. ### Codex CLI @@ -1291,13 +1679,13 @@ codex "your prompt" ### OpenClaw -**Alternativ 1 — Instrumentpanel (rekommenderas):** +**Option 1 — Dashboard (recommended):** ``` Dashboard → CLI Tools → OpenClaw → Select Model → Apply ``` -**Alternativ 2 — Manuell:** Redigera `~/.openclaw/openclaw.json`: +**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`: ```json { @@ -1313,9 +1701,9 @@ Dashboard → CLI Tools → OpenClaw → Select Model → Apply } ``` -> **Obs!** OpenClaw fungerar endast med lokal OmniRoute. Använd `127.0.0.1` istället för `localhost` för att undvika problem med IPv6-upplösning. +> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues. -### Cline / Fortsätt / RooCode +### Cline / Continue / RooCode ``` Settings → API Configuration: @@ -1325,96 +1713,231 @@ Settings → API Configuration: 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. +
- โควต้าการสมัครจะหมดอายุโดยไม่ได้ใช้ทุกเดือน
-- การจำกัดอัตราจะทำให้คุณไม่สามารถเขียนโค้ดกลางคันได้
-- API ราคาแพง ($20-50/เดือนต่อผู้ให้บริการ)
-- การสลับระหว่างผู้ให้บริการด้วยตนเอง
-
-**OmniRoute แก้ปัญหานี้:**
-
-- ✅ **เพิ่มการสมัครรับข้อมูลสูงสุด** - ติดตามโควต้า ใช้ทุกบิตก่อนรีเซ็ต
-- ✅ **ทางเลือกสำรองอัตโนมัติ** - การสมัครสมาชิก → คีย์ API → ราคาถูก → ฟรี ไม่มีการหยุดทำงาน
-- ✅ **หลายบัญชี** - หมุนเวียนระหว่างบัญชีต่อผู้ให้บริการ
-- ✅ **สากล** - ใช้งานได้กับ Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw และเครื่องมือ CLI ใดๆ
-
----
-
-## 📧 สนับสนุน
-
-> 💌 **เข้าร่วมชุมชนของเรา!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — รับความช่วยเหลือ แบ่งปันเคล็ดลับ และติดตามข่าวสารล่าสุด
-
-- **เว็บไซต์**: [omniroute.online](https://omniroute.online)
+- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **ปัญหา**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **โปรเจ็กต์ดั้งเดิม**: [9router by decolua](https://github.com/decolua/9router)
+- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 มันทำงานอย่างไร
+## 🔄 How It Works
```
┌─────────────┐
@@ -227,452 +236,453 @@ Result: Never stop coding, minimal cost
---
-## 🎯 สิ่งที่ OmniRoute แก้ปัญหาได้ — 30 คะแนนปัญหาและกรณีการใช้งานจริง
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **นักพัฒนาทุกคนที่ใช้เครื่องมือ AI ต้องเผชิญกับปัญหาเหล่านี้ทุกวัน** OmniRoute ถูกสร้างขึ้นเพื่อแก้ไขปัญหาทั้งหมด ตั้งแต่ค่าใช้จ่ายที่มากเกินไปไปจนถึงการบล็อกระดับภูมิภาค จากโฟลว์ OAuth ที่เสียหาย ไปจนถึงการทำงานของโปรโตคอลและความสามารถในการสังเกตระดับองค์กร
+> **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.
Квота підписки закінчується без використання кожного місяця
-- Обмеження швидкості перешкоджають кодуванню в середині
-- Дорогі API ($20-50/місяць за постачальника)
-- Ручне перемикання між провайдерами
-
-**OmniRoute вирішує цю проблему:**
-
-- ✅ **Збільште кількість підписок** - Відстежуйте квоту, використовуйте кожен біт перед скиданням
-- ✅ **Автоматичний резерв** - Підписка → Ключ API → Дешево → Безкоштовно, без простоїв
-- ✅ **Кілька облікових записів** - Циклічний цикл між обліковими записами кожного постачальника
-- ✅ **Універсальний** - Працює з Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, будь-яким інструментом CLI
-
----
-
-## 📧 Підтримка
-
-> 💬 **Приєднуйтесь до нашої спільноти!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — отримуйте допомогу, діліться порадами та будьте в курсі подій.
-
-- **Веб-сайт**: [omniroute.online](https://omniroute.online)
+- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Проблеми**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Оригінальний проект**: [9router by decolua](https://github.com/decolua/9router)
+- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 Як це працює
+## 🔄 How It Works
```
┌─────────────┐
@@ -227,456 +236,453 @@ Result: Never stop coding, minimal cost
---
-## 🎯 Що вирішує OmniRoute — 30 реальних проблем і варіантів використання
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **Кожен розробник, який використовує інструменти штучного інтелекту, щодня стикається з цими проблемами.** OmniRoute було створено, щоб вирішити їх усі — від перевитрати коштів до регіональних блокувань, від порушених потоків OAuth до операцій протоколу та спостережуваності підприємства.
+> **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.
Klicka för att expandera felsökningsguide
+Click to expand troubleshooting guide
-**"Språkmodellen gav inga meddelanden"** +**"Language model did not provide messages"** -- Leverantörskvoten är slut → Kontrollera instrumentpanelens kvotföljare -- Lösning: Använd kombinationsalternativ eller byt till billigare nivå +- Provider quota exhausted → Check dashboard quota tracker +- Solution: Use combo fallback or switch to cheaper tier -**Taxebegränsning** +**Rate limiting** -- Prenumerationskvot ute → Fallback till GLM/MiniMax -- Lägg till kombination: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Subscription quota out → Fallback to GLM/MiniMax +- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -**OAuth-token har löpt ut** +**OAuth token expired** -- Automatisk uppdatering av OmniRoute -- Om problemen kvarstår: Dashboard → Leverantör → Återanslut +- Auto-refreshed by OmniRoute +- If issues persist: Dashboard → Provider → Reconnect -**Höga kostnader** +**High costs** -- Kontrollera användningsstatistik i Dashboard → Kostnader -- Byt primär modell till GLM/MiniMax -- Använd gratis nivå (Gemini CLI, iFlow) för icke-kritiska uppgifter +- Check usage stats in Dashboard → Costs +- Switch primary model to GLM/MiniMax +- Use free tier (Gemini CLI, iFlow) for non-critical tasks -**Dashboard öppnas på fel port** +**Dashboard/API ports are wrong** -- Set `PORT=20128` och `NEXT_PUBLIC_BASE_URL=http://localhost:20128` +- `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) -**Molnsynkroniseringsfel** +**Cloud sync errors** -- Verifiera att `BASE_URL` pekar på din löpinstans -- Verifiera `CLOUD_URL` poäng till din förväntade molnslutpunkt -- Håll `NEXT_PUBLIC_*` värden i linje med värden på serversidan +- 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 -**Första inloggningen fungerar inte** +**First login not working** -- Kontrollera `INITIAL_PASSWORD` i `.env` -- Om det inte är inställt är reservlösenordet `123456` +- Check `INITIAL_PASSWORD` in `.env` +- If unset, fallback password is `123456` -**Inga förfrågningsloggar** +**No request logs** -- Ställ in `ENABLE_REQUEST_LOGS=true` i `.env` +- Set `ENABLE_REQUEST_LOGS=true` in `.env` -**Anslutningstest visar "Invalid" för OpenAI-kompatibla leverantörer** +**Connection test shows "Invalid" for OpenAI-compatible providers** -- Många leverantörer exponerar inte en `/models` slutpunkt -- OmniRoute v1.0.6+ inkluderar reservvalidering via chattslutföranden -- Se till att baswebbadressen innehåller suffixet `/v1` +- 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 +### 🔐 OAuth on a Remote Server + -> **⚠️ VIKTIGT för användning av OmniRoute med VPS/Docker/serverfjärrkontroll** +> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server** -### Hur kan du göra Antigravity / Tvilling CLI på fjärrkontroller? +#### Why does Antigravity / Gemini CLI OAuth fail on remote servers? -Os provedores **Antigravity** och **Gemini CLI** usam **Google OAuth 2.0** för autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo. +The **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console. -Som credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticação com: +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 ``` -### Lösning: Konfigurera självständigt OAuth +#### Solution: Configure your own OAuth credentials -Você precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu service. +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 + +# For Gemini CLI: +GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com +GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +``` + +**6. Restart OmniRoute** + +```bash +# npm: +npm run dev + +# Docker: +docker restart omniroute +``` + +**7. Try connecting again** + +Dashboard → Providers → Antigravity (or Gemini CLI) → OAuth + +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. + +--- + +
+
-- **Körtid**: Node.js 18–22 LTS (⚠️ Node.js 24+ stöds **inte** — `better-sqlite3` inbyggda binärer är inkompatibla)
-- **Språk**: TypeScript 5.9 — **100 % TypeScript** över `src/` och `open-sse/` (v1.0.6)
-- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4
-- **Databas**: LowDB (JSON) + SQLite (domäntillstånd + proxyloggar)
-- **Streaming**: Serversända händelser (SSE)
-- **Auth**: OAuth 2.0 (PKCE) + JWT + API-nycklar
-- **Test**: Node.js testlöpare (368+ enhetstester)
-- **CI/CD**: GitHub-åtgärder (automatisk npm-publicering + Docker Hub vid release)
-- **Webbplats**: [omniroute.online](https://omniroute.online)
-- **Paket**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
-- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
-- **Resiliens**: Strömbrytare, exponentiell backoff, anti-dundrande flock, TLS-spoofing
-
----
-
-## 📖 Dokumentation
-
-| Dokument | Beskrivning |
-| -------------------------------------------- | ---------------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Leverantörer, kombinationer, CLI-integration, distribution |
-| [API Reference](docs/API_REFERENCE.md) | Alla slutpunkter med exempel |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Vanliga problem och lösningar |
-| [Architecture](docs/ARCHITECTURE.md) | Systemarkitektur och interna delar |
-| [Contributing](CONTRIBUTING.md) | Utvecklingsupplägg och riktlinjer |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0-specifikation |
-| [Security Policy](SECURITY.md) | Sårbarhetsrapportering och säkerhetsrutiner |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Komplett guide: VM + nginx + Cloudflare-installation |
-| [Features Gallery](docs/FEATURES.md) | Visuell visning av instrumentpanelen med skärmdumpar |
-
-### 📸 Förhandsgranskning av instrumentpanelen
+## 🛠️ Tech Stack
🇧🇷 Versão em Português
+ +#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos? + +Os provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo. + +As credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticação com: + +``` +Error 400: redirect_uri_mismatch +``` + +#### Solução: Configure suas próprias credenciais OAuth + +Você precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor. #### Passo a passo -**1. Åtkomst till Google Cloud Console** +**1. Acesse o Google Cloud Console** Abra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) **2. Crie um novo OAuth 2.0 Client ID** -- Klicka på dem **"+ Skapa inloggningsuppgifter"** → **"OAuth-klient-ID"** -- Typo de aplicativo: **"Webbapplikation"** -- Namn: escolha qualquer nome (ex: `OmniRoute Remote`) +- Clique em **"+ Create Credentials"** → **"OAuth client ID"** +- Tipo de aplicativo: **"Web application"** +- Nome: escolha qualquer nome (ex: `OmniRoute Remote`) -**3. Adicione som auktoriserade omdirigerings-URI** +**3. Adicione as Authorized Redirect URIs** -Ingen campo **"Auktoriserade omdirigerings-URIs"**, adicione: +No campo **"Authorized redirect URIs"**, adicione: ``` https://seu-servidor.com/callback @@ -1422,11 +1945,11 @@ https://seu-servidor.com/callback > Substitua `seu-servidor.com` pelo domínio ou IP do seu servidor (inclua a porta se necessário, ex: `http://45.33.32.156:20128/callback`). -**4. Spara e kopia som credenciais** +**4. Salve e copie as credenciais** Após criar, o Google mostrará o **Client ID** e o **Client Secret**. -**5. Konfigurera som variáveis de ambiente** +**5. Configure as variáveis de ambiente** No seu `.env` (ou nas variáveis de ambiente do Docker): @@ -1453,21 +1976,21 @@ docker restart omniroute **7. Tente conectar novamente** -Dashboard → Leverantörer → Antigravity (ou Gemini CLI) → OAuth +Dashboard → Providers → Antigravity (ou Gemini CLI) → OAuth Agora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará. --- -### Lösning temporário (som configurar credenciais próprias) +#### Workaround temporário (sem configurar credenciais próprias) Se não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**: -1. O OmniRoute abrirá en URL de autorização till Google +1. O OmniRoute abrirá a URL de autorização do Google 2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto) -3. **Kopiera en webbadress komplett** da barra de endereço do seu webbläsare (mesmo que a página não carregue) +3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue) 4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute -5. Klicka på **"Anslut"** +5. Clique em **"Connect"** > Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não. @@ -1475,128 +1998,123 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux --- -## 🛠️ +
-
---
-## 🗺️
+## Dokumentation
-OmniRoute har **210+ funktioner planerade** över flera utvecklingsfaser. Här är nyckelområdena:
-
-| Kategori | Planerade funktioner | Höjdpunkter |
-| ------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------ |
-| 🧠 **Routing & intelligens** | 25+ | Routning med lägsta latens, taggbaserad routing, kvotförhandskontroll, val av P2C-konto |
-| 🔒 **Säkerhet och efterlevnad** | 20+ | SSRF-härdning, cloaking av autentiseringsuppgifter, hastighetsgräns per endpoint, hanteringsnyckelomfattning |
-| 📊 **Observerbarhet** | 15+ | OpenTelemetry-integration, kvotövervakning i realtid, kostnadsspårning per modell |
-| 🔄 **Providerintegrationer** | 20+ | Dynamiskt modellregister, nedkylning av leverantörer, Codex för flera konton, Copilot-kvotanalys |
-| ⚡ **Prestanda** | 15+ | Dubbla cachelager, promptcache, svarscache, streaming keepalive, batch API |
-| 🌐 **Ekosystem** | 10+ | WebSocket API, config hot-reload, distribuerad config store, kommersiellt läge |
-
-### 🔜 Kommer snart
-
-- 🔗 **OpenCode Integration** — Inbyggt leverantörsstöd för OpenCode AI-kodnings-IDE
-- 🔗 **TRAE Integration** — Fullständigt stöd för TRAE AI-utvecklingsramverket
-- 📦 **Batch API** — Asynkron batchbearbetning för bulkförfrågningar
-- 🎯 **Taggbaserad routing** — Ruttbegäranden baserade på anpassade taggar och metadata
-- 💰 **Lägsta kostnadsstrategi** — Välj automatiskt den billigaste tillgängliga leverantören
-
-> 📝 Fullständiga funktionsspecifikationer tillgängliga i [link](docs/new-features/) (217 detaljerade specifikationer)
+| Document | Description |
+| ---------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 16 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/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
+| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
-## 👥 Bidragsgivare
+## 🗺️ Roadmap
+
+OmniRoute has **210+ 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, P2C account selection |
+| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |
+| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |
+| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider 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
[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
-### Hur man bidrar
+### How to Contribute
-1. Dela förvaret
-2. Skapa din funktionsgren (`git checkout -b feature/amazing-feature`)
-3. Bekräfta dina ändringar (`git commit -m 'Add amazing feature'`)
-4. Tryck till grenen (`git push origin feature/amazing-feature`)
-5. Öppna en Pull Request
+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
-Se [CONTRIBUTING.md](CONTRIBUTING.md) för detaljerade riktlinjer.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
-### Släpper en ny version
+### Releasing a New Version
```bash
# Create a release — npm publish happens automatically
-gh release create v1.0.6 --title "v1.0.6" --generate-notes
+gh release create v2.0.0 --title "v2.0.0" --generate-notes
```
---
-## 📊 Stjärnhistorik
+## 📊 Star History
## Stargazers over time
## [](https://starchart.cc/diegosouzapw/OmniRoute)
-## 🙏 Tack
+## 🙏 Acknowledgments
-Speciellt tack till **[9router](https://github.com/decolua/9router)** av **[decolua](https://github.com/decolua)** — originalprojektet som inspirerade denna gaffel. OmniRoute bygger på den otroliga grunden med ytterligare funktioner, multimodala API:er och en fullständig TypeScript-omskrivning.
+Special thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.
-Särskilt tack till **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — den ursprungliga Go-implementeringen som inspirerade denna JavaScript-port.
+Special thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.
---
-## 📄 Licens
+## Licens
-MIT-licens - se [LICENSE](LICENSE) för detaljer.
+MIT License - see [LICENSE](LICENSE) for details.
---
Klicka för att se skärmdumpar på instrumentpanelen
+Click to expand tech stack details
-| Sida | Skärmdump | -| --------------------- | ------------------------------------------------- | -| **Leverantörer** |  | -| **Kombos** |  | -| **Analytics** |  | -| **Hälsa** |  | -| **Översättare** |  | -| **Inställningar** |  | -| **CLI-verktyg** |  | -| **Användningsloggar** |  | -| **Slutpunkt** |  | +- **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**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions) +- **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
- Byggd med ❤️ för utvecklare som kodar 24/7
+ Built with ❤️ for developers who code 24/7
omniroute.online
+
diff --git a/docs/i18n/sv/docs/FEATURES.md b/docs/i18n/sv/docs/FEATURES.md
new file mode 100644
index 0000000000..e0054ba36c
--- /dev/null
+++ b/docs/i18n/sv/docs/FEATURES.md
@@ -0,0 +1,145 @@
+# OmniRoute — Dashboard Features Gallery (Svenska)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/FEATURES.md) · 🇪🇸 [es](../../es/docs/FEATURES.md) · 🇫🇷 [fr](../../fr/docs/FEATURES.md) · 🇩🇪 [de](../../de/docs/FEATURES.md) · 🇮🇹 [it](../../it/docs/FEATURES.md) · 🇷🇺 [ru](../../ru/docs/FEATURES.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FEATURES.md) · 🇯🇵 [ja](../../ja/docs/FEATURES.md) · 🇰🇷 [ko](../../ko/docs/FEATURES.md) · 🇸🇦 [ar](../../ar/docs/FEATURES.md) · 🇮🇳 [in](../../in/docs/FEATURES.md) · 🇹🇭 [th](../../th/docs/FEATURES.md) · 🇻🇳 [vi](../../vi/docs/FEATURES.md) · 🇮🇩 [id](../../id/docs/FEATURES.md) · 🇲🇾 [ms](../../ms/docs/FEATURES.md) · 🇳🇱 [nl](../../nl/docs/FEATURES.md) · 🇵🇱 [pl](../../pl/docs/FEATURES.md) · 🇸🇪 [sv](../../sv/docs/FEATURES.md) · 🇳🇴 [no](../../no/docs/FEATURES.md) · 🇩🇰 [da](../../da/docs/FEATURES.md) · 🇫🇮 [fi](../../fi/docs/FEATURES.md) · 🇵🇹 [pt](../../pt/docs/FEATURES.md) · 🇷🇴 [ro](../../ro/docs/FEATURES.md) · 🇭🇺 [hu](../../hu/docs/FEATURES.md) · 🇧🇬 [bg](../../bg/docs/FEATURES.md) · 🇸🇰 [sk](../../sk/docs/FEATURES.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FEATURES.md) · 🇮🇱 [he](../../he/docs/FEATURES.md) · 🇵🇭 [phi](../../phi/docs/FEATURES.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FEATURES.md)
+
+---
+
+Visual guide to every section of the OmniRoute dashboard.
+
+---
+
+## 🔌 Providers
+
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
+
+
+
+---
+
+## 🎨 Combos
+
+Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
+
+
+
+---
+
+## 📊 Analytics
+
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
+
+
+
+---
+
+## 🏥 System Health
+
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+
+
+
+---
+
+## 🔧 Translator Playground
+
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
+
+
+
+---
+
+## 🎮 Model Playground _(v2.0.9+)_
+
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
+
+---
+
+## 🎨 Themes _(v2.0.5+)_
+
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
+
+## ⚙️ Settings
+
+Comprehensive settings panel with tabs:
+
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning
+- **Advanced** — Configuration overrides
+
+
+
+---
+
+## 🔧 CLI Tools
+
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
+
+
+
+---
+
+## 🤖 CLI Agents _(v2.0.11+)_
+
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
+
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
+
+---
+
+## 🖼️ Media _(v2.0.3+)_
+
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
+
+## 📝 Request Logs
+
+Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
+
+
+
+---
+
+## 🌐 API Endpoint
+
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
+
+
+
+---
+
+## 🔑 API Key Management
+
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
+
+---
+
+## 📋 Audit Log
+
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
+
+---
+
+## 🖥️ Desktop Application
+
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
+
+Key features:
+
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
+
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.
diff --git a/docs/i18n/th/README.md b/docs/i18n/th/README.md
index 1ffdce9b1b..73fa7269fd 100644
--- a/docs/i18n/th/README.md
+++ b/docs/i18n/th/README.md
@@ -1,24 +1,94 @@
-omniroute.online
-
-
- # 🚀 OmniRoute — เกตเวย์ AI ฟรี
+# 🚀 OmniRoute — The Free AI Gateway (ไทย)
-### อย่าหยุดเขียนโค้ด การกำหนดเส้นทางอัจฉริยะไปยัง **โมเดล AI ฟรีและราคาประหยัด** พร้อมทางเลือกสำรองอัตโนมัติ
-
-_พร็อกซี API สากลของคุณ — จุดสิ้นสุดเดียว ผู้ให้บริการมากกว่า 36 ราย เวลาหยุดทำงานเป็นศูนย์_
-
-**เสร็จสิ้นการแชท • การฝัง • การสร้างภาพ • เสียง • การจัดอันดับใหม่ • TypeScript 100%**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 ผู้ให้บริการ AI ฟรีสำหรับตัวแทนการเขียนโค้ดที่คุณชื่นชอบ
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_เชื่อมต่อเครื่องมือ IDE หรือ CLI ที่ขับเคลื่อนด้วย AI ผ่าน OmniRoute — เกตเวย์ API ฟรีสำหรับการเข้ารหัสไม่จำกัด_
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+` tags no longer leak to clients in SSE streaming responses (#585) |
+| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with per-provider/account quota enforcement, idempotency, SHA-256 storage, and optional GitHub issue reporting |
+| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG → generic fallback chain |
+| 🔄 **Model Auto-Sync** | 24h scheduler and manual UI toggle to sync model lists for built-in and custom OpenAI-compatible providers |
+| 🌐 **OpenCode Zen/Go** | Two new providers from @kang-heewon via PR #530: free tier + subscription tier via `OpencodeExecutor` |
+| 🐛 **Gemini CLI OAuth** | Actionable error when `GEMINI_OAUTH_CLIENT_SECRET` is missing in Docker (was cryptic Google error) |
+| 🐛 **OpenCode config** | `saveOpenCodeConfig()` now correctly writes TOML to `XDG_CONFIG_HOME` |
+| 🐛 **Pinned model override** | `body.model` correctly set to `pinnedModel` on context-cache protection |
+| 🐛 **Codex/Claude loop** | `tool_result` blocks now converted to text to stop infinite loops |
+| 🐛 **Login redirect** | Login no longer freezes after skipping password setup |
+| 🐛 **Windows paths** | MSYS2/Git-Bash paths (`/c/...`) normalized to `C:\...` automatically |
+
+---
+
+## 🖼️ Main Dashboard
+
+
-📡 ตัวแทนทั้งหมดเชื่อมต่อผ่าน ` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**Stop wasting money and hitting limits:**
-### 🆕 What's New in v3.0.0
+- Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**OmniRoute solves this:**
+
+- ✅ **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
+- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool
---
-[](https://www.npmjs.com/package/omniroute)
-[](https://hub.docker.com/r/diegosouzapw/omniroute)
-[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
-[](https://omniroute.online)
-[](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
+## 📧 Support
-[🌐 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)
+> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.
-🌐 **Available in:** 🇺🇸 [English](../../README.md) | 🇧🇷 [Português (Brasil)](../pt-BR/README.md) | 🇪🇸 [Español](../es/README.md) | 🇫🇷 [Français](../fr/README.md) | 🇮🇹 [Italiano](../it/README.md) | 🇷🇺 [Русский](../ru/README.md) | 🇨🇳 [中文 (简体)](../zh-CN/README.md) | 🇩🇪 [Deutsch](../de/README.md) | 🇮🇳 [हिन्दी](../in/README.md) | 🇹🇭 [ไทย](../th/README.md) | 🇺🇦 [Українська](../uk-UA/README.md) | 🇸🇦 [العربية](../ar/README.md) | 🇯🇵 [日本語](../ja/README.md) | 🇻🇳 [Tiếng Việt](../vi/README.md) | 🇧🇬 [Български](../bg/README.md) | 🇩🇰 [Dansk](../da/README.md) | 🇫🇮 [Suomi](../fi/README.md) | 🇮🇱 [עברית](../he/README.md) | 🇭🇺 [Magyar](../hu/README.md) | 🇮🇩 [Bahasa Indonesia](../id/README.md) | 🇰🇷 [한국어](../ko/README.md) | 🇲🇾 [Bahasa Melayu](../ms/README.md) | 🇳🇱 [Nederlands](../nl/README.md) | 🇳🇴 [Norsk](../no/README.md) | 🇵🇹 [Português (Portugal)](../pt/README.md) | 🇷🇴 [Română](../ro/README.md) | 🇵🇱 [Polski](../pl/README.md) | 🇸🇰 [Slovenčina](../sk/README.md) | 🇸🇪 [Svenska](../sv/README.md) | 🇵🇭 [Filipino](../phi/README.md)
-
-
-
----
-
-## 🖼️
-
-
-
- # 🚀 OmniRoute — เกตเวย์ AI ฟรี
+# 🚀 OmniRoute — The Free AI Gateway (ไทย)
-### อย่าหยุดเขียนโค้ด การกำหนดเส้นทางอัจฉริยะไปยัง **โมเดล AI ฟรีและราคาประหยัด** พร้อมทางเลือกสำรองอัตโนมัติ
-
-_พร็อกซี API สากลของคุณ — จุดสิ้นสุดเดียว ผู้ให้บริการมากกว่า 36 ราย เวลาหยุดทำงานเป็นศูนย์_
-
-**เสร็จสิ้นการแชท • การฝัง • การสร้างภาพ • เสียง • การจัดอันดับใหม่ • TypeScript 100%**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 ผู้ให้บริการ AI ฟรีสำหรับตัวแทนการเขียนโค้ดที่คุณชื่นชอบ
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_เชื่อมต่อเครื่องมือ IDE หรือ CLI ที่ขับเคลื่อนด้วย AI ผ่าน OmniRoute — เกตเวย์ API ฟรีสำหรับการเข้ารหัสไม่จำกัด_
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+
+
+[](https://www.npmjs.com/package/omniroute)
+[](https://www.npmjs.com/package/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
+[](https://omniroute.online)
+[](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)
+
+
+
+🌐 **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)
+
+---
+
+## 🆕 What's New in v3.0.0
+
+> **Upgrading from v2.9.5?** — See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes.
+
+| Area | Change |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection remediation |
+| ✅ **Route Validation** | All 176 API routes now validated with Zod schemas + `validateBody()` — CI `check:route-validation:t06` passes |
+| 🐛 **omniModel Tag Leak** | Internal `
+
+
+
+---
+
+## 📸 Dashboard Preview
+
+
+
+
+
+---
+
+### 🤖 Free AI Provider for your favorite coding agents
+
+_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._
Click to see dashboard screenshots
+ +| Page | Screenshot | +| -------------- | ------------------------------------------------- | +| **Providers** |  | +| **Combos** |  | +| **Analytics** |  | +| **Health** |  | +| **Translator** |  | +| **Settings** |  | +| **CLI Tools** |  | +| **Usage Logs** |  | +| **Endpoints** |  | + +|
-
+
OpenClaw @@ -92,113 +162,52 @@ _เชื่อมต่อเครื่องมือ IDE หรือ CLI |
http://localhost:20128/v1 หรือ http://cloud.omniroute.online/v1 — การกำหนดค่าเดียว โมเดลไม่จำกัด และ โควต้า
+📡 All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 — one config, unlimited models and quota
---
-### 🆕 What's New in v3.0.0
+## 🤔 Why OmniRoute?
-| Area | Change |
-| ------------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal ` Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `
-
-
-
----
-
-## 📸
-
-
-
-
-
----
-
-## 🤔 ทำไมต้อง OmniRoute?
-
-**หยุดเสียเงินและจำกัดขีดจำกัด:**
-
-- ...
- -| # | # | -| ----- | ---------------------------------------- | -| **1** |  | -| **2** |  | -| **3** |  | -| **4** |  | -| **5** |  | -| **6** |  | -| **7** |  | -| **8** |  | -| **9** |  | - - โควต้าการสมัครจะหมดอายุโดยไม่ได้ใช้ทุกเดือน
-- การจำกัดอัตราจะทำให้คุณไม่สามารถเขียนโค้ดกลางคันได้
-- API ราคาแพง ($20-50/เดือนต่อผู้ให้บริการ)
-- การสลับระหว่างผู้ให้บริการด้วยตนเอง
-
-**OmniRoute แก้ปัญหานี้:**
-
-- ✅ **เพิ่มการสมัครรับข้อมูลสูงสุด** - ติดตามโควต้า ใช้ทุกบิตก่อนรีเซ็ต
-- ✅ **ทางเลือกสำรองอัตโนมัติ** - การสมัครสมาชิก → คีย์ API → ราคาถูก → ฟรี ไม่มีการหยุดทำงาน
-- ✅ **หลายบัญชี** - หมุนเวียนระหว่างบัญชีต่อผู้ให้บริการ
-- ✅ **สากล** - ใช้งานได้กับ Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw และเครื่องมือ CLI ใดๆ
-
----
-
-## 📧 สนับสนุน
-
-> 💌 **เข้าร่วมชุมชนของเรา!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — รับความช่วยเหลือ แบ่งปันเคล็ดลับ และติดตามข่าวสารล่าสุด
-
-- **เว็บไซต์**: [omniroute.online](https://omniroute.online)
+- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **ปัญหา**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **โปรเจ็กต์ดั้งเดิม**: [9router by decolua](https://github.com/decolua/9router)
+- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 มันทำงานอย่างไร
+## 🔄 How It Works
```
┌─────────────┐
@@ -227,452 +236,453 @@ Result: Never stop coding, minimal cost
---
-## 🎯 สิ่งที่ OmniRoute แก้ปัญหาได้ — 30 คะแนนปัญหาและกรณีการใช้งานจริง
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **นักพัฒนาทุกคนที่ใช้เครื่องมือ AI ต้องเผชิญกับปัญหาเหล่านี้ทุกวัน** OmniRoute ถูกสร้างขึ้นเพื่อแก้ไขปัญหาทั้งหมด ตั้งแต่ค่าใช้จ่ายที่มากเกินไปไปจนถึงการบล็อกระดับภูมิภาค จากโฟลว์ OAuth ที่เสียหาย ไปจนถึงการทำงานของโปรโตคอลและความสามารถในการสังเกตระดับองค์กร
+> **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.
-
💸 1. "ฉันจ่ายค่าสมัครสมาชิกราคาแพงแต่ยังคงถูกขัดจังหวะด้วยขีดจำกัด"
+💸 1. "I pay for an expensive subscription but still get interrupted by limits"
-นักพัฒนาจ่ายเงิน $20–200/เดือนสำหรับ Claude Pro, Codex Pro หรือ GitHub Copilot แม้จะจ่ายเงิน โควต้าก็มีเพดาน — การใช้งาน 5 ชม. ขีดจำกัดรายสัปดาห์ หรือขีดจำกัดอัตราต่อนาที เซสชันการเข้ารหัสกลาง ผู้ให้บริการหยุดการตอบสนอง และนักพัฒนาสูญเสียความลื่นไหลและประสิทธิภาพการทำงาน +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. -**OmniRoute แก้ปัญหาอย่างไร:** +**How OmniRoute solves it:** -- **ทางเลือกสำรองอัจฉริยะ 4 ระดับ** — หากโควต้าการสมัครสมาชิกหมด จะเปลี่ยนเส้นทางไปยังคีย์ API → ราคาถูก → ฟรีโดยไม่มีการแทรกแซงด้วยตนเอง -- **การติดตามโควต้าแบบเรียลไทม์** — แสดงการใช้โทเค็นแบบเรียลไทม์พร้อมการนับถอยหลังการรีเซ็ต (5 ชม. รายวัน รายสัปดาห์) -- **การสนับสนุนหลายบัญชี** — หลายบัญชีต่อผู้ให้บริการพร้อมการหมุนเวียนอัตโนมัติ — เมื่อบัญชีหนึ่งหมด ให้สลับไปยังบัญชีถัดไป -- **คอมโบแบบกำหนดเอง** — ห่วงโซ่ทางเลือกที่ปรับแต่งได้พร้อมกลยุทธ์การปรับสมดุล 6 แบบ (เติมก่อน, ปัดเศษ, P2C, สุ่ม, ใช้น้อยที่สุด, ปรับต้นทุนให้เหมาะสม) -- **โควต้าธุรกิจ Codex** — การตรวจสอบโควต้าพื้นที่ทำงานของธุรกิจ/ทีมโดยตรงในแดชบอร์ด +- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention +- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly) +- **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 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
-` จากรุ่นอย่าง DeepSeek R1 ให้เป็น `reasoning_content` ที่ได้มาตรฐาน
-- **เอาต์พุตที่มีโครงสร้างสำหรับราศีเมถุน** — `json_schema` → `responseMimeType`/`responseSchema` การแปลงอัตโนมัติ
-- **`stream` มีค่าเริ่มต้นเป็น `false`** — สอดคล้องกับข้อกำหนด OpenAI หลีกเลี่ยง SSE ที่ไม่คาดคิดใน Python/Rust/Go SDK
+- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 67+ 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
🔌 2. "ฉันจำเป็นต้องใช้ผู้ให้บริการหลายราย แต่แต่ละรายมี API ที่แตกต่างกัน"
+🔌 2. "I need to use multiple providers but each has a different API"
-OpenAI ใช้รูปแบบหนึ่ง Claude (Anthropic) ใช้อีกรูปแบบหนึ่ง Gemini ยังใช้อีกรูปแบบหนึ่ง หากผู้พัฒนาต้องการทดสอบโมเดลจากผู้ให้บริการหลายรายหรือทางเลือกระหว่างผู้ให้บริการ พวกเขาจำเป็นต้องกำหนดค่า SDK ใหม่ เปลี่ยนตำแหน่งข้อมูล และจัดการกับรูปแบบที่เข้ากันไม่ได้ ผู้ให้บริการแบบกำหนดเอง (FriendLI, NIM) มีจุดสิ้นสุดโมเดลที่ไม่ได้มาตรฐาน +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. -**OmniRoute แก้ปัญหาอย่างไร:** +**How OmniRoute solves it:** -- **Unified Endpoint** — `http://localhost:20128/v1` เดียวทำหน้าที่เป็นพร็อกซีสำหรับผู้ให้บริการมากกว่า 36 ราย -- **การแปลรูปแบบ** — อัตโนมัติและโปร่งใส: OpenAI ↔ Claude ↔ Gemini ↔ Responses API -- **การฆ่าเชื้อการตอบสนอง** — ตัดช่องที่ไม่ได้มาตรฐาน (`x_groq`, `usage_breakdown`, `service_tier`) ที่ทำลาย OpenAI SDK v1.83+ -- **การปรับบทบาทให้เป็นมาตรฐาน** — แปลง `developer` → `system` สำหรับผู้ให้บริการที่ไม่ใช่ OpenAI `system` → `user` สำหรับ GLM/ERNIE -- **คิดการแยกแท็ก** — แยกบล็อก `
-
🌐 3. "ผู้ให้บริการ AI ของฉันบล็อกภูมิภาค/ประเทศของฉัน"
+🌐 3. "My AI provider blocks my region/country"
-ผู้ให้บริการเช่น OpenAI/Codex บล็อกการเข้าถึงจากภูมิภาคทางภูมิศาสตร์บางแห่ง ผู้ใช้ได้รับข้อผิดพลาดเช่น `unsupported_country_region_territory` ในระหว่างการเชื่อมต่อ OAuth และ API สิ่งนี้น่าหงุดหงิดเป็นพิเศษสำหรับนักพัฒนาจากประเทศกำลังพัฒนา +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. -**OmniRoute แก้ปัญหาอย่างไร:** +**How OmniRoute solves it:** -- **การกำหนดค่าพร็อกซี 3 ระดับ** — พร็อกซีที่กำหนดค่าได้ 3 ระดับ: ทั่วโลก (การรับส่งข้อมูลทั้งหมด) ต่อผู้ให้บริการ (ผู้ให้บริการรายเดียวเท่านั้น) และต่อการเชื่อมต่อ/คีย์ -- **ป้ายพร็อกซีที่ใช้รหัสสี** — ตัวบ่งชี้ภาพ: 🟢 พร็อกซีส่วนกลาง, 🟡 พร็อกซีผู้ให้บริการ, 🔵 พร็อกซีการเชื่อมต่อ แสดง IP เสมอ -- **การแลกเปลี่ยนโทเค็น OAuth ผ่านพร็อกซี** — โฟลว์ OAuth ยังต้องผ่านพร็อกซีด้วย การแก้ปัญหา `unsupported_country_region_territory` -- **การทดสอบการเชื่อมต่อผ่านพร็อกซี** — การทดสอบการเชื่อมต่อใช้พร็อกซีที่กำหนดค่าไว้ (ไม่มีการบายพาสโดยตรงอีกต่อไป) -- **รองรับ SOCKS5** — รองรับพร็อกซี SOCKS5 เต็มรูปแบบสำหรับการกำหนดเส้นทางขาออก -- **การปลอมแปลงลายนิ้วมือ TLS** — ลายนิ้วมือ TLS เหมือนเบราว์เซอร์ผ่าน `wreq-js` เพื่อเลี่ยงการตรวจจับบอท +- **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
-` prefix
-- **คอมโบฟรีเท่านั้น** — Chain `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/เดือน โดยไม่มีการหยุดทำงาน
-- **เครดิตฟรี NVIDIA NIM** — รวมเครดิตฟรี 1,000 รายการ
-- **กลยุทธ์การปรับต้นทุนให้เหมาะสม** — กลยุทธ์การกำหนดเส้นทางที่จะเลือกผู้ให้บริการที่ถูกที่สุดที่มีอยู่โดยอัตโนมัติ
+- **Free-Only Combos** — Chain `gc/gemini-3-flash → 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
🆓 4. "ฉันต้องการใช้ AI ในการเขียนโค้ด แต่ไม่มีเงิน"
+🆓 4. "I want to use AI for coding but I have no money"
-ไม่ใช่ทุกคนที่สามารถจ่าย $20–200/เดือน สำหรับการสมัครสมาชิก AI นักศึกษา นักพัฒนาจากประเทศเกิดใหม่ ผู้ที่สมัครเล่น และฟรีแลนซ์ต้องการเข้าถึงโมเดลคุณภาพโดยไม่มีค่าใช้จ่าย +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. -**OmniRoute แก้ปัญหาอย่างไร:** +**How OmniRoute solves it:** -- **ผู้ให้บริการ Tier ฟรีในตัว** — รองรับเนทิฟสำหรับผู้ให้บริการฟรี 100%: iFlow (8 รุ่นไม่จำกัด), Qwen (3 รุ่นไม่จำกัด), Kiro (Claude ฟรี), Gemini CLI (ฟรี 180K/เดือน) +- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free) - **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/
-
🔒 5. "ฉันต้องปกป้องเกตเวย์ AI ของฉันจากการเข้าถึงที่ไม่ได้รับอนุญาต"
+🔒 5. "I need to protect my AI gateway from unauthorized access"
-เมื่อเปิดเผยเกตเวย์ AI ไปยังเครือข่าย (LAN, VPS, Docker) ใครก็ตามที่มีที่อยู่จะสามารถใช้โทเค็น/โควต้าของนักพัฒนาได้ หากไม่มีการป้องกัน API ก็เสี่ยงต่อการถูกนำไปใช้ในทางที่ผิด การแทรกทันที และการละเมิด +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. -**OmniRoute แก้ปัญหาอย่างไร:** +**How OmniRoute solves it:** -- **การจัดการคีย์ API** — การสร้าง การหมุนเวียน และการกำหนดขอบเขตต่อผู้ให้บริการด้วยเพจ `/dashboard/api-manager` เฉพาะ -- **การอนุญาตระดับโมเดล** — จำกัดคีย์ API ให้กับโมเดลเฉพาะ (`openai/*` รูปแบบไวด์การ์ด) พร้อมสลับอนุญาตทั้งหมด/จำกัด -- **การป้องกันปลายทาง API** — ต้องใช้รหัสสำหรับ `/v1/models` และบล็อกผู้ให้บริการบางรายจากรายการ -- **Auth Guard + การป้องกัน CSRF** — เส้นทางแดชบอร์ดทั้งหมดที่ได้รับการป้องกันด้วยมิดเดิลแวร์ `withAuth` + โทเค็น CSRF -- **ตัวจำกัดอัตรา** — การจำกัดอัตราต่อ IP ด้วยหน้าต่างที่กำหนดค่าได้ -- **การกรอง IP** — รายการที่อนุญาต/รายการบล็อกสำหรับการควบคุมการเข้าถึง -- **Prompt Injection Guard** — การฆ่าเชื้อจากรูปแบบการแจ้งเตือนที่เป็นอันตราย -- **การเข้ารหัส AES-256-GCM** — ข้อมูลประจำตัวได้รับการเข้ารหัสเมื่อไม่ได้ใช้งาน +- **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. "ผู้ให้บริการของฉันหยุดทำงานและฉันสูญเสียขั้นตอนการเขียนโค้ด"
+🛑 6. "My provider went down and I lost my coding flow"
-ผู้ให้บริการ AI อาจไม่เสถียร ส่งกลับข้อผิดพลาด 5xx หรือถึงขีดจำกัดอัตราชั่วคราว หากผู้พัฒนาขึ้นอยู่กับผู้ให้บริการรายเดียว ผู้ให้บริการเหล่านั้นจะถูกขัดจังหวะ หากไม่มีเซอร์กิตเบรกเกอร์ การลองซ้ำหลายครั้งอาจทำให้แอปพลิเคชันเสียหายได้ +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. -**OmniRoute แก้ปัญหาอย่างไร:** +**How OmniRoute solves it:** -- **เซอร์กิตเบรกเกอร์ต่อผู้ให้บริการ** — เปิด/ปิดอัตโนมัติด้วยเกณฑ์และคูลดาวน์ที่กำหนดค่าได้ (ปิด/เปิด/เปิดครึ่งหนึ่ง) -- **Exponential Backoff** — ความล่าช้าในการลองใหม่อย่างต่อเนื่อง -- **Anti-Thundering Herd** — Mutex + การป้องกันเซมาฟอร์จากพายุที่ลองใหม่พร้อมกัน -- **Combo Fallback Chains** — หากผู้ให้บริการหลักล้มเหลว จะตกผ่านห่วงโซ่โดยอัตโนมัติโดยไม่มีการแทรกแซง -- **Combo Circuit Breaker** — ปิดการใช้งานผู้ให้บริการที่ล้มเหลวภายในคอมโบเชนโดยอัตโนมัติ - | 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format | -- **แดชบอร์ดสุขภาพ** — การตรวจสอบสถานะการออนไลน์ สถานะของเซอร์กิตเบรกเกอร์ การล็อก สถิติแคช เวลาแฝง p50/p95/p99 +- **Circuit Breaker per-model** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks +- **Exponential Backoff** — Progressive retry delays +- **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 +- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain +- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
-
🏽 7. "การกำหนดค่าเครื่องมือ AI แต่ละรายการนั้นน่าเบื่อและซ้ำซาก"
+🔧 7. "Configuring each AI tool is tedious and repetitive"
-นักพัฒนาใช้ Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... เครื่องมือแต่ละอันจำเป็นต้องมีการกำหนดค่าที่แตกต่างกัน (จุดสิ้นสุด API, คีย์, โมเดล) การกำหนดค่าใหม่เมื่อเปลี่ยนผู้ให้บริการหรือรุ่นเป็นการเสียเวลา +Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time. -**OmniRoute แก้ปัญหาอย่างไร:** +**How OmniRoute solves it:** -- **แดชบอร์ดเครื่องมือ CLI** — หน้าเฉพาะพร้อมการตั้งค่าเพียงคลิกเดียวสำหรับ Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline -- **GitHub Copilot Config Generator** — สร้าง `chatLanguageModels.json` สำหรับโค้ด VS พร้อมการเลือกรุ่นจำนวนมาก -- **ตัวช่วยสร้างการเริ่มต้นใช้งาน** — คำแนะนำการตั้งค่า 4 ขั้นตอนสำหรับผู้ใช้ครั้งแรก -- **จุดสิ้นสุดเดียว ทุกรุ่น** — กำหนดค่า `http://localhost:20128/v1` ครั้งเดียว เข้าถึงผู้ให้บริการมากกว่า 36 ราย +- **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 67+ providers
-
🔑 8. "การจัดการโทเค็น OAuth จากผู้ให้บริการหลายรายนั้นช่างเลวร้าย"
+🔑 8. "Managing OAuth tokens from multiple providers is hell"
-Claude Code, Codex, Gemini CLI, Copilot — ทั้งหมดใช้ OAuth 2.0 โดยมีโทเค็นที่กำลังจะหมดอายุ นักพัฒนาจำเป็นต้องตรวจสอบความถูกต้องอีกครั้งอย่างต่อเนื่อง จัดการกับ `client_secret is missing`, `redirect_uri_mismatch` และความล้มเหลวบนเซิร์ฟเวอร์ระยะไกล OAuth บน LAN/VPS เป็นปัญหาอย่างยิ่ง +Claude Code, Codex, Gemini CLI, 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. -**OmniRoute แก้ปัญหาอย่างไร:** +**How OmniRoute solves it:** -- **รีเฟรชโทเค็นอัตโนมัติ** — โทเค็น OAuth รีเฟรชในพื้นหลังก่อนหมดอายุ -- **OAuth 2.0 (PKCE) ในตัว** — โฟลว์อัตโนมัติสำหรับ Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow -- **OAuth หลายบัญชี** — หลายบัญชีต่อผู้ให้บริการผ่านการดึงโทเค็น JWT/ID -- **OAuth LAN/Remote Fix** — การตรวจจับ IP ส่วนตัวสำหรับ `redirect_uri` + โหมด URL แบบแมนนวลสำหรับเซิร์ฟเวอร์ระยะไกล -- **OAuth ที่อยู่เบื้องหลัง Nginx** — ใช้ `window.location.origin` สำหรับความเข้ากันได้ของ Reverse Proxy -- **คู่มือ OAuth ระยะไกล** — คำแนะนำทีละขั้นตอนสำหรับข้อมูลรับรอง Google Cloud บน VPS/Docker +- **Auto Token Refresh** — OAuth tokens refresh in background before expiration +- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow +- **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. "ฉันไม่รู้ว่าใช้เงินไปเท่าไหร่หรือที่ไหน"
+📊 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. -**OmniRoute แก้ปัญหาอย่างไร:** +**How OmniRoute solves it:** -- **แดชบอร์ดการวิเคราะห์ต้นทุน** — การติดตามต้นทุนต่อโทเค็นและการจัดการงบประมาณต่อผู้ให้บริการ -- **ขีดจำกัดงบประมาณต่อระดับ** — เพดานการใช้จ่ายต่อระดับที่ทำให้เกิดทางเลือกสำรองอัตโนมัติ -- **การกำหนดค่าราคาต่อรุ่น** — ราคาที่กำหนดค่าได้ต่อรุ่น -- **สถิติการใช้งานต่อคีย์ API** — จำนวนคำขอและการประทับเวลาที่ใช้ล่าสุดต่อคีย์ -- **แดชบอร์ดการวิเคราะห์** — การ์ดสถิติ แผนภูมิการใช้งานโมเดล ตารางผู้ให้บริการพร้อมอัตราความสำเร็จและเวลาแฝง +- **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. "ฉันไม่สามารถวินิจฉัยข้อผิดพลาดและปัญหาในการเรียก AI ได้"
+🐛 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. -**OmniRoute แก้ปัญหาอย่างไร:** +**How OmniRoute solves it:** -- **Unified Logs Dashboard** — 4 แท็บ: บันทึกคำขอ, บันทึกพร็อกซี, บันทึกการตรวจสอบ, คอนโซล -- **โปรแกรมดูบันทึกคอนโซล** — โปรแกรมดูสไตล์เทอร์มินัลแบบเรียลไทม์พร้อมระดับรหัสสี เลื่อนอัตโนมัติ ค้นหา ตัวกรอง -- **SQLite Proxy Logs** — บันทึกถาวรที่รอดจากการรีสตาร์ทเซิร์ฟเวอร์ -- **Translator Playground** — โหมดแก้ไขข้อบกพร่อง 4 โหมด: Playground (การแปลรูปแบบ), Chat Tester (ไป-กลับ), ม้านั่งทดสอบ (เป็นกลุ่ม), Live Monitor (เรียลไทม์) -- **ร้องขอการตรวจวัดทางไกล** — p50/p95/p99 latency + การติดตาม X-Request-Id -- **การบันทึกตามไฟล์พร้อมการหมุน** — ตัวสกัดกั้นคอนโซลจะบันทึกทุกอย่างไปยังบันทึก JSON ด้วยการหมุนตามขนาด +- **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 Proxy Logs** — Persistent logs that survive server restarts +- **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 Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation +- **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. "การปรับใช้และการบำรุงรักษาเกตเวย์นั้นซับซ้อน"
+🏗️ 11. "Deploying and maintaining the gateway is complex"
-การติดตั้ง การกำหนดค่า และการบำรุงรักษาพร็อกซี AI ในสภาพแวดล้อมที่แตกต่างกัน (ภายในเครื่อง, VPS, Docker, คลาวด์) ต้องใช้แรงงานมาก ปัญหาเช่นเส้นทางฮาร์ดโค้ด `EACCES` บนไดเร็กทอรี ข้อขัดแย้งของพอร์ต และการสร้างข้ามแพลตฟอร์มจะเพิ่มแรงเสียดทาน +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. -**OmniRoute แก้ปัญหาอย่างไร:** +**How OmniRoute solves it:** -- **การติดตั้งทั่วโลก npm** — `npm install -g omniroute && omniroute` — เสร็จแล้ว -- **นักเทียบท่าหลายแพลตฟอร์ม** — AMD64 + ARM64 ดั้งเดิม (Apple Silicon, AWS Graviton, Raspberry Pi) -- **โปรไฟล์นักเทียบท่าเขียน** — `base` (ไม่มีเครื่องมือ CLI) และ `cli` (พร้อม Claude Code, Codex, OpenClaw) -- **แอป Electron Desktop** — แอปเนทีฟสำหรับ Windows/macOS/Linux พร้อมถาดระบบ เริ่มอัตโนมัติ โหมดออฟไลน์ -- **โหมดแยกพอร์ต** — API และแดชบอร์ดบนพอร์ตแยกกันสำหรับสถานการณ์ขั้นสูง (พร็อกซีย้อนกลับ เครือข่ายคอนเทนเนอร์) -- **Cloud Sync** — กำหนดค่าการซิงโครไนซ์ระหว่างอุปกรณ์ผ่าน Cloudflare Workers -- **การสำรองข้อมูล DB** — การสำรองข้อมูล กู้คืน ส่งออก และนำเข้าการตั้งค่าทั้งหมดโดยอัตโนมัติ +- **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
-
🌍 12. "อินเทอร์เฟซเป็นภาษาอังกฤษเท่านั้น และทีมของฉันไม่พูดภาษาอังกฤษ"
+🌍 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. -**OmniRoute แก้ปัญหาอย่างไร:** +**How OmniRoute solves it:** -- **แดชบอร์ด i18n — 30 ภาษา** — ทั้งหมด 500+ คีย์ที่แปล รวมถึงอารบิก บัลแกเรีย เดนมาร์ก เยอรมัน สเปน ฟินแลนด์ ฝรั่งเศส ฮิบรู ฮินดี ฮังการี อินโดนีเซีย อิตาลี ญี่ปุ่น เกาหลี มาเลย์ ดัตช์ นอร์เวย์ โปแลนด์ โปรตุเกส (PT/BR) โรมาเนีย รัสเซีย สโลวาเกีย สวีเดน ไทย ยูเครน เวียดนาม จีน ฟิลิปปินส์ อังกฤษ -- **รองรับ RTL** — รองรับภาษาอาหรับและฮีบรูจากขวาไปซ้าย -- **README หลายภาษา** — การแปลเอกสารฉบับสมบูรณ์ 30 รายการ -- **ตัวเลือกภาษา** — ไอคอนลูกโลกในส่วนหัวสำหรับการสลับแบบเรียลไทม์ +- **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. "ฉันต้องการมากกว่าการแชท — ฉันต้องการการฝัง รูปภาพ เสียง"
+🔄 13. "I need more than chat — I need embeddings, images, audio"
-AI ไม่ใช่แค่การแชทให้เสร็จสิ้นเท่านั้น นักพัฒนาจำเป็นต้องสร้างภาพ ถอดเสียง สร้างการฝังสำหรับ RAG จัดอันดับเอกสารใหม่ และกลั่นกรองเนื้อหา API แต่ละรายการมีจุดสิ้นสุดและรูปแบบที่แตกต่างกัน +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. -**OmniRoute แก้ปัญหาอย่างไร:** +**How OmniRoute solves it:** -- **การฝัง** — `/v1/embeddings` พร้อมผู้ให้บริการ 6 รายและรุ่น 9+ -- **การสร้างภาพ** — `/v1/images/generations` พร้อมผู้ให้บริการ 10 รายและโมเดลมากกว่า 20 รุ่น (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI) -- **ข้อความเป็นวิดีโอ** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) และ SD WebUI -- **ข้อความเป็นเพลง** — `/v1/music/generations` — ComfyUI (เปิดเสียงที่เสถียร, MusicGen) -- **การถอดเสียง** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3 -- **การอ่านออกเสียงข้อความ** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, Inworld, Cartesia, PlayHT และผู้ให้บริการที่มีอยู่ -- **การกลั่นกรอง** — `/v1/moderations` — การตรวจสอบความปลอดภัยของเนื้อหา -- **การจัดอันดับใหม่** — `/v1/rerank` — การจัดอันดับความเกี่ยวข้องของเอกสารใหม่ -- **Responses API** — รองรับ `/v1/responses` เต็มรูปแบบสำหรับ Codex +- **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. "ฉันไม่มีวิธีทดสอบและเปรียบเทียบคุณภาพระหว่างรุ่นต่างๆ"
+🧪 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. -**OmniRoute แก้ปัญหาอย่างไร:** +**How OmniRoute solves it:** -- **การประเมิน LLM** — การทดสอบชุดทองพร้อมเคสที่โหลดไว้ล่วงหน้า 10 เคส ซึ่งครอบคลุมการทักทาย คณิตศาสตร์ ภูมิศาสตร์ การสร้างโค้ด การปฏิบัติตาม JSON การแปล การมาร์กดาวน์ การปฏิเสธด้านความปลอดภัย -- **4 กลยุทธ์การจับคู่** — `exact`, `contains`, `regex`, `custom` (ฟังก์ชัน JS) -- **ม้านั่งทดสอบสนามเด็กเล่นสำหรับนักแปล** — การทดสอบเป็นกลุ่มที่มีอินพุตหลายอินพุตและเอาต์พุตที่คาดหวัง การเปรียบเทียบข้ามผู้ให้บริการ -- **เครื่องมือทดสอบการแชท** — ไป-กลับเต็มรูปแบบพร้อมการเรนเดอร์การตอบสนองด้วยภาพ -- **Live Monitor** — สตรีมคำขอทั้งหมดที่ไหลผ่านพร็อกซีแบบเรียลไทม์ +- **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. "ฉันต้องปรับขนาดโดยไม่สูญเสียประสิทธิภาพ"
+📈 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. -**OmniRoute แก้ปัญหาอย่างไร:** +**How OmniRoute solves it:** -- **Semantic Cache** — แคชสองชั้น (ลายเซ็น + ความหมาย) ช่วยลดต้นทุนและเวลาแฝง -- **คำขอ Idempotency** — หน้าต่างการขจัดข้อมูลซ้ำซ้อน 5 วินาทีสำหรับคำขอที่เหมือนกัน -- **การตรวจจับขีดจำกัดอัตรา** — RPM ต่อผู้ให้บริการ ช่องว่างขั้นต่ำ และการติดตามพร้อมกันสูงสุด -- **ขีดจำกัดอัตราที่แก้ไขได้** — ค่าเริ่มต้นที่กำหนดค่าได้ในการตั้งค่า → ความยืดหยุ่นด้วยความคงอยู่ -- **แคชการตรวจสอบคีย์ API** — แคช 3 ระดับสำหรับประสิทธิภาพการผลิต -- **แดชบอร์ดสุขภาพพร้อมการวัดและส่งข้อมูลทางไกล** — เวลาแฝง p50/p95/p99 สถิติแคช เวลาทำงาน +- **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 +- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence +- **API Key Validation Cache** — 3-tier cache for production performance +- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
-
🤖 16. "ฉันต้องการควบคุมพฤติกรรมของโมเดลทั่วโลก"
+🤖 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. -**OmniRoute แก้ปัญหาอย่างไร:** +**How OmniRoute solves it:** -- **การแจ้งพร้อมท์ของระบบ** — พร้อมท์ทั่วโลกนำไปใช้กับคำขอทั้งหมด -- **การตรวจสอบงบประมาณการคิด** — การควบคุมการจัดสรรโทเค็นการให้เหตุผลต่อคำขอ (การส่งผ่าน, อัตโนมัติ, กำหนดเอง, การปรับตัว) -- **6 กลยุทธ์การกำหนดเส้นทาง** — กลยุทธ์ระดับโลกที่กำหนดวิธีกระจายคำขอ -- **Wildcard Router** — รูปแบบ `provider/*` จะกำหนดเส้นทางแบบไดนามิกไปยังผู้ให้บริการใดๆ -- **Combo Enable/Disable Toggle** — สลับคอมโบได้โดยตรงจากแดชบอร์ด -- **สลับผู้ให้บริการ** — เปิด/ปิดการเชื่อมต่อทั้งหมดสำหรับผู้ให้บริการได้ด้วยคลิกเดียว -- **ผู้ให้บริการที่ถูกบล็อก** — ยกเว้นผู้ให้บริการบางรายจากรายการ `/v1/models` +- **System Prompt Injection** — Global prompt applied to all requests +- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive) +- **6 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 +- **Provider Toggle** — Enable/disable all connections for a provider with one click +- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
-
🧰 17. "ฉันต้องการเครื่องมือ MCP เนื่องจากความสามารถด้านผลิตภัณฑ์ระดับเฟิร์สคลาส"
+🧰 17. "I need MCP tools as first-class product capabilities"
-เกตเวย์ AI จำนวนมากเปิดเผย MCP เป็นเพียงรายละเอียดการใช้งานที่ซ่อนอยู่เท่านั้น ทีมจำเป็นต้องมีชั้นการปฏิบัติงานที่มองเห็นได้และจัดการได้ +Many AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer. -**OmniRoute แก้ปัญหาอย่างไร:** +**How OmniRoute solves it:** -- MCP ปรากฏในการนำทางแดชบอร์ดและแท็บโปรโตคอลปลายทาง -- หน้าการจัดการ MCP เฉพาะพร้อมกระบวนการ เครื่องมือ ขอบเขต และการตรวจสอบ -- การเริ่มต้นอย่างรวดเร็วในตัวสำหรับ `omniroute --mcp` และการเริ่มต้นใช้งานไคลเอ็นต์ +- 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. "ฉันต้องการการประสาน A2A พร้อมเส้นทางงานการซิงค์ + สตรีม"
+🧠 18. "I need A2A orchestration with sync + stream task paths"
-เวิร์กโฟลว์ของตัวแทนต้องการทั้งการตอบกลับโดยตรงและการดำเนินการสตรีมที่ใช้เวลานานพร้อมการควบคุมวงจรชีวิต +Agent workflows need both direct replies and long-running streamed execution with lifecycle control. -**OmniRoute แก้ปัญหาอย่างไร:** +**How OmniRoute solves it:** -- จุดสิ้นสุด A2A JSON-RPC (`POST /a2a`) พร้อม `message/send` และ `message/stream` -- การสตรีม SSE พร้อมการเผยแพร่สถานะเทอร์มินัล -- API วงจรชีวิตของงานสำหรับ `tasks/get` และ `tasks/cancel` +- 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. "ฉันต้องการความสมบูรณ์ของกระบวนการ MCP ที่แท้จริง ไม่ใช่สถานะที่เดาได้"
+🛰️ 19. "I need real MCP process health, not guessed status"
-ทีมปฏิบัติการจำเป็นต้องทราบว่า MCP ยังคงอยู่จริงหรือไม่ ไม่ใช่แค่ว่า API สามารถเข้าถึงได้หรือไม่ +Operational teams need to know if MCP is actually alive, not just whether an API is reachable. -**OmniRoute แก้ปัญหาอย่างไร:** +**How OmniRoute solves it:** -- ไฟล์ฮาร์ทบีทรันไทม์พร้อม PID, การประทับเวลา, การขนส่ง, จำนวนเครื่องมือ และโหมดขอบเขต -- API สถานะ MCP รวมการเต้นของหัวใจ + กิจกรรมล่าสุด -- การ์ดสถานะ UI สำหรับความสดใหม่ของกระบวนการ/สถานะการออนไลน์/การเต้นของหัวใจ +- 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. "ฉันต้องการการทำงานของเครื่องมือ MCP ที่ตรวจสอบได้"
+📋 20. "I need auditable MCP tool execution"
-เมื่อเครื่องมือเปลี่ยนแปลงการกำหนดค่าหรือทริกเกอร์การดำเนินการ ทีมจำเป็นต้องมีการตรวจสอบย้อนกลับทางนิติเวช +When tools mutate config or trigger ops actions, teams need forensic traceability. -**OmniRoute แก้ปัญหาอย่างไร:** +**How OmniRoute solves it:** -- การบันทึกการตรวจสอบที่ได้รับการสนับสนุนจาก SQLite สำหรับการเรียกใช้เครื่องมือ MCP -- กรองตามเครื่องมือ ความสำเร็จ/ความล้มเหลว คีย์ API และการแบ่งหน้า -- ตารางการตรวจสอบแดชบอร์ด + จุดสิ้นสุดสถิติสำหรับระบบอัตโนมัติ +- 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. "ฉันต้องการสิทธิ์ MCP ที่กำหนดขอบเขตต่อการบูรณาการ"
+🔐 21. "I need scoped MCP permissions per integration"
-ไคลเอนต์ที่แตกต่างกันควรมีสิทธิ์เข้าถึงหมวดหมู่เครื่องมือน้อยที่สุด +Different clients should have least-privilege access to tool categories. -**OmniRoute แก้ปัญหาอย่างไร:** +**How OmniRoute solves it:** -- ขอบเขต MCP แบบละเอียด 9 แบบสำหรับการเข้าถึงเครื่องมือที่ควบคุม -- การบังคับใช้ขอบเขตและการมองเห็นใน UI การจัดการ MCP -- ท่าทางเริ่มต้นที่ปลอดภัยสำหรับเครื่องมือในการปฏิบัติงาน +- 9 granular MCP scopes for controlled tool access +- Scope enforcement and visibility in MCP management UI +- Safe default posture for operational tooling
-
⚙️ 22. "ฉันต้องการการควบคุมการปฏิบัติงานโดยไม่ต้องปรับใช้ใหม่"
+⚙️ 22. "I need operational controls without redeploying"
-ทีมต้องการการเปลี่ยนแปลงรันไทม์อย่างรวดเร็วระหว่างเหตุการณ์หรือเหตุการณ์ต้นทุน +Teams need quick runtime changes during incidents or cost events. -**OmniRoute แก้ปัญหาอย่างไร:** +**How OmniRoute solves it:** -- สลับการเปิดใช้งานคอมโบโดยตรงจากแดชบอร์ด MCP -- ใช้โปรไฟล์ความยืดหยุ่นจากชุดนโยบายที่กำหนดไว้ล่วงหน้า -- รีเซ็ตสถานะเซอร์กิตเบรกเกอร์จากแผงการทำงานเดียวกัน +- Switch combo activation directly from MCP dashboard +- Apply resilience profiles from pre-defined policy packs +- Reset circuit breaker state from the same operations panel
-
🔄 23. "ฉันต้องการการมองเห็นและการยกเลิกวงจรการใช้งาน A2A แบบสด"
+🔄 23. "I need live A2A task lifecycle visibility and cancellation"
-หากไม่มีการมองเห็นวงจรการใช้งาน เหตุการณ์ของงานจะยากต่อการคัดแยก +Without lifecycle visibility, task incidents become hard to triage. -**OmniRoute แก้ปัญหาอย่างไร:** +**How OmniRoute solves it:** -- รายการงาน/การกรองตามสถานะ/ทักษะพร้อมการแบ่งหน้า -- เจาะลึกข้อมูลเมตาของงาน เหตุการณ์ และสิ่งประดิษฐ์ -- จุดสิ้นสุดการยกเลิกงานและการดำเนินการ UI พร้อมการยืนยัน +- 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. "ฉันต้องการตัววัดสตรีมที่ใช้งานอยู่สำหรับโหลด A2A"
+🌊 24. "I need active stream metrics for A2A load"
-เวิร์กโฟลว์การสตรีมจำเป็นต้องมีข้อมูลเชิงลึกในการดำเนินงานเกี่ยวกับการทำงานพร้อมกันและการเชื่อมต่อแบบสด +Streaming workflows require operational insight into concurrency and live connections. -**OmniRoute แก้ปัญหาอย่างไร:** +**How OmniRoute solves it:** -- ตัวนับสตรีมที่ใช้งานรวมอยู่ในสถานะ A2A -- การประทับเวลางานล่าสุดและการนับต่อรัฐ -- การ์ดแดชบอร์ด A2A สำหรับการตรวจสอบการปฏิบัติงานแบบเรียลไทม์ +- Active stream counters integrated into A2A status +- Last task timestamp and per-state counts +- A2A dashboard cards for real-time ops monitoring
-
🪪 25. "ฉันต้องการการค้นพบเอเจนต์มาตรฐานสำหรับลูกค้า"
+🪪 25. "I need standard agent discovery for clients"
-ไคลเอนต์และผู้ควบคุมภายนอกต้องการเมตาดาต้าที่เครื่องอ่านได้เพื่อการเริ่มต้นใช้งาน +External clients and orchestrators need machine-readable metadata for onboarding. -**OmniRoute แก้ปัญหาอย่างไร:** +**How OmniRoute solves it:** -- บัตรตัวแทนเปิดเผยที่ `/.well-known/agent.json` -- ความสามารถและทักษะที่แสดงใน UI การจัดการ -- API สถานะ A2A รวมถึงข้อมูลเมตาการค้นพบสำหรับระบบอัตโนมัติ +- Agent Card exposed at `/.well-known/agent.json` +- Capabilities and skills shown in management UI +- A2A status API includes discovery metadata for automation
-
🧭 26. "ฉันต้องการการค้นพบโปรโตคอลในผลิตภัณฑ์ UX"
+🧭 26. "I need protocol discoverability in the product UX"
-หากผู้ใช้ไม่พบพื้นผิวของโปรโตคอล การนำไปใช้และคุณภาพการสนับสนุนจะลดลง +If users cannot discover protocol surfaces, adoption and support quality drop. -**OmniRoute แก้ปัญหาอย่างไร:** +**How OmniRoute solves it:** -- รายการแถบด้านข้างสำหรับ MCP และ A2A -- แท็บโปรโตคอลหน้าปลายทางพร้อมการเริ่มต้นและสถานะอย่างรวดเร็ว -- ลิงก์จากภาพรวมไปยังแดชบอร์ดการจัดการเฉพาะ +- 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. "ฉันต้องการการตรวจสอบโปรโตคอลแบบ end-to-end กับไคลเอนต์จริง"
+🧪 27. "I need end-to-end protocol validation with real clients"
-การทดสอบจำลองไม่เพียงพอที่จะตรวจสอบความเข้ากันได้ของโปรโตคอลก่อนเผยแพร่ +Mock tests are not enough to validate protocol compatibility before release. -**OmniRoute แก้ปัญหาอย่างไร:** +**How OmniRoute solves it:** -- ชุด E2E ที่บูทแอปและใช้การขนส่งไคลเอนต์ MCP SDK จริง -- ไคลเอนต์ A2A ทดสอบการค้นหา ส่ง สตรีม รับ และยกเลิกโฟลว์ -- ยืนยันการตรวจสอบข้ามกับการตรวจสอบ MCP และ API งาน A2A +- 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. "ฉันต้องการความสามารถในการสังเกตแบบรวมศูนย์ในทุกอินเทอร์เฟซ"
+📡 28. "I need unified observability across all interfaces"
-การแยกความสามารถในการสังเกตตามโปรโตคอลทำให้เกิดจุดบอดและ MTTR ที่ยาวขึ้น +Splitting observability by protocol creates blind spots and longer MTTR. -**OmniRoute แก้ปัญหาอย่างไร:** +**How OmniRoute solves it:** -- แดชบอร์ด/บันทึก/การวิเคราะห์แบบรวมในผลิตภัณฑ์เดียว -- สุขภาพ + การตรวจสอบ + ขอการตรวจวัดทางไกลผ่านเลเยอร์ OpenAI, MCP และ A2A -- API การดำเนินงานสำหรับสถานะและระบบอัตโนมัติ +- Unified dashboards/logs/analytics in one product +- Health + audit + request telemetry across OpenAI, MCP, and A2A layers +- Operational APIs for status and automation
-
💼 29. "ฉันต้องการหนึ่งรันไทม์สำหรับพร็อกซี + เครื่องมือ + การจัดการเอเจนต์"
+💼 29. "I need one runtime for proxy + tools + agent orchestration"
-การใช้บริการแยกกันจำนวนมากจะเพิ่มต้นทุนการดำเนินงานและโหมดความล้มเหลว +Running many separate services increases operational cost and failure modes. -**OmniRoute แก้ปัญหาอย่างไร:** +**How OmniRoute solves it:** -- พร็อกซีที่เข้ากันได้กับ OpenAI, เซิร์ฟเวอร์ MCP และเซิร์ฟเวอร์ A2A ในสแต็กเดียว -- การรับรองความถูกต้องที่ใช้ร่วมกัน ความยืดหยุ่น การจัดเก็บข้อมูล และความสามารถในการสังเกต -- รูปแบบนโยบายที่สอดคล้องกันในทุกรูปแบบการโต้ตอบ +- 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
-
-### Playbook ตัวอย่าง (กรณีการใช้งานแบบรวม)
+### Example Playbooks (Integrated Use Cases)
-**Playbook A: เพิ่มการสมัครสมาชิกแบบชำระเงินให้สูงสุด + การสำรองข้อมูลราคาถูก**
+**Playbook A: Maximize paid subscription + cheap backup**
```txt
Combo: "maximize-claude"
@@ -684,7 +694,7 @@ Monthly cost: $20 + small backup spend
Outcome: higher quality, near-zero interruption
```
-**Playbook B: สแต็คการเขียนโค้ดแบบไม่มีค่าใช้จ่าย**
+**Playbook B: Zero-cost coding stack**
```txt
Combo: "free-forever"
@@ -696,7 +706,7 @@ Monthly cost: $0
Outcome: stable free coding workflow
```
-**Playbook C: ห่วงโซ่ทางเลือกที่เปิดตลอด 24 ชั่วโมงทุกวัน**
+**Playbook C: 24/7 always-on fallback chain**
```txt
Combo: "always-on"
@@ -709,65 +719,132 @@ Combo: "always-on"
Outcome: deep fallback depth for deadline-critical workloads
```
-**Playbook D: ตัวแทนดำเนินการด้วย MCP + A2A**
+**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/mcp and /dashboard/a2a
-4) Control incidents with resilience profile + task cancellation
+3) Observe via /dashboard/endpoint (MCP and A2A tabs)
+4) Toggle services via inline status controls
```
---
-## ⚡ เริ่มต้นอย่างรวดเร็ว
+## 🆓 Start Free — Zero Configuration Cost
-**1. ติดตั้งทั่วโลก:**
+> 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 **iFlow** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |
+| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |
+| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |
+| 5 | `/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).
+
+## เริ่มต้นอย่างรวดเร็ว
+
+### 1) Install and run
```bash
npm install -g omniroute
omniroute
```
-🎉 แดชบอร์ดเปิดเมื่อ `http://localhost:20128`
+> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:
+>
+> ```bash
+> pnpm install -g omniroute
+> pnpm approve-builds -g # Select all packages → approve
+> omniroute
+> ```
-| คำสั่ง | คำอธิบาย |
-| ----------------------- | -------------------------------------- |
-| `omniroute` | เริ่มเซิร์ฟเวอร์ (พอร์ตเริ่มต้น 20128) |
-| `omniroute --port 3000` | ใช้พอร์ตที่กำหนดเอง |
-| `omniroute --no-open` | อย่าเปิดเบราว์เซอร์อัตโนมัติ |
-| `omniroute --help` | แสดงความช่วยเหลือ |
+Dashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.
-**2. เชื่อมต่อผู้ให้บริการฟรี:**
+| 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 |
-แดชบอร์ด → ผู้ให้บริการ → เชื่อมต่อ **Claude Code** หรือ **Antigravity** → เข้าสู่ระบบ OAuth → เสร็จสิ้น!
+Optional split-port mode:
-**3. ใช้ในเครื่องมือ CLI ของคุณ:**
-
-```
-Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Settings:
- Endpoint: http://localhost:20128/v1
- API Key: [copy from dashboard]
- Model: if/kimi-k2-thinking
+```bash
+PORT=20128 DASHBOARD_PORT=20129 omniroute
+# API: http://localhost:20128/v1
+# Dashboard: http://localhost:20129
```
-**แค่นั้นแหละ!** เริ่มเขียนโค้ดด้วยโมเดล AI ฟรี
+### 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
+
+```txt
+Base URL: http://localhost:20128/v1
+API Key: [copy from Endpoint page]
+Model: if/kimi-k2-thinking (or any provider/model prefix)
+```
+
+Works with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.
+
+### 4) Enable and validate protocols (v2.0)
+
+**MCP (for tool-driven operations):**
+
+```bash
+omniroute --mcp
+```
+
+Then connect your MCP client over `stdio` and test tools like:
+
+- `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 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
+PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev
```
---
-## 🐳 ด็อคเกอร์
+## 🐳 Docker
-OmniRoute มีให้เป็นอิมเมจ Docker สาธารณะบน [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute)
+OmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
-**วิ่งด่วน:**
+**Quick run:**
```bash
docker run -d \
@@ -778,7 +855,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**พร้อมไฟล์สภาพแวดล้อม:**
+**With environment file:**
```bash
# Copy and edit .env first
@@ -793,7 +870,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**การใช้นักเทียบท่าเขียน:**
+**Using Docker Compose:**
```bash
# Base profile (no CLI tools)
@@ -803,255 +880,552 @@ docker compose --profile base up -d
docker compose --profile cli up -d
```
-| รูปภาพ | แท็ก | ขนาด | คำอธิบาย |
-| ------------------------ | -------- | ------ | ---------------- |
-| `diegosouzapw/omniroute` | `latest` | ~250MB | รุ่นเสถียรล่าสุด |
-| `diegosouzapw/omniroute` | `1.0.3` | ~250MB | เวอร์ชันปัจจุบัน |
+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.
+- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.
+- 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` | `1.0.3` | ~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
+### เริ่มต้นอย่างรวดเร็ว
+
```bash
-npm run electron:dev # Development mode
+# 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)
+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
-| ชั้น | ผู้ให้บริการ | ราคา | รีเซ็ตโควต้า | ดีที่สุดสำหรับ |
-| ------------------ | ---------------- | ---------------------- | ------------------- | ---------------------------- |
-| **💳 สมัครสมาชิก** | รหัสคลอดด์ (Pro) | $20/เดือน | 5 ชม. + รายสัปดาห์ | สมัครสมาชิกแล้ว |
-| | Codex (พลัส/โปร) | $20-200/เดือน | 5 ชม. + รายสัปดาห์ | ผู้ใช้ OpenAI |
-| | ราศีเมถุน CLI | **ฟรี** | 180K/เดือน + 1K/วัน | ทุกคน! |
-| | นักบิน GitHub | $10-19/เดือน | รายเดือน | ผู้ใช้ GitHub |
-| **🔑 คีย์ API** | NVIDIA NIM | **ฟรี** (1,000 เครดิต) | ครั้งเดียว | การทดสอบระดับฟรี |
-| | DeepSeek | จ่ายตามการใช้งาน | ไม่มี | ราคา/คุณภาพที่ดีที่สุด |
-| | กรอค | ฟรีเทียร์ + จ่ายเงิน | อัตราจำกัด | การอนุมานที่รวดเร็วเป็นพิเศษ |
-| | xAI (โกรก) | จ่ายตามการใช้งาน | ไม่มี | รุ่น Grok |
-| | มิสทรัล | ฟรีเทียร์ + จ่ายเงิน | อัตราจำกัด | AI ยุโรป |
-| | OpenRouter | จ่ายตามการใช้งาน | ไม่มี | โมเดลมากกว่า 100 แบบ |
-| **💰 ราคาถูก** | GLM-4.7 | $0.6/1M | ทุกวัน 10.00 น. | สำรองงบประมาณ |
-| | MiniMax M2.1 | $0.2/1M | กลิ้ง 5 ชั่วโมง | ตัวเลือกที่ถูกที่สุด |
-| | คิมิ K2 | $9/เดือน คงที่ | 10M โทเค็น/เดือน | ต้นทุนที่คาดการณ์ได้ |
-| **🆓 ฟรี** | ไอโฟลว์ | $0 | ไม่จำกัด | ฟรี 8 รุ่น |
-| | ควีน | $0 | ไม่จำกัด | ฟรี 3 รุ่น |
-| | คิโระ | $0 | ไม่จำกัด | คลอดด์ฟรี |
+| 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 |
+| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |
+| | 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** | iFlow | **$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 |
-**💡 เคล็ดลับสำหรับมืออาชีพ:** เริ่มต้นด้วย Gemini CLI (ฟรี 180,000 ต่อเดือน) + iFlow (ฟรีไม่จำกัด) คอมโบ = ค่าใช้จ่าย $0!
+> 🆕 **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
+iFlow (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
-| คุณสมบัติ | มันทำอะไร |
-| ------------------------------------ | --------------------------------------------------------------------------------- |
-| 🎯 **ทางเลือกสำรองอัจฉริยะ 4 ระดับ** | เส้นทางอัตโนมัติ: การสมัครสมาชิก → คีย์ API → ถูก → ฟรี |
-| 📊 **การติดตามโควต้าแบบเรียลไทม์** | จำนวนโทเค็นสด + รีเซ็ตการนับถอยหลังต่อผู้ให้บริการ |
-| 🔄 **แปลรูปแบบ** | OpenAI ↔ Claude ↔ ราศีเมถุน ↔ เคอร์เซอร์ ↔ Kiro ไร้รอยต่อ + การฆ่าเชื้อแบบตอบสนอง |
-| 👥 **รองรับหลายบัญชี** | หลายบัญชีต่อผู้ให้บริการพร้อมตัวเลือกที่ชาญฉลาด |
-| 🔄 **รีเฟรชโทเค็นอัตโนมัติ** | โทเค็น OAuth รีเฟรชอัตโนมัติพร้อมลองอีกครั้ง |
-| 🎨 **คอมโบแบบกำหนดเอง** | 6 กลยุทธ์: เติมก่อน, ปัดเศษ, p2c, สุ่ม, ใช้น้อยที่สุด, ปรับต้นทุนให้เหมาะสม |
-| 🧩 **โมเดลที่กำหนดเอง** | เพิ่ม ID รุ่นใด ๆ ให้กับผู้ให้บริการ |
-| 🌐 **เราเตอร์ตัวแทน** | กำหนดเส้นทางรูปแบบ `provider/*` ไปยังผู้ให้บริการใดๆ แบบไดนามิก |
-| 🧠 **คิดงบประมาณ** | โหมดส่งผ่าน, อัตโนมัติ, กำหนดเอง และแบบปรับได้สำหรับโมเดลการให้เหตุผล |
-| 🔀 **Model Aliases** | Auto-forward deprecated model IDs to current replacements (built-in + custom) |
-| ⚡ **Background Degradation** | Auto-route background tasks (titles, summaries) to cheaper models |
-| 💌 **ระบบพร้อมฉีด** | พร้อมท์ระบบสากลใช้กับคำขอทั้งหมด |
-| 📄 **API ตอบกลับ** | รองรับ OpenAI Responses API เต็มรูปแบบ (`/v1/responses`) สำหรับ Codex |
+> 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.
-### 🎵 Multi-Modal API
+### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)
-| คุณสมบัติ | มันทำอะไร |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| 🖼️ **การสร้างภาพ** | `/v1/images/generations` — ผู้ให้บริการ 4 ราย รุ่น 9+ |
-| 📐 **การฝัง** | `/v1/embeddings` — ผู้ให้บริการ 6 ราย รุ่น 9+ |
-| 🎶 **การถอดเสียง** | `/v1/audio/transcriptions` — รองรับการกระซิบ |
-| 🔊 **ข้อความเป็นคำพูด** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) |
-| 🛡️ **การกลั่นกรอง** | `/v1/moderations` — การตรวจสอบความปลอดภัยของเนื้อหา |
-| 🔀 **จัดอันดับ** | `/v1/rerank` — การจัดอันดับความเกี่ยวข้องของเอกสาร |
+| 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 |
-### 🛡️ ความยืดหยุ่นและความปลอดภัย
+### 🟢 IFLOW MODELS (Free OAuth — No Credit Card)
-| คุณสมบัติ | มันทำอะไร |
-| --------------------------------- | ---------------------------------------------------------------------------- |
-| 🔌 **เซอร์กิตเบรกเกอร์** | เปิด/ปิดอัตโนมัติต่อผู้ให้บริการพร้อมเกณฑ์ที่กำหนดค่าได้ |
-| 🛡️ **ฝูงต่อต้านฟ้าร้อง** | Mutex + ขีดจำกัดอัตราเซมาฟอร์สำหรับผู้ให้บริการคีย์ API |
-| 🧠 **แคชความหมาย** | แคชสองชั้น (ลายเซ็น + ความหมาย) ช่วยลดต้นทุน & เวลาแฝง |
-| ⚡ **ขอ Idempotency** | หน้าต่าง dedup 5s สำหรับคำขอซ้ำ |
-| 🔒 **การปลอมแปลงลายนิ้วมือ TLS** | เลี่ยงการตรวจจับบอทที่ใช้ TLS ผ่าน wreq-js |
-| 🌐 **การกรอง IP** | รายการที่อนุญาต/รายการบล็อกสำหรับการควบคุมการเข้าถึง API |
-| 📊 **ขีดจำกัดอัตราที่แก้ไขได้** | RPM ที่กำหนดค่าได้ ช่องว่างขั้นต่ำ และสูงสุดพร้อมกันที่ระดับระบบ |
-| 💾 **Rate Limit Persistence** | Learned limits survive restarts via SQLite with 60s debounce + 24h staleness |
-| 🔄 **Token Refresh Resilience** | Per-provider circuit breaker (5 fails→30min) + 30s timeout per attempt |
-| 🛡 **การป้องกันปลายทาง API** | การตรวจสอบสิทธิ์ + การบล็อกผู้ให้บริการสำหรับปลายทาง `/models` |
-| 🔒 **การมองเห็นพร็อกซี** | ป้ายรหัสสี: 🟢 ทั่วโลก 🟡 ผู้ให้บริการ 🔵 ต่อการเชื่อมต่อพร้อมจอแสดงผล IP |
-| 🌐 **การกำหนดค่าพร็อกซี 3 ระดับ** | กำหนดค่าพร็อกซีในระดับโกลบอล ต่อผู้ให้บริการ หรือต่อการเชื่อมต่อ |
+| 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 |
-### 📊 ความสามารถในการสังเกตและการวิเคราะห์
+### 🟡 QWEN MODELS (Device Code Auth)
-| คุณสมบัติ | มันทำอะไร |
-| -------------------------------- | ------------------------------------------------------------------------------ |
-| 📝 **ขอบันทึก** | โหมดแก้ไขข้อบกพร่องพร้อมบันทึกคำขอ/การตอบกลับแบบเต็ม |
-| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |
-| 💾 **บันทึกพร็อกซี SQLite** | บันทึกพร็อกซีถาวรยังคงอยู่เซิร์ฟเวอร์รีสตาร์ท |
-| 📊 **แดชบอร์ดการวิเคราะห์** | ขับเคลื่อนโดย Recharts: การ์ดสถิติ แผนภูมิการใช้งานโมเดล ตารางผู้ให้บริการ |
-| 📈 **ติดตามความคืบหน้า** | เลือกใช้กิจกรรมความคืบหน้าของ SSE สำหรับการสตรีม |
-| 🧪 **การประเมิน LLM** | การทดสอบชุดทองด้วย 4 กลยุทธ์การจับคู่ |
-| 🔍 **ขอโทรมาตร** | การรวมเวลาแฝง p50/p95/p99 + การติดตาม X-Request-Id |
-| 📋 **แดชบอร์ดบันทึก** | หน้าแท็บ 4 แบบรวม: บันทึกคำขอ บันทึกพร็อกซี บันทึกการตรวจสอบ คอนโซล |
-| 🖥️ **ผู้ดูบันทึกคอนโซล** | โปรแกรมดูสไตล์เทอร์มินัลแบบเรียลไทม์พร้อมตัวกรองระดับ การค้นหา เลื่อนอัตโนมัติ |
-| 📑 **การบันทึกตามไฟล์** | ตัวดักจับคอนโซลจับเอาต์พุตทั้งหมดไปยังไฟล์บันทึก JSON พร้อมการหมุน |
-| 🏥 **แดชบอร์ดสุขภาพ** | เวลาทำงานของระบบ, สถานะของเซอร์กิตเบรกเกอร์, การล็อกเอาต์, สถิติแคช |
-| 💰 **ติดตามต้นทุน** | การจัดการงบประมาณ + การกำหนดค่าราคาต่อรุ่น |
+| 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) |
-### ☁️ การปรับใช้และการซิงค์
+### 🟣 GEMINI CLI (Google OAuth)
-| คุณสมบัติ | มันทำอะไร |
-| ------------------------------------ | --------------------------------------------------------------------------- |
-| 💾 **คลาวด์ซิงค์** | ซิงค์การกำหนดค่าระหว่างอุปกรณ์ผ่าน Cloudflare Workers |
-| 🌐 **ปรับใช้ได้ทุกที่** | Localhost, VPS, นักเทียบท่า, พนักงาน Cloudflare |
-| 🔑 **การจัดการคีย์ API** | สร้าง หมุนเวียน และกำหนดขอบเขตคีย์ API ตามผู้ให้บริการ |
-| 🧙 **ตัวช่วยสร้างการเริ่มต้นใช้งาน** | การตั้งค่าพร้อมคำแนะนำ 4 ขั้นตอนสำหรับผู้ใช้ครั้งแรก |
-| ???? **แดชบอร์ดเครื่องมือ CLI** | คลิกเดียวกำหนดค่า Claude, Codex, Cline, OpenClaw, Kilo, Antigravity |
-| 🔄 **การสำรองฐานข้อมูล** | สำรองข้อมูล กู้คืน ส่งออก & นำเข้าอัตโนมัติสำหรับการตั้งค่าทั้งหมด |
-| 🌐 **ความเป็นสากล** | i18n เต็มรูปแบบพร้อม next-intl — รองรับภาษาอังกฤษ + โปรตุเกส (บราซิล) |
-| 🌍 **ตัวเลือกภาษา** | ไอคอนลูกโลกในส่วนหัวสำหรับการสลับภาษาแบบเรียลไทม์ (USA/🇧🇷) |
-| 🧹 **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 |
-| 📂 **ไดเรกทอรีข้อมูลที่กำหนดเอง** | `DATA_DIR` env var เพื่อแทนที่ค่าเริ่มต้น `~/.omniroute` พาธหน่วยเก็บข้อมูล |
+| Model | Prefix | Limit | Rate Limit |
+| ------------------------ | ------ | --------------------------- | ------------- |
+| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |
+| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |
+
+### ⚫ 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
+> iFlow (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 v2.0 is built as an operational platform, not just a relay proxy.
+
+### 🆕 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 Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |
+| 🤖 **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 (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) |
+| 🤝 **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** | 9 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 combo, apply resilience profiles, reset breakers from one control surface |
+
+### 🧠 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** | 6 balancing strategies + fallback chain control |
+| 🌐 **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) |
+| 💬 **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 |
+| ----------------------------------- | -------------------------------------------------------------------------------------- |
+| 🔌 **Circuit Breakers** | Per-model trip/recover with threshold controls |
+| 🎯 **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 |
+| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |
+| 🔑 **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 |
+
+### 📊 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 |
+| 📋 **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 |
+
+### ☁️ Deployment & Platform
+
+| Feature | What It Does |
+| ----------------------------- | --------------------------------------------------------- |
+| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |
+| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |
+| 💾 **Cloud Sync** | Configuration sync via cloud worker |
+| 🔄 **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 |
+
+### Feature Deep Dive
+
+#### Smart fallback with practical cost control
+
+```txt
+Combo: "my-coding-stack"
+ 1. cc/claude-opus-4-6
+ 2. nvidia/llama-3.3-70b
+ 3. glm/glm-4.7
+ 4. if/kimi-k2-thinking
+```
+
+When quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.
+
+#### 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)
+
+#### 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)
🚀 30. "ฉันต้องจัดส่งเวิร์กโฟลว์เอเจนต์โดยไม่มีการแผ่ขยายโค้ดกาว"
+🚀 30. "I need to ship agentic workflows without glue-code sprawl"
-ทีมจะสูญเสียความเร็วเมื่อรวมบริการและสคริปต์เฉพาะกิจหลายรายการเข้าด้วยกัน +Teams lose velocity when stitching multiple ad-hoc services and scripts. -**OmniRoute แก้ปัญหาอย่างไร:** +**How OmniRoute solves it:** -- กลยุทธ์อุปกรณ์ปลายทางแบบครบวงจรสำหรับลูกค้าและตัวแทน -- UIs การจัดการโปรโตคอลในตัวและเส้นทางการตรวจสอบควัน -- รากฐานที่พร้อมสำหรับการผลิต (ความปลอดภัย การบันทึก ความยืดหยุ่น การสำรองข้อมูล) +- Unified endpoint strategy for clients and agents +- Built-in protocol management UIs and smoke validation paths +- Production-ready foundations (security, logging, resilience, backup)
-` บล็อก → `reasoning_content` สำหรับการคิดโมเดล
-- **เอาต์พุตที่มีโครงสร้าง** — `json_schema` → `responseMimeType`/`responseSchema` ของราศีเมถุน
-
-### 👥 รองรับหลายบัญชี
-
-- เพิ่มหลายบัญชีต่อผู้ให้บริการ
-- การวนรอบอัตโนมัติหรือการกำหนดเส้นทางตามลำดับความสำคัญ
-- ถอยกลับไปยังบัญชีถัดไปเมื่อถึงโควต้า
-
-### 🔄 รีเฟรชโทเค็นอัตโนมัติ
-
-- โทเค็น OAuth จะรีเฟรชโดยอัตโนมัติก่อนหมดอายุ
-- ไม่จำเป็นต้องตรวจสอบสิทธิ์ซ้ำด้วยตนเอง
-- ประสบการณ์ที่ไร้รอยต่อกับผู้ให้บริการทุกราย
-
-### 🎨 คอมโบที่กำหนดเอง
-
-- สร้างชุดค่าผสมโมเดลได้ไม่จำกัด
-- 6 กลยุทธ์: เติมก่อน ปัดเศษ ยกกำลังสองตัวเลือก สุ่ม ใช้น้อยที่สุด ปรับต้นทุนให้เหมาะสม
-- แบ่งปันคอมโบระหว่างอุปกรณ์ด้วย Cloud Sync
-
-### 🏥 แดชบอร์ดสุขภาพ
-
-- สถานะของระบบ (สถานะการออนไลน์, เวอร์ชัน, การใช้หน่วยความจำ)
-- สถานะเซอร์กิตเบรกเกอร์ต่อผู้ให้บริการ (ปิด/เปิด/เปิดครึ่ง)
-- สถานะการจำกัดอัตราและการล็อกที่ใช้งานอยู่
-- สถิติแคชลายเซ็น
-- telemetry Latency (p50/p95/p99) + แคชพร้อมท์
-- รีเซ็ตสถานะสุขภาพได้ด้วยคลิกเดียว
-
-### ???? สนามเด็กเล่นนักแปล
-
-OmniRoute มี Translator Playground ในตัวอันทรงพลัง พร้อมด้วย **4 โหมด** สำหรับการดีบัก การทดสอบ และการตรวจสอบการแปล API:
-
-| โหมด | คำอธิบาย |
-| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **💻 สนามเด็กเล่น** | การแปลรูปแบบโดยตรง — วางเนื้อหาคำขอ API ใดๆ และดูได้ทันทีว่า OmniRoute แปลระหว่างรูปแบบของผู้ให้บริการอย่างไร (OpenAI ↔ Claude ↔ Gemini ↔ Responses API) รวมเทมเพลตตัวอย่างและการตรวจจับรูปแบบอัตโนมัติ |
-| **💌 โปรแกรมทดสอบการแชท** | ส่งคำขอแชทจริงผ่าน OmniRoute และดูการเดินทางไปกลับทั้งหมด: ข้อมูลของคุณ คำขอที่แปล คำตอบของผู้ให้บริการ และการตอบกลับที่แปลแล้ว ล้ำค่าสำหรับการตรวจสอบการกำหนดเส้นทางคำสั่งผสม |
-| **🧪 ม้านั่งทดสอบ** | โหมดการทดสอบแบบแบตช์ — กำหนดกรณีการทดสอบหลายกรณีด้วยอินพุตและเอาต์พุตที่คาดหวังที่แตกต่างกัน รันการทดสอบทั้งหมดพร้อมกัน และเปรียบเทียบผลลัพธ์ระหว่างผู้ให้บริการและโมเดลต่างๆ |
-| **📱 ไลฟ์มอนิเตอร์** | การตรวจสอบคำขอแบบเรียลไทม์ — ดูคำขอที่เข้ามาขณะที่คำขอไหลผ่าน OmniRoute ดูการแปลรูปแบบที่เกิดขึ้นแบบสด และระบุปัญหาได้ทันที |
-
-**การเข้าถึง:** แดชบอร์ด → นักแปล (แถบด้านข้าง)
-
-### 💾 คลาวด์ซิงค์
-
-- ซิงค์ผู้ให้บริการ คอมโบ และการตั้งค่าระหว่างอุปกรณ์ต่างๆ
-- ซิงค์พื้นหลังอัตโนมัติ
-- พื้นที่เก็บข้อมูลที่เข้ารหัสที่ปลอดภัย
+- `GET /api/mcp/status`
+- `GET /api/mcp/tools`
+- `GET /api/mcp/audit`
+- `GET /api/mcp/audit/stats`
-## 🧪 การประเมินผล (Evals)
+📖 รายละเอียดคุณสมบัติ
-### 🎯 ทางเลือกสำรอง 4 ชั้นอัจฉริยะ +🧩 MCP Setup (Model Context Protocol)
-สร้างคอมโบพร้อมทางเลือกอัตโนมัติ: +Start MCP transport in stdio mode: -``` -Combo: "my-coding-stack" - 1. cc/claude-opus-4-6 (your subscription) - 2. nvidia/llama-3.3-70b (free NVIDIA API) - 3. glm/glm-4.7 (cheap backup, $0.6/1M) - 4. if/kimi-k2-thinking (free fallback) - -→ Auto switches when quota runs out or errors occur +```bash +omniroute --mcp ``` -### 📊 การติดตามโควต้าแบบเรียลไทม์ +Recommended validation flow: -- การใช้โทเค็นต่อผู้ให้บริการ -- รีเซ็ตการนับถอยหลัง (5 ชั่วโมง รายวัน รายสัปดาห์) -- การประมาณต้นทุนสำหรับระดับที่ชำระเงิน -- รายงานการใช้จ่ายรายเดือน +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: -การแปลที่ราบรื่นระหว่างรูปแบบ: - -- **OpenAI** ↔ **Claude** ↔ **ราศีเมถุน** ↔ **การตอบกลับ OpenAI** -- เครื่องมือ CLI ของคุณส่งรูปแบบ OpenAI → การแปล OmniRoute → ผู้ให้บริการได้รับรูปแบบดั้งเดิม -- ทำงานร่วมกับเครื่องมือใดๆ ที่รองรับจุดสิ้นสุด OpenAI ที่กำหนดเอง -- **การฆ่าเชื้อการตอบสนอง** — ตัดช่องที่ไม่ได้มาตรฐานสำหรับความเข้ากันได้ของ OpenAI SDK ที่เข้มงวด -- **การปรับบทบาทให้เป็นมาตรฐาน** — `developer` → `system` สำหรับ non-OpenAI; `system` → `user` สำหรับรุ่น GLM/ERNIE -- **ลองแยกแท็ก** — `
+
🤝 A2A Setup (Agent2Agent)
-OmniRoute มีกรอบการประเมินในตัวเพื่อทดสอบคุณภาพการตอบสนองของ LLM เทียบกับชุดทอง เข้าถึงได้ผ่านทาง **Analytics → Evals** ในแดชบอร์ด +Discover the agent: -### ชุดทองในตัว +```bash +curl http://localhost:20128/.well-known/agent.json +``` -"OmniRoute Golden Set" ที่โหลดไว้ล่วงหน้าประกอบด้วยกรณีทดสอบ 10 กรณีที่ครอบคลุม: +Send a task: -- คำทักทาย คณิตศาสตร์ ภูมิศาสตร์ การสร้างโค้ด -- การปฏิบัติตามรูปแบบ JSON, การแปล, มาร์กดาวน์ -- การปฏิเสธอย่างปลอดภัย (เนื้อหาที่เป็นอันตราย) การนับ ตรรกะบูลีน +```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."}]}}' +``` -### กลยุทธ์การประเมินผล +Manage lifecycle: -| กลยุทธ์ | คำอธิบาย | ตัวอย่าง | -| ---------- | ------------------------------------------------------------------ | -------------------------------- | -| `exact` | ผลลัพธ์จะต้องตรงกันทุกประการ | `"4"` | -| `contains` | เอาต์พุตจะต้องมีสตริงย่อย (ไม่คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่) | `"Paris"` | -| `regex` | เอาต์พุตต้องตรงกับรูปแบบ regex | `"1.*2.*3"` | -| `custom` | ฟังก์ชัน JS แบบกำหนดเองส่งคืนค่า true/false | `(output) => output.length > 10` | +- `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 + +
-
+
+💳 ผู้ให้บริการสมัครสมาชิก
-### รหัสคลอด (Pro/Max) +🧪 End-to-end protocol validation
+ +Validate both protocols with real clients: + +```bash +npm run test:protocols:e2e +``` + +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) ```bash Dashboard → Providers → Connect Claude Code @@ -1064,9 +1438,9 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**เคล็ดลับสำหรับมือโปร:** ใช้ Opus สำหรับงานที่ซับซ้อน และใช้ Sonnet เพื่อความรวดเร็ว โควต้าการติดตาม OmniRoute ต่อรุ่น! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! -### OpenAI Codex (พลัส/โปร) +### OpenAI Codex (Plus/Pro) ```bash Dashboard → Providers → Connect Codex @@ -1078,7 +1452,24 @@ Models: cx/gpt-5.1-codex-max ``` -### Gemini CLI (ฟรี 180K/เดือน!) +#### 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). + +### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -1090,9 +1481,9 @@ Models: gc/gemini-2.5-pro ``` -**คุ้มค่าที่สุด:** ระดับฟรีมหาศาล! ใช้สิ่งนี้ก่อนระดับที่ชำระเงิน +**Best Value:** Huge free tier! Use this before paid tiers. -### นักบิน GitHub +### GitHub Copilot ```bash Dashboard → Providers → Connect GitHub @@ -1108,85 +1499,88 @@ Models:
-
🔑 ผู้ให้บริการคีย์ API
-### NVIDIA NIM (ฟรี 1,000 เครดิต!) +🔑 API Key Providers
-1. ลงทะเบียน: [build.nvidia.com](https://build.nvidia.com) -2. รับคีย์ API ฟรี (รวมเครดิตการอนุมาน 1,000 รายการ) -3. แดชบอร์ด → เพิ่มผู้ให้บริการ → NVIDIA NIM: - - คีย์ API: `nvapi-your-key` +### NVIDIA NIM (FREE developer access — 70+ models) -**รุ่น:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct` และอีก 50+ รายการ +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` -**เคล็ดลับสำหรับมือโปร:** API ที่เข้ากันได้กับ OpenAI — ทำงานได้อย่างราบรื่นกับการแปลรูปแบบของ OmniRoute! +**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! -1. ลงทะเบียน: [platform.deepseek.com](https://platform.deepseek.com) -2. รับรหัส API -3. แดชบอร์ด → เพิ่มผู้ให้บริการ → DeepSeek +### DeepSeek -**รุ่น:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` +1. Sign up: [platform.deepseek.com](https://platform.deepseek.com) +2. Get API key +3. Dashboard → Add Provider → DeepSeek -### Groq (มีระดับฟรี!) +**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` -1. ลงทะเบียน: [console.groq.com](https://console.groq.com) -2. รับคีย์ API (รวมเทียร์ฟรี) -3. แดชบอร์ด → เพิ่มผู้ให้บริการ → Groq +### Groq (Free Tier Available!) -**รุ่น:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` +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` -### OpenRouter (มากกว่า 100 รุ่น) +**Pro Tip:** Ultra-fast inference — best for real-time coding! -1. ลงทะเบียน: [openrouter.ai](https://openrouter.ai) -2. รับรหัส API -3. แดชบอร์ด → เพิ่มผู้ให้บริการ → OpenRouter +### OpenRouter (100+ Models) -**รุ่น:** เข้าถึงโมเดลมากกว่า 100 โมเดลจากผู้ให้บริการรายใหญ่ทั้งหมดผ่านคีย์ API เดียว +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.
-
💰 ผู้ให้บริการราคาถูก (สำรอง)
-### GLM-4.7 (รีเซ็ตรายวัน, $0.6/1M) +💰 Cheap Providers (Backup)
-1. ลงทะเบียน: [Zhipu AI](https://open.bigmodel.cn/) -2. รับคีย์ API จาก Coding Plan -3. แดชบอร์ด → เพิ่มคีย์ API: - - ผู้ให้บริการ: `glm` - - คีย์ API: `your-key` +### GLM-4.7 (Daily reset, $0.6/1M) -**ใช้:** `glm/glm-4.7` +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` -**เคล็ดลับสำหรับมือโปร:** แผนการเขียนโค้ดเสนอโควต้า 3 เท่าในราคา 1/7! รีเซ็ตทุกวัน 10.00 น. +**Use:** `glm/glm-4.7` -### MiniMax M2.1 (รีเซ็ต 5 ชม., $0.20/1M) +**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -1. ลงทะเบียน: [MiniMax](https://www.minimax.io/) -2. รับรหัส API -3. แดชบอร์ด → เพิ่มคีย์ API +### MiniMax M2.1 (5h reset, $0.20/1M) -**ใช้:** `minimax/MiniMax-M2.1` +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key +3. Dashboard → Add API Key -**เคล็ดลับสำหรับมือโปร:** ตัวเลือกที่ถูกที่สุดสำหรับบริบทที่ยาว (โทเค็น 1M)! +**Use:** `minimax/MiniMax-M2.1` -### Kimi K2 ($9/เดือน) +**Pro Tip:** Cheapest option for long context (1M tokens)! -1. สมัครสมาชิก: [Moonshot AI](https://platform.moonshot.ai/) -2. รับรหัส API -3. แดชบอร์ด → เพิ่มคีย์ API +### Kimi K2 ($9/month flat) -**ใช้:** `kimi/kimi-latest` +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key +3. Dashboard → Add API Key -**เคล็ดลับสำหรับมือโปร:** แก้ไข $9/เดือนสำหรับโทเค็น 10M = $0.90/ต้นทุนที่แท้จริง 1M! +**Use:** `kimi/kimi-latest` + +**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
-
🆓 ผู้ให้บริการฟรี (การสำรองข้อมูลฉุกเฉิน)
-### iFlow (ฟรี 8 รุ่น) +🆓 FREE Providers (Emergency Backup)
+ +### iFlow (5 FREE models via OAuth) ```bash Dashboard → Connect iFlow @@ -1201,7 +1595,7 @@ Models: if/deepseek-r1 ``` -### Qwen (ฟรี 3 รุ่น) +### Qwen (4 FREE models via Device Code) ```bash Dashboard → Connect Qwen @@ -1213,7 +1607,7 @@ Models: qw/qwen3-coder-flash ``` -### คิโระ (คลอดด์ฟรี) +### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro @@ -1228,8 +1622,9 @@ Models:
-
🎨 สร้างคอมโบ
-### ตัวอย่างที่ 1: เพิ่มการสมัครสมาชิกให้สูงสุด → การสำรองข้อมูลราคาถูก +🎨 Create Combos
+ +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -1243,7 +1638,7 @@ Models: Use in CLI: premium-coding ``` -### ตัวอย่างที่ 2: ฟรีเท่านั้น (ไม่มีค่าใช้จ่าย) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -1258,8 +1653,9 @@ Cost: $0 forever!
-
---
-## 🐛 การแก้ไขปัญหา
+## การแก้ไขปัญหา
ดำเนินการบูรณาการ CLI
-### เคอร์เซอร์ IDE +🔧 CLI Integration
+ +### Cursor IDE ``` Settings → Models → Advanced: @@ -1268,9 +1664,9 @@ Settings → Models → Advanced: Model: cc/claude-opus-4-6 ``` -### รหัสคลอด +### Claude Code -ใช้หน้า **เครื่องมือ CLI** ในแดชบอร์ดสำหรับการกำหนดค่าด้วยคลิกเดียว หรือแก้ไข `~/.claude/settings.json` ด้วยตนเอง +Use the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually. ### Codex CLI @@ -1281,15 +1677,15 @@ export OPENAI_API_KEY="your-omniroute-api-key" codex "your prompt" ``` -### โอเพ่นคลอว์ +### OpenClaw -**ตัวเลือก 1 — แดชบอร์ด (แนะนำ):** +**Option 1 — Dashboard (recommended):** ``` Dashboard → CLI Tools → OpenClaw → Select Model → Apply ``` -**ตัวเลือก 2 — กำหนดเอง:** แก้ไข `~/.openclaw/openclaw.json`: +**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`: ```json { @@ -1305,9 +1701,9 @@ Dashboard → CLI Tools → OpenClaw → Select Model → Apply } ``` -> **หมายเหตุ:** OpenClaw ใช้งานได้กับ OmniRoute ในพื้นที่เท่านั้น ใช้ `127.0.0.1` แทน `localhost` เพื่อหลีกเลี่ยงปัญหาความละเอียดของ IPv6 +> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues. -### ไคลน์ / ดำเนินการต่อ / RooCode +### Cline / Continue / RooCode ``` Settings → API Configuration: @@ -1317,109 +1713,245 @@ Settings → API Configuration: 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. +
-
-- **รันไทม์**: Node.js 18–22 LTS (⚠️ Node.js 24+ ไม่ได้รับการสนับสนุน\*\* — `better-sqlite3` ไบนารีดั้งเดิมเข้ากันไม่ได้)
-- **ภาษา**: TypeScript 5.9 — **100% TypeScript** ทั่วทั้ง `src/` และ `open-sse/` (v1.0.6)
-- **เฟรมเวิร์ก**: Next.js 16 + React 19 + Tailwind CSS 4
-- **ฐานข้อมูล**: LowDB (JSON) + SQLite (สถานะโดเมน + บันทึกพร็อกซี)
-- **การสตรีม**: เหตุการณ์ที่เซิร์ฟเวอร์ส่ง (SSE)
-- **Auth**: OAuth 2.0 (PKCE) + JWT + คีย์ API
-- **การทดสอบ**: ตัวรันการทดสอบ Node.js (การทดสอบหน่วยมากกว่า 368 รายการ)
-- **CI/CD**: การดำเนินการ GitHub (เผยแพร่ npm อัตโนมัติ + Docker Hub เมื่อวางจำหน่าย)
-- **เว็บไซต์**: [omniroute.online](https://omniroute.online)
-- **แพ็คเกจ**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
-- **นักเทียบท่า**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
-- **ความยืดหยุ่น**: เซอร์กิตเบรกเกอร์, การถอยกลับแบบเอ็กซ์โปเนนเชียล, การป้องกันฝูงฟ้าผ่า, การปลอมแปลง TLS
-
----
-
-## 📖 เอกสารประกอบ
-
-| เอกสาร | คำอธิบาย |
-| -------------------------------------------- | ----------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | ผู้ให้บริการ, คอมโบ, การรวม CLI, การปรับใช้ |
-| [API Reference](docs/API_REFERENCE.md) | จุดสิ้นสุดทั้งหมดพร้อมตัวอย่าง |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | ปัญหาและแนวทางแก้ไขทั่วไป |
-| [Architecture](docs/ARCHITECTURE.md) | สถาปัตยกรรมระบบและภายใน |
-| [Contributing](CONTRIBUTING.md) | การตั้งค่าและแนวทางการพัฒนา |
-| [OpenAPI Spec](docs/openapi.yaml) | ข้อมูลจำเพาะของ OpenAPI 3.0 |
-| [Security Policy](SECURITY.md) | การรายงานช่องโหว่และแนวปฏิบัติด้านความปลอดภัย |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | คู่มือฉบับสมบูรณ์: VM + nginx + การตั้งค่า Cloudflare |
-| [Features Gallery](docs/FEATURES.md) | ทัวร์ชมแดชบอร์ดภาพพร้อมภาพหน้าจอ |
-
-### 📸 ดูตัวอย่างแดชบอร์ด
+## 🛠️ Tech Stack
คลิกเพื่อขยายคำแนะนำการแก้ปัญหา
-**"โมเดลภาษาไม่ได้ระบุข้อความ"** +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 -- โควต้าการสมัครสมาชิกหมด → สำรองไปที่ GLM/MiniMax -- เพิ่มคอมโบ: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +**Rate limiting** -**โทเค็น OAuth หมดอายุแล้ว** +- Subscription quota out → Fallback to GLM/MiniMax +- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -- รีเฟรชอัตโนมัติโดย OmniRoute -- หากปัญหายังคงอยู่: แดชบอร์ด → ผู้ให้บริการ → เชื่อมต่อใหม่ +**OAuth token expired** -**ค่าใช้จ่ายสูง** +- Auto-refreshed by OmniRoute +- If issues persist: Dashboard → Provider → Reconnect -- ตรวจสอบสถิติการใช้งานในแดชบอร์ด → ต้นทุน -- เปลี่ยนโมเดลหลักเป็น GLM/MiniMax -- ใช้ระดับฟรี (Gemini CLI, iFlow) สำหรับงานที่ไม่สำคัญ +**High costs** -**แดชบอร์ดเปิดผิดพอร์ต** +- Check usage stats in Dashboard → Costs +- Switch primary model to GLM/MiniMax +- Use free tier (Gemini CLI, iFlow) for non-critical tasks -- ตั้งค่า `PORT=20128` และ `NEXT_PUBLIC_BASE_URL=http://localhost:20128` +**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) -- ตรวจสอบ `BASE_URL` ชี้ไปยังอินสแตนซ์ที่ทำงานอยู่ของคุณ -- ตรวจสอบ `CLOUD_URL` ชี้ไปยังจุดปลายทางคลาวด์ที่คุณคาดหวัง -- เก็บค่า `NEXT_PUBLIC_*` ให้สอดคล้องกับค่าฝั่งเซิร์ฟเวอร์ +**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 -- ตรวจสอบ `INITIAL_PASSWORD` ใน `.env` -- หากไม่ได้ตั้งค่า รหัสผ่านสำรองจะเป็น `123456` +**First login not working** -** ไม่มีบันทึกคำขอ ** +- Check `INITIAL_PASSWORD` in `.env` +- If unset, fallback password is `123456` -- ตั้งค่า `ENABLE_REQUEST_LOGS=true` ใน `.env` +**No request logs** -**การทดสอบการเชื่อมต่อแสดงว่า "ไม่ถูกต้อง" สำหรับผู้ให้บริการที่รองรับ OpenAI** +- Set `ENABLE_REQUEST_LOGS=true` in `.env` -- ผู้ให้บริการหลายรายไม่เปิดเผยปลายทาง `/models` -- OmniRoute v1.0.6+ มีการตรวจสอบทางเลือกผ่านการแชทให้เสร็จสิ้น -- ตรวจสอบให้แน่ใจว่า URL ฐานมีคำต่อท้าย `/v1` +**Connection test shows "Invalid" for OpenAI-compatible providers** -### 🔐 OAuth ในเซิร์ฟเวอร์ Remoto (การตั้งค่า OAuth ระยะไกล) +- 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 + + -> **⚠️ สิ่งสำคัญสำหรับการใช้ OmniRoute กับ VPS/Docker/servidor remoto** +> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server** -### OAuth +#### Why does Antigravity / Gemini CLI OAuth fail on remote servers? -ระบบปฏิบัติการ **Antigravity** และ **Gemini CLI** ใช้ **Google OAuth 2.0** สำหรับการรับรองความถูกต้อง O Google ต้องการ `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo. +The **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console. -ตามที่รับรอง OAuth embutidas no OmniRoute estão cadastradas **apenas para `localhost`**. ต้องการใช้ OmniRoute ในเซิร์ฟเวอร์ remoto (เช่น `https://omniroute.meuservidor.com`) หรือ Google ตรวจสอบ com autenticação: +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 ``` -### วิธีแก้ปัญหา: กำหนดค่า suas próprias credenciais OAuth +#### Solution: Configure your own OAuth credentials -อยู่ในนั้นโดยตรง **OAuth 2.0 Client ID** ไม่มี Google Cloud Console พร้อม URI สำหรับเซิร์ฟเวอร์ +You need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI. -#### เยี่ยมเลย +#### Step-by-step -**1. เข้าถึง Google Cloud Console** +**1. Open Google Cloud Console** -อับรา: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) +Go to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) -**2. ฉันเพิ่งค้นพบ OAuth 2.0 Client ID** +**2. Create a new OAuth 2.0 Client ID** -- คลิก em **"+ สร้างข้อมูลรับรอง"** → **"รหัสไคลเอ็นต์ OAuth"** -- เคล็ดลับการใช้งาน: **"แอปพลิเคชันเว็บ"** -- ชื่อ: ชื่อ escolha qualquer (เช่น: `OmniRoute Remote`) +- Click **"+ Create Credentials"** → **"OAuth client ID"** +- Application type: **"Web application"** +- Name: anything you like (e.g. `OmniRoute Remote`) -**3. Adicione เป็น URI การเปลี่ยนเส้นทางที่ได้รับอนุญาต** +**3. Add Authorized Redirect URIs** -ไม่มีค่าย **"URI การเปลี่ยนเส้นทางที่ได้รับอนุญาต"** ผู้สนับสนุน: +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 + +# For Gemini CLI: +GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com +GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +``` + +**6. Restart OmniRoute** + +```bash +# npm: +npm run dev + +# Docker: +docker restart omniroute +``` + +**7. Try connecting again** + +Dashboard → Providers → Antigravity (or Gemini CLI) → OAuth + +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. + +--- + +
+
---
-## 🛠️
+🇧🇷 Versão em Português
+ +#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos? + +Os provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo. + +As credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticação com: + +``` +Error 400: redirect_uri_mismatch +``` + +#### Solução: Configure suas próprias credenciais OAuth + +Você precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor. + +#### Passo a passo + +**1. Acesse o Google Cloud Console** + +Abra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) + +**2. Crie um novo OAuth 2.0 Client ID** + +- Clique em **"+ Create Credentials"** → **"OAuth client ID"** +- Tipo de aplicativo: **"Web application"** +- Nome: escolha qualquer nome (ex: `OmniRoute Remote`) + +**3. Adicione as Authorized Redirect URIs** + +No campo **"Authorized redirect URIs"**, adicione: ``` https://seu-servidor.com/callback ``` -> Substitua `seu-servidor.com` pelo domínio ou IP do seu servidor (รวม porta se necessário เช่น `http://45.33.32.156:20128/callback`) +> Substitua `seu-servidor.com` pelo domínio ou IP do seu servidor (inclua a porta se necessário, ex: `http://45.33.32.156:20128/callback`). -**4. Salve e copy as credenciais** +**4. Salve e copie as credenciais** -อ้างอิงถึง Google มากที่สุด o **Client ID** e o **Client Secret** +Após criar, o Google mostrará o **Client ID** e o **Client Secret**. -**5. กำหนดค่าเป็น variáveis de Ambiente** +**5. Configure as variáveis de ambiente** -ไม่มี `.env` (คุณมีตัวเลือกอื่นสำหรับ Docker): +No seu `.env` (ou nas variáveis de ambiente do Docker): ```bash # Para Antigravity: @@ -1432,7 +1964,7 @@ GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret ``` -**6. ย้อนกลับไปสู่ OmniRoute** +**6. Reinicie o OmniRoute** ```bash # Se usando npm: @@ -1442,151 +1974,147 @@ npm run dev docker restart omniroute ``` -**7. เต็นท์ คอนเนกตาร์ โนวาเมนเต** +**7. Tente conectar novamente** -แดชบอร์ด → ผู้ให้บริการ → Antigravity (หรือ Gemini CLI) → OAuth +Dashboard → Providers → Antigravity (ou Gemini CLI) → OAuth -ภาพรวมของ Google การแก้ไขสำหรับ `https://seu-servidor.com/callback` และการรับรองความถูกต้อง +Agora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará. --- -### วิธีแก้ปัญหาชั่วคราว (sem configurar credenciais próprias) +#### Workaround temporário (sem configurar credenciais próprias) Se não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**: -1. O OmniRoute ย่อ URL อัตโนมัติของ Google +1. O OmniRoute abrirá a URL de autorização do Google 2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto) -3. **คัดลอก URL ที่สมบูรณ์** da barra de endereço do seu browser (mesmo que a página não carregue) +3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue) 4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute -5. คลิกที่นี่ **"เชื่อมต่อ"** +5. Clique em **"Connect"** -> วิธีแก้ปัญหาเบื้องต้นคือทำการเปลี่ยนเส้นทางโดยอัตโนมัติและทำการเปลี่ยนเส้นทางโดยอัตโนมัติ +> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.
-
---
-## 🗺️
+## เอกสาร
-OmniRoute มี **ฟีเจอร์มากกว่า 210 รายการที่วางแผน** ไว้ในขั้นตอนการพัฒนาหลายขั้นตอน นี่คือประเด็นสำคัญ:
-
-| หมวดหมู่ | คุณสมบัติที่วางแผนไว้ | ไฮไลท์ |
-| ------------------------------------------ | --------------------- | ------------------------------------------------------------------------------------------------------------- |
-| 🧠 **การกำหนดเส้นทางและความฉลาด** | 25+ | การกำหนดเส้นทางที่มีความหน่วงต่ำที่สุด, การกำหนดเส้นทางตามแท็ก, โควต้า preflight, การเลือกบัญชี P2C |
-| 🔒 **ความปลอดภัยและการปฏิบัติตามข้อกำหนด** | 20+ | การเสริมความแข็งแกร่งของ SSRF, การปิดบังข้อมูลรับรอง, ขีดจำกัดอัตราต่อจุดสิ้นสุด, การกำหนดขอบเขตคีย์การจัดการ |
-| 📊 **ความสามารถในการสังเกต** | 15+ | การรวม OpenTelemetry การตรวจสอบโควต้าแบบเรียลไทม์ การติดตามต้นทุนต่อรุ่น |
-| 🔄 **การบูรณาการของผู้ให้บริการ** | 20+ | การลงทะเบียนโมเดลแบบไดนามิก, คูลดาวน์ของผู้ให้บริการ, Codex หลายบัญชี, การแยกวิเคราะห์โควต้า Copilot |
-| ⚡ **ประสิทธิภาพ** | 15+ | เลเยอร์แคชคู่, แคชพร้อมท์, แคชการตอบสนอง, การสตรีมแบบ Keepalive, ชุด API |
-| 🌐 **ระบบนิเวศ** | 10+ | WebSocket API, กำหนดค่า hot-reload, การจัดเก็บ config แบบกระจาย, โหมดเชิงพาณิชย์ |
-
-### 🔜 เร็วๆ นี้
-
-- 🔗 **การรวม OpenCode** — รองรับผู้ให้บริการเนทีฟสำหรับ IDE การเข้ารหัส OpenCode AI
-- 🔗 **การบูรณาการ TRAE** — รองรับกรอบการพัฒนา TRAE AI อย่างเต็มที่
-- 📦 **Batch API** — การประมวลผลแบบแบตช์แบบอะซิงโครนัสสำหรับคำขอจำนวนมาก
-- 🎯 **การกำหนดเส้นทางตามแท็ก** — คำขอกำหนดเส้นทางตามแท็กที่กำหนดเองและข้อมูลเมตา
-- 💰 **กลยุทธ์ต้นทุนต่ำสุด** — เลือกผู้ให้บริการที่ถูกที่สุดโดยอัตโนมัติ
-
-> dict ข้อมูลจำเพาะคุณสมบัติแบบเต็มมีอยู่ใน [link](docs/new-features/) (ข้อมูลจำเพาะโดยละเอียด 217 รายการ)
+| Document | Description |
+| ---------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 16 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/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
+| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
-## 👥 ผู้มีส่วนร่วม
+## 🗺️ Roadmap
+
+OmniRoute has **210+ 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, P2C account selection |
+| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |
+| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |
+| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider 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
[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
-### วิธีการมีส่วนร่วม
+### How to Contribute
-1. แยกพื้นที่เก็บข้อมูล
-2. สร้างสาขาคุณลักษณะของคุณ (`git checkout -b feature/amazing-feature`)
-3. ยอมรับการเปลี่ยนแปลงของคุณ (`git commit -m 'Add amazing feature'`)
-4. กดไปที่สาขา (`git push origin feature/amazing-feature`)
-5. เปิดคำขอดึง
+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
-ดู [CONTRIBUTING.md](CONTRIBUTING.md) สำหรับคำแนะนำโดยละเอียด
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
-### เปิดตัวเวอร์ชันใหม่
+### Releasing a New Version
```bash
# Create a release — npm publish happens automatically
-gh release create v1.0.6 --title "v1.0.6" --generate-notes
+gh release create v2.0.0 --title "v2.0.0" --generate-notes
```
---
-## 📊 ประวัติดารา
+## 📊 Star History
## Stargazers over time
## [](https://starchart.cc/diegosouzapw/OmniRoute)
-## 🙏ขอบพระคุณ
+## 🙏 Acknowledgments
-ขอขอบคุณเป็นพิเศษกับ **[9router](https://github.com/decolua/9router)** โดย **[decolua](https://github.com/decolua)** — โปรเจ็กต์ดั้งเดิมที่เป็นแรงบันดาลใจให้กับ Fork นี้ OmniRoute สร้างบนรากฐานอันน่าทึ่งดังกล่าวด้วยคุณสมบัติเพิ่มเติม API หลายรูปแบบ และการเขียน TypeScript ใหม่ทั้งหมด
+Special thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.
-ขอขอบคุณเป็นพิเศษสำหรับ **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — การใช้งาน Go ดั้งเดิมที่เป็นแรงบันดาลใจให้กับพอร์ต JavaScript นี้
+Special thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.
---
-## 📄 ใบอนุญาต
+## สิทธิ์การใช้งาน
-ใบอนุญาต MIT - ดู [LICENSE](LICENSE) สำหรับรายละเอียด
+MIT License - see [LICENSE](LICENSE) for details.
---
คลิกเพื่อดูภาพหน้าจอแดชบอร์ด
-| หน้า | ภาพหน้าจอ | -| ------------------- | ------------------------------------------------- | -| **ผู้ให้บริการ** |  | -| **คอมโบ** |  | -| **การวิเคราะห์** |  | -| **สุขภาพ** |  | -| **นักแปล** |  | -| **การตั้งค่า** |  | -| **เครื่องมือ CLI** |  | -| **บันทึกการใช้งาน** |  | -| **จุดสิ้นสุด** |  | +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**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions) +- **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
- สร้างด้วย ❤️ สำหรับนักพัฒนาที่เขียนโค้ด 24/7
+ Built with ❤️ for developers who code 24/7
- omniroute.online + omniroute.online
+
diff --git a/docs/i18n/th/docs/FEATURES.md b/docs/i18n/th/docs/FEATURES.md
new file mode 100644
index 0000000000..f58a52e527
--- /dev/null
+++ b/docs/i18n/th/docs/FEATURES.md
@@ -0,0 +1,145 @@
+# OmniRoute — Dashboard Features Gallery (ไทย)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/FEATURES.md) · 🇪🇸 [es](../../es/docs/FEATURES.md) · 🇫🇷 [fr](../../fr/docs/FEATURES.md) · 🇩🇪 [de](../../de/docs/FEATURES.md) · 🇮🇹 [it](../../it/docs/FEATURES.md) · 🇷🇺 [ru](../../ru/docs/FEATURES.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FEATURES.md) · 🇯🇵 [ja](../../ja/docs/FEATURES.md) · 🇰🇷 [ko](../../ko/docs/FEATURES.md) · 🇸🇦 [ar](../../ar/docs/FEATURES.md) · 🇮🇳 [in](../../in/docs/FEATURES.md) · 🇹🇭 [th](../../th/docs/FEATURES.md) · 🇻🇳 [vi](../../vi/docs/FEATURES.md) · 🇮🇩 [id](../../id/docs/FEATURES.md) · 🇲🇾 [ms](../../ms/docs/FEATURES.md) · 🇳🇱 [nl](../../nl/docs/FEATURES.md) · 🇵🇱 [pl](../../pl/docs/FEATURES.md) · 🇸🇪 [sv](../../sv/docs/FEATURES.md) · 🇳🇴 [no](../../no/docs/FEATURES.md) · 🇩🇰 [da](../../da/docs/FEATURES.md) · 🇫🇮 [fi](../../fi/docs/FEATURES.md) · 🇵🇹 [pt](../../pt/docs/FEATURES.md) · 🇷🇴 [ro](../../ro/docs/FEATURES.md) · 🇭🇺 [hu](../../hu/docs/FEATURES.md) · 🇧🇬 [bg](../../bg/docs/FEATURES.md) · 🇸🇰 [sk](../../sk/docs/FEATURES.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FEATURES.md) · 🇮🇱 [he](../../he/docs/FEATURES.md) · 🇵🇭 [phi](../../phi/docs/FEATURES.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FEATURES.md)
+
+---
+
+Visual guide to every section of the OmniRoute dashboard.
+
+---
+
+## 🔌 Providers
+
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
+
+
+
+---
+
+## 🎨 Combos
+
+Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
+
+
+
+---
+
+## 📊 Analytics
+
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
+
+
+
+---
+
+## 🏥 System Health
+
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+
+
+
+---
+
+## 🔧 Translator Playground
+
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
+
+
+
+---
+
+## 🎮 Model Playground _(v2.0.9+)_
+
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
+
+---
+
+## 🎨 Themes _(v2.0.5+)_
+
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
+
+## ⚙️ Settings
+
+Comprehensive settings panel with tabs:
+
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning
+- **Advanced** — Configuration overrides
+
+
+
+---
+
+## 🔧 CLI Tools
+
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
+
+
+
+---
+
+## 🤖 CLI Agents _(v2.0.11+)_
+
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
+
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
+
+---
+
+## 🖼️ Media _(v2.0.3+)_
+
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
+
+## 📝 Request Logs
+
+Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
+
+
+
+---
+
+## 🌐 API Endpoint
+
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
+
+
+
+---
+
+## 🔑 API Key Management
+
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
+
+---
+
+## 📋 Audit Log
+
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
+
+---
+
+## 🖥️ Desktop Application
+
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
+
+Key features:
+
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
+
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.
diff --git a/docs/i18n/uk-UA/README.md b/docs/i18n/uk-UA/README.md
index acb8d6afb6..1fb50f6f61 100644
--- a/docs/i18n/uk-UA/README.md
+++ b/docs/i18n/uk-UA/README.md
@@ -1,24 +1,94 @@
-- omniroute.online + omniroute.online
-
-
- # 🚀 OmniRoute — безкоштовний ШІ-шлюз
+# 🚀 OmniRoute — The Free AI Gateway (Українська)
-### Ніколи не припиняйте кодувати. Розумна маршрутизація до **БЕЗКОШТОВНИХ і недорогих моделей штучного інтелекту** з автоматичним резервним копіюванням.
-
-_Ваш універсальний API-проксі — одна кінцева точка, понад 36 провайдерів, нуль простоїв._
-
-**Завершення чату • Вбудовування • Генерація зображень • Аудіо • Реранжування • 100% TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Безкоштовний постачальник AI для ваших улюблених агентів кодування
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Підключіть будь-який інструмент IDE або CLI на основі штучного інтелекту через OmniRoute — безкоштовний шлюз API для необмеженого програмування._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+` tags no longer leak to clients in SSE streaming responses (#585) |
+| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with per-provider/account quota enforcement, idempotency, SHA-256 storage, and optional GitHub issue reporting |
+| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG → generic fallback chain |
+| 🔄 **Model Auto-Sync** | 24h scheduler and manual UI toggle to sync model lists for built-in and custom OpenAI-compatible providers |
+| 🌐 **OpenCode Zen/Go** | Two new providers from @kang-heewon via PR #530: free tier + subscription tier via `OpencodeExecutor` |
+| 🐛 **Gemini CLI OAuth** | Actionable error when `GEMINI_OAUTH_CLIENT_SECRET` is missing in Docker (was cryptic Google error) |
+| 🐛 **OpenCode config** | `saveOpenCodeConfig()` now correctly writes TOML to `XDG_CONFIG_HOME` |
+| 🐛 **Pinned model override** | `body.model` correctly set to `pinnedModel` on context-cache protection |
+| 🐛 **Codex/Claude loop** | `tool_result` blocks now converted to text to stop infinite loops |
+| 🐛 **Login redirect** | Login no longer freezes after skipping password setup |
+| 🐛 **Windows paths** | MSYS2/Git-Bash paths (`/c/...`) normalized to `C:\...` automatically |
+
+---
+
+## 🖼️ Main Dashboard
+
+
-📡 Усі агенти підключаються через ` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**Stop wasting money and hitting limits:**
-### 🆕 What's New in v3.0.0
+- Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**OmniRoute solves this:**
+
+- ✅ **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
+- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool
---
-[](https://www.npmjs.com/package/omniroute)
-[](https://hub.docker.com/r/diegosouzapw/omniroute)
-[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
-[](https://omniroute.online)
-[](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
+## 📧 Support
-[🌐 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)
+> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.
-🌐 **Available in:** 🇺🇸 [English](../../README.md) | 🇧🇷 [Português (Brasil)](../pt-BR/README.md) | 🇪🇸 [Español](../es/README.md) | 🇫🇷 [Français](../fr/README.md) | 🇮🇹 [Italiano](../it/README.md) | 🇷🇺 [Русский](../ru/README.md) | 🇨🇳 [中文 (简体)](../zh-CN/README.md) | 🇩🇪 [Deutsch](../de/README.md) | 🇮🇳 [हिन्दी](../in/README.md) | 🇹🇭 [ไทย](../th/README.md) | 🇺🇦 [Українська](../uk-UA/README.md) | 🇸🇦 [العربية](../ar/README.md) | 🇯🇵 [日本語](../ja/README.md) | 🇻🇳 [Tiếng Việt](../vi/README.md) | 🇧🇬 [Български](../bg/README.md) | 🇩🇰 [Dansk](../da/README.md) | 🇫🇮 [Suomi](../fi/README.md) | 🇮🇱 [עברית](../he/README.md) | 🇭🇺 [Magyar](../hu/README.md) | 🇮🇩 [Bahasa Indonesia](../id/README.md) | 🇰🇷 [한국어](../ko/README.md) | 🇲🇾 [Bahasa Melayu](../ms/README.md) | 🇳🇱 [Nederlands](../nl/README.md) | 🇳🇴 [Norsk](../no/README.md) | 🇵🇹 [Português (Portugal)](../pt/README.md) | 🇷🇴 [Română](../ro/README.md) | 🇵🇱 [Polski](../pl/README.md) | 🇸🇰 [Slovenčina](../sk/README.md) | 🇸🇪 [Svenska](../sv/README.md) | 🇵🇭 [Filipino](../phi/README.md)
-
-
-
----
-
-## 🖼️
-
-
-
- # 🚀 OmniRoute — безкоштовний ШІ-шлюз
+# 🚀 OmniRoute — The Free AI Gateway (Українська)
-### Ніколи не припиняйте кодувати. Розумна маршрутизація до **БЕЗКОШТОВНИХ і недорогих моделей штучного інтелекту** з автоматичним резервним копіюванням.
-
-_Ваш універсальний API-проксі — одна кінцева точка, понад 36 провайдерів, нуль простоїв._
-
-**Завершення чату • Вбудовування • Генерація зображень • Аудіо • Реранжування • 100% TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Безкоштовний постачальник AI для ваших улюблених агентів кодування
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Підключіть будь-який інструмент IDE або CLI на основі штучного інтелекту через OmniRoute — безкоштовний шлюз API для необмеженого програмування._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+
+
+[](https://www.npmjs.com/package/omniroute)
+[](https://www.npmjs.com/package/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
+[](https://omniroute.online)
+[](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)
+
+
+
+🌐 **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)
+
+---
+
+## 🆕 What's New in v3.0.0
+
+> **Upgrading from v2.9.5?** — See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes.
+
+| Area | Change |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection remediation |
+| ✅ **Route Validation** | All 176 API routes now validated with Zod schemas + `validateBody()` — CI `check:route-validation:t06` passes |
+| 🐛 **omniModel Tag Leak** | Internal `
+
+
+
+---
+
+## 📸 Dashboard Preview
+
+
+
+
+
+---
+
+### 🤖 Free AI Provider for your favorite coding agents
+
+_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._
Click to see dashboard screenshots
+ +| Page | Screenshot | +| -------------- | ------------------------------------------------- | +| **Providers** |  | +| **Combos** |  | +| **Analytics** |  | +| **Health** |  | +| **Translator** |  | +| **Settings** |  | +| **CLI Tools** |  | +| **Usage Logs** |  | +| **Endpoints** |  | + +|
-
+
OpenClaw @@ -92,113 +162,52 @@ _Підключіть будь-який інструмент IDE або CLI на |
http://localhost:20128/v1 або http://cloud.omniroute.online/v1 — одна конфігурація, необмежена кількість моделей і квота
+📡 All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 — one config, unlimited models and quota
---
-### 🆕 What's New in v3.0.0
+## 🤔 Why OmniRoute?
-| Area | Change |
-| ------------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal ` Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `
-
-
-
----
-
-## 📸
-
-
-
-
-
----
-
-## 🤔 Чому OmniRoute?
-
-**Припиніть витрачати гроші та досягати лімітів:**
-
-- ...
- -| # | # | -| ----- | ---------------------------------------- | -| **1** |  | -| **2** |  | -| **3** |  | -| **4** |  | -| **5** |  | -| **6** |  | -| **7** |  | -| **8** |  | -| **9** |  | - - Квота підписки закінчується без використання кожного місяця
-- Обмеження швидкості перешкоджають кодуванню в середині
-- Дорогі API ($20-50/місяць за постачальника)
-- Ручне перемикання між провайдерами
-
-**OmniRoute вирішує цю проблему:**
-
-- ✅ **Збільште кількість підписок** - Відстежуйте квоту, використовуйте кожен біт перед скиданням
-- ✅ **Автоматичний резерв** - Підписка → Ключ API → Дешево → Безкоштовно, без простоїв
-- ✅ **Кілька облікових записів** - Циклічний цикл між обліковими записами кожного постачальника
-- ✅ **Універсальний** - Працює з Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, будь-яким інструментом CLI
-
----
-
-## 📧 Підтримка
-
-> 💬 **Приєднуйтесь до нашої спільноти!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — отримуйте допомогу, діліться порадами та будьте в курсі подій.
-
-- **Веб-сайт**: [omniroute.online](https://omniroute.online)
+- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Проблеми**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Оригінальний проект**: [9router by decolua](https://github.com/decolua/9router)
+- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 Як це працює
+## 🔄 How It Works
```
┌─────────────┐
@@ -227,456 +236,453 @@ Result: Never stop coding, minimal cost
---
-## 🎯 Що вирішує OmniRoute — 30 реальних проблем і варіантів використання
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **Кожен розробник, який використовує інструменти штучного інтелекту, щодня стикається з цими проблемами.** OmniRoute було створено, щоб вирішити їх усі — від перевитрати коштів до регіональних блокувань, від порушених потоків OAuth до операцій протоколу та спостережуваності підприємства.
+> **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.
-
💸 1. «Я плачу за дорогу підписку, але мене все одно переривають через обмеження»
+💸 1. "I pay for an expensive subscription but still get interrupted by limits"
-Розробники платять 20–200 доларів на місяць за Claude Pro, Codex Pro або GitHub Copilot. Навіть якщо платити, квота має максимальну межу — 5 годин використання, тижневі ліміти або ліміти за хвилину. У середині сеансу кодування постачальник перестає відповідати, а розробник втрачає швидкість і продуктивність. +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. -**Як це вирішує OmniRoute:** +**How OmniRoute solves it:** -- **Smart 4-Tier Fallback** — якщо квота підписки закінчується, автоматично перенаправляється до API Key → Дешево → Безкоштовно без ручного втручання -- **Відстеження квот у реальному часі** — показує споживання токенів у реальному часі зі зворотним відліком скидання (5 годин, щодня, щотижня) -- **Підтримка кількох облікових записів** — кілька облікових записів у кожного постачальника з автоматичним циклічним перебором — коли один закінчується, перемикається на наступний -- **Користувацькі комбінації** — резервні ланцюжки, які можна налаштувати, із 6 стратегіями балансування (спочатку заповнення, циклічний, P2C, випадковий, найменш використовуваний, економічно оптимізований) -- **Бізнес-квоти Codex** — Моніторинг квот робочого простору бізнесу/команди безпосередньо на інформаційній панелі +- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention +- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly) +- **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 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
-` із таких моделей, як DeepSeek R1, у стандартизований `reasoning_content`
-- **Структурований вихід для Gemini** — `json_schema` → `responseMimeType`/`responseSchema` автоматичне перетворення
-- **`stream` за замовчуванням — `false`** — відповідає специфікації OpenAI, уникаючи неочікуваних SSE у Python/Rust/Go SDK.
+- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 67+ 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
🔌 2. «Мені потрібно використовувати кілька постачальників, але кожен має різний API»
+🔌 2. "I need to use multiple providers but each has a different API"
-OpenAI використовує один формат, Claude (Anthropic) використовує інший, Gemini ще інший. Якщо розробник хоче перевірити моделі від різних постачальників або повернутися до них, йому потрібно переналаштувати SDK, змінити кінцеві точки, мати справу з несумісними форматами. Спеціальні постачальники (FriendLI, NIM) мають нестандартні кінцеві точки моделі. +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. -**Як це вирішує OmniRoute:** +**How OmniRoute solves it:** -- **Уніфікована кінцева точка** — один `http://localhost:20128/v1` служить проксі для всіх 36+ постачальників -- **Переклад форматів** — автоматичний і прозорий: OpenAI ↔ Claude ↔ Gemini ↔ Responses API -- **Response Sanitization** — видаляє нестандартні поля (`x_groq`, `usage_breakdown`, `service_tier`), які порушують роботу OpenAI SDK v1.83+ -- **Нормалізація ролі** — перетворює `developer` → `system` для постачальників, які не є OpenAI; `system` → `user` для GLM/ERNIE -- **Think Tag Extraction** — витягує блоки `
-
🌐 3. «Мій постачальник штучного інтелекту блокує мій регіон/країну»
+🌐 3. "My AI provider blocks my region/country"
-Такі постачальники, як OpenAI/Codex, блокують доступ із певних географічних регіонів. Користувачі отримують помилки на зразок `unsupported_country_region_territory` під час з’єднань OAuth і API. Це особливо засмучує розробників із країн, що розвиваються. +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. -**Як це вирішує OmniRoute:** +**How OmniRoute solves it:** -- **3-рівнева конфігурація проксі-сервера** — налаштовується проксі-сервер на 3 рівнях: глобальний (увесь трафік), для кожного постачальника (лише один постачальник) і для кожного підключення/ключа -- **Значки проксі-сервера з кольоровим кодуванням** — Візуальні індикатори: 🟢 глобальний проксі, 🟡 проксі-сервер постачальника, 🔵 проксі-сервер підключення, завжди показує IP-адресу -- **Обмін маркерами OAuth через проксі** — потік OAuth також проходить через проксі, вирішуючи `unsupported_country_region_territory` -- **Тестування з’єднання через проксі** — тестування з’єднання використовує налаштований проксі (без прямого обходу) -- **Підтримка SOCKS5** — повна підтримка проксі SOCKS5 для вихідної маршрутизації -- **TLS Fingerprint Spoofing** — TLS-відбиток, як у браузері, через `wreq-js` для обходу виявлення ботів +- **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
-` prefix
-- **Безкоштовні комбінації** — ланцюжок `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = 0 доларів США/місяць без простоїв
-- **Безкоштовні кредити NVIDIA NIM** — інтегровано 1000 безкоштовних кредитів
-- **Стратегія оптимізації витрат** — стратегія маршрутизації, яка автоматично вибирає найдешевшого доступного постачальника
+- **Free-Only Combos** — Chain `gc/gemini-3-flash → 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
🆓 4. «Я хочу використовувати ШІ для кодування, але в мене немає грошей»
+🆓 4. "I want to use AI for coding but I have no money"
-Не кожен може платити 20–200 доларів на місяць за підписку на AI. Студентам, розробникам із країн, що розвиваються, любителям і фрілансерам потрібен доступ до якісних моделей за нульовою ціною. +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. -**Як це вирішує OmniRoute:** +**How OmniRoute solves it:** -- **Вбудовані безкоштовні постачальники рівня** — Вбудована підтримка 100% безкоштовних постачальників: iFlow (8 необмежених моделей), Qwen (3 необмежені моделі), Kiro (Claude безкоштовно), Gemini CLI (180K/місяць безкоштовно) +- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free) - **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/
-
🔒 5. «Мені потрібно захистити свій ШІ-шлюз від несанкціонованого доступу»
+🔒 5. "I need to protect my AI gateway from unauthorized access"
-Коли шлюз штучного інтелекту надається мережі (LAN, VPS, Docker), будь-хто, хто має адресу, може використовувати токени/квоту розробника. Без захисту API вразливі до неправильного використання, швидкого впровадження та зловживання. +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. -**Як це вирішує OmniRoute:** +**How OmniRoute solves it:** -- **Керування ключами API** — генерація, ротація та визначення обсягу для кожного постачальника за допомогою спеціальної сторінки `/dashboard/api-manager` -- **Дозволи на рівні моделі** — обмежте ключі API певними моделями (`openai/*`, шаблони узагальнення) із перемикачем «Дозволити все»/«Обмежити» -- **API Endpoint Protection** — вимагати ключ для `/v1/models` і блокувати певних постачальників зі списку -- **Auth Guard + CSRF Protection** — усі маршрути інформаційної панелі захищені проміжним програмним забезпеченням `withAuth` + маркерами CSRF -- **Обмежувач швидкості** — обмеження швидкості за IP-адресою з настроюваними вікнами -- **IP Filtering** — список дозволених/чорних адрес для контролю доступу -- **Prompt Injection Guard** — очищення від шкідливих шаблонів підказок -- **Шифрування AES-256-GCM** — облікові дані зашифровані в стані спокою +- **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. «Мій постачальник не працює, і я втратив потік кодування»
+🛑 6. "My provider went down and I lost my coding flow"
-Постачальники AI можуть стати нестабільними, повертати помилки 5xx або досягати тимчасових обмежень швидкості. Якщо розробник залежить від одного постачальника, вони перериваються. Без автоматичних вимикачів повторні спроби можуть призвести до збою програми. +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. -**Як це вирішує OmniRoute:** +**How OmniRoute solves it:** -- **Автоматичний вимикач для кожного постачальника** — автоматичне розмикання/замикання з настроюваними пороговими значеннями та часом відновлення (закрито/розімкнуто/напіврозімкнуто) -- **Exponential Backoff** — прогресивні затримки повторних спроб -- **Anti-Thundering Herd** — Mutex + захист семафора від одночасних повторних штормів -- **Комбіновані запасні ланцюги** — якщо основний постачальник виходить з ладу, автоматично проходить через ланцюжок без втручання. -- **Combo Circuit Breaker** — автоматично вимикає несправні постачальники в комбінованому ланцюжку - | 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format | -- **Health Dashboard** — Моніторинг безвідмовної роботи, стани автоматичного вимикача, блокування, статистика кешу, затримка p50/p95/p99 +- **Circuit Breaker per-model** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks +- **Exponential Backoff** — Progressive retry delays +- **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 +- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain +- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
-
🔧 7. «Налаштування кожного інструменту штучного інтелекту є виснажливим і повторюваним процесом»
+🔧 7. "Configuring each AI tool is tedious and repetitive"
-Розробники використовують Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Кожному інструменту потрібна інша конфігурація (кінцева точка API, ключ, модель). Перенастроювання при зміні постачальника чи моделі – марна трата часу. +Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time. -**Як це вирішує OmniRoute:** +**How OmniRoute solves it:** -- **Панель інструментів CLI** — спеціальна сторінка з налаштуванням одним клацанням для Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline -- **GitHub Copilot Config Generator** — генерує `chatLanguageModels.json` для коду VS із масовим вибором моделі -- **Майстер адаптації** — 4-етапне налаштування для тих, хто вперше користується -- **Одна кінцева точка, усі моделі** — налаштуйте `http://localhost:20128/v1` один раз, отримайте доступ до 36+ постачальників +- **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 67+ providers
-
🔑 8. «Керування токенами OAuth від кількох постачальників — це пекло»
+🔑 8. "Managing OAuth tokens from multiple providers is hell"
-Claude Code, Codex, Gemini CLI, Copilot — усі використовують OAuth 2.0 із терміном дії маркерів. Розробникам необхідно постійно проходити повторну автентифікацію, мати справу з `client_secret is missing`, `redirect_uri_mismatch` і збоями на віддалених серверах. OAuth у LAN/VPS є особливо проблематичним. +Claude Code, Codex, Gemini CLI, 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. -**Як це вирішує OmniRoute:** +**How OmniRoute solves it:** -- **Auto Token Refresh** — маркери OAuth оновлюються у фоновому режимі до завершення терміну дії -- **Вбудований OAuth 2.0 (PKCE)** — автоматичний потік для Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow -- **Multi-Account OAuth** — кілька облікових записів на постачальника за допомогою вилучення токенів JWT/ID -- **OAuth LAN/Remote Fix** — виявлення приватної IP-адреси для `redirect_uri` + ручний режим URL-адреси для віддалених серверів -- **OAuth за Nginx** — використовує `window.location.origin` для зворотної сумісності проксі -- **Remote OAuth Guide** — покроковий посібник для облікових даних Google Cloud на VPS/Docker +- **Auto Token Refresh** — OAuth tokens refresh in background before expiration +- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow +- **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. «Я не знаю, скільки я витрачаю і куди»
+📊 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. -**Як це вирішує OmniRoute:** +**How OmniRoute solves it:** -- **Інформаційна панель аналізу витрат** — відстеження вартості кожного токена та керування бюджетом для кожного постачальника -- **Бюджетні обмеження на рівень** — максимальна сума витрат на рівень, що запускає автоматичний відкат -- **Конфігурація ціни за модель** — налаштовувані ціни за модель -- **Статистика використання за ключ API** — кількість запитів і позначка часу останнього використання для кожного ключа -- **Інформаційна панель аналітики** — картки зі статистичними даними, діаграма використання моделі, таблиця постачальників із показниками успіху та затримкою +- **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. «Я не можу діагностувати помилки та проблеми під час викликів ШІ»
+🐛 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. -**Як це вирішує OmniRoute:** +**How OmniRoute solves it:** -- **Інформаційна панель уніфікованих журналів** — 4 вкладки: журнали запитів, журнали проксі, журнали аудиту, консоль -- **Console Log Viewer** — засіб перегляду терміналу в режимі реального часу з кольоровими рівнями, автопрокручуванням, пошуком, фільтром -- **Проксі-журнали SQLite** — постійні журнали, які залишаються після перезапуску сервера -- **Translator Playground** — 4 режими налагодження: Playground (переклад формату), Chat Tester (туди й назад), Test Bench (пакет), Live Monitor (у реальному часі) -- **Запит телеметрії** — затримка p50/p95/p99 + трасування X-Request-Id -- **Логування на основі файлів із ротацією** — консольний перехоплювач записує все в журнал JSON із ротацією на основі розміру +- **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 Proxy Logs** — Persistent logs that survive server restarts +- **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 Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation +- **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. «Розгортання та підтримка шлюзу є складною справою»
+🏗️ 11. "Deploying and maintaining the gateway is complex"
-Встановлення, налаштування та обслуговування проксі ШІ в різних середовищах (локальне, VPS, Docker, хмара) є трудомістким. Такі проблеми, як жорстко закодовані шляхи, `EACCES` у каталогах, конфлікти портів і кросплатформні збірки, додають тертя. +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. -**Як це вирішує OmniRoute:** +**How OmniRoute solves it:** -- **npm global install** — `npm install -g omniroute && omniroute` — готово -- **Мультиплатформенний Docker** — нативний AMD64 + ARM64 (Apple Silicon, AWS Graviton, Raspberry Pi) -- **Профілі створення Docker** — `base` (без інструментів CLI) і `cli` (з Claude Code, Codex, OpenClaw) -- **Electron Desktop App** — рідна програма для Windows/macOS/Linux із системним треєм, автозапуском, офлайн-режимом -- **Режим розділеного порту** — API та інформаційна панель на окремих портах для розширених сценаріїв (зворотний проксі, мережа контейнерів) -- **Cloud Sync** — синхронізація налаштувань між пристроями через Cloudflare Workers -- **Резервне копіювання БД** — автоматичне резервне копіювання, відновлення, експорт та імпорт усіх налаштувань +- **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
-
🌍 12. «Інтерфейс лише англійською мовою, і моя команда не розмовляє англійською»
+🌍 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. -**Як це вирішує OmniRoute:** +**How OmniRoute solves it:** -- **Інформаційна панель i18n — 30 мов** — перекладено всі 500+ клавіш, включаючи арабську, болгарську, датську, німецьку, іспанську, фінську, французьку, іврит, гінді, угорську, індонезійську, італійську, японську, корейську, малайську, голландську, норвезьку, польську, португальську (PT/BR), румунську, російську, словацьку, шведську, тайську, українську, в’єтнамську, китайська, філіппінська, англійська -- **Підтримка RTL** — підтримка арабської та івриту справа наліво -- **Багатомовні файли README** — 30 повних перекладів документації -- **Вибір мови** — значок глобуса в заголовку для перемикання в реальному часі +- **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. «Мені потрібно більше, ніж чат — мені потрібні вставки, зображення, аудіо»
+🔄 13. "I need more than chat — I need embeddings, images, audio"
-ШІ — це не просто завершення чату. Розробникам потрібно генерувати зображення, транскрибувати аудіо, створювати вбудовування для RAG, змінювати рейтинг документів і модерувати вміст. Кожен API має різну кінцеву точку та формат. +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. -**Як це вирішує OmniRoute:** +**How OmniRoute solves it:** -- **Вбудовування** — `/v1/embeddings` із 6 постачальниками та 9+ моделями -- **Генерація зображень** — `/v1/images/generations` із 10 постачальниками та понад 20 моделями (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI) -- **Текст у відео** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) і SD WebUI -- **Текст у музику** — `/v1/music/generations` — ComfyUI (Stable Audio Open, MusicGen) -- **Транскрипція аудіо** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3 -- **Перетворення тексту в мовлення** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, Inworld, Cartesia, PlayHT + існуючі постачальники -- **Модерації** — `/v1/moderations` — Перевірки безпеки вмісту -- **Переранжування** — `/v1/rerank` — Переранжування релевантності документа -- **Responses API** — повна підтримка `/v1/responses` для Codex +- **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. «У мене немає можливості перевірити та порівняти якість різних моделей»
+🧪 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. -**Як це вирішує OmniRoute:** +**How OmniRoute solves it:** -- **Оцінки LLM** — Золотий набір тестів із 10 попередньо завантаженими випадками, що охоплюють привітання, математику, географію, генерацію коду, відповідність JSON, переклад, уцінку, відмову безпеки -- **4 стратегії збігу** — `exact`, `contains`, `regex`, `custom` (функція JS) -- **Translator Playground Test Bench** — Пакетне тестування з кількома входами та очікуваними результатами, порівняння між постачальниками -- **Chat Tester** — повний цикл із візуальним відтворенням відповідей -- **Live Monitor** — потік усіх запитів, що проходять через проксі, у реальному часі +- **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. «Мені потрібно масштабувати без втрати продуктивності»
+📈 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. -**Як це вирішує OmniRoute:** +**How OmniRoute solves it:** -- **Семантичний кеш** — дворівневий кеш (підпис + семантичний) зменшує вартість і затримку -- **Request Idempotency** — вікно дедуплікації 5 с для ідентичних запитів -- **Виявлення ліміту швидкості** — RPM для кожного постачальника, мінімальний розрив і максимальне одночасне відстеження -- **Обмеження швидкості, які можна редагувати** — налаштування за замовчуванням у Параметрах → Стійкість із наполегливістю -- **API Key Validation Cache** — 3-рівневий кеш для продуктивності -- **Інформаційна панель справності з телеметрією** — затримка p50/p95/p99, статистика кешу, час роботи +- **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 +- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence +- **API Key Validation Cache** — 3-tier cache for production performance +- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
-
🤖 16. «Я хочу глобально контролювати поведінку моделі»
+🤖 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. -**Як це вирішує OmniRoute:** +**How OmniRoute solves it:** -- **Впровадження системної підказки** — глобальна підказка застосовується до всіх запитів -- **Thinking Budget Validation** — Контроль розподілу токенів міркувань за запитом (прохідний, автоматичний, спеціальний, адаптивний) -- **6 стратегій маршрутизації** — глобальні стратегії, які визначають спосіб розподілу запитів -- **Wildcard Router** — шаблони `provider/*` динамічно маршрутизують до будь-якого постачальника -- **Увімкнути/вимкнути комбо** — перемикайте комбо безпосередньо з інформаційної панелі -- **Перемикнути постачальника** — увімкнути/вимкнути всі з’єднання для постачальника одним клацанням миші -- **Заблоковані постачальники** — виключити певних постачальників зі списку `/v1/models` +- **System Prompt Injection** — Global prompt applied to all requests +- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive) +- **6 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 +- **Provider Toggle** — Enable/disable all connections for a provider with one click +- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
-
🧰 17. «Мені потрібні інструменти MCP як першокласні можливості продукту»
+🧰 17. "I need MCP tools as first-class product capabilities"
-Багато шлюзів ШІ розкривають MCP лише як приховану деталь реалізації. Командам потрібен видимий, керований рівень операцій. +Many AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer. -**Як це вирішує OmniRoute:** +**How OmniRoute solves it:** -- MCP з’являється на панелі навігації та на вкладці протоколу кінцевої точки -- Спеціальна сторінка керування MCP із процесом, інструментами, обсягами й аудитом -- Вбудований швидкий запуск для `omniroute --mcp` і адаптація клієнта +- 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. «Мені потрібна оркестровка A2A із синхронізацією + шляхи завдань потоку»
+🧠 18. "I need A2A orchestration with sync + stream task paths"
-Робочі процеси агента потребують як прямих відповідей, так і тривалого потокового виконання з контролем життєвого циклу. +Agent workflows need both direct replies and long-running streamed execution with lifecycle control. -**Як це вирішує OmniRoute:** +**How OmniRoute solves it:** -- Кінцева точка A2A JSON-RPC (`POST /a2a`) з `message/send` і `message/stream` -- Потокова передача SSE з розповсюдженням стану терміналу -- API життєвого циклу завдань для `tasks/get` і `tasks/cancel` +- 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. «Мені потрібна реальна справність процесу MCP, а не вгаданий статус»
+🛰️ 19. "I need real MCP process health, not guessed status"
-Операційним групам потрібно знати, чи справді MCP активний, а не лише те, чи доступний API. +Operational teams need to know if MCP is actually alive, not just whether an API is reachable. -**Як це вирішує OmniRoute:** +**How OmniRoute solves it:** -- Файл серцевого ритму виконання з PID, часовими мітками, транспортом, кількістю інструментів і режимом області -- API статусу MCP, що поєднує серцебиття + останню активність -- Картки стану інтерфейсу користувача для процесу/часу безперебійної роботи/свіжості пульсу +- 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. «Мені потрібне виконання інструменту MCP з можливістю перевірки»
+📋 20. "I need auditable MCP tool execution"
-Коли інструменти змінюють конфігурацію або запускають операційні дії, командам потрібна криміналістична відстежуваність. +When tools mutate config or trigger ops actions, teams need forensic traceability. -**Як це вирішує OmniRoute:** +**How OmniRoute solves it:** -— Журнал аудиту з підтримкою SQLite для викликів інструментів MCP - -- Фільтри за інструментом, успіхом/невдачею, ключем API та розбивкою на сторінки -- Таблиця аудиту інформаційної панелі + кінцеві точки статистики для автоматизації +- 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. «Мені потрібні обмежені дозволи MCP для інтеграції»
+🔐 21. "I need scoped MCP permissions per integration"
-Різні клієнти повинні мати мінімальний доступ до категорій інструментів. +Different clients should have least-privilege access to tool categories. -**Як це вирішує OmniRoute:** +**How OmniRoute solves it:** -- 9 детальних областей MCP для контрольованого доступу до інструменту -- Застосування обсягу та видимість в інтерфейсі користувача керування MCP -- Безпечна поза за замовчуванням для робочих інструментів +- 9 granular MCP scopes for controlled tool access +- Scope enforcement and visibility in MCP management UI +- Safe default posture for operational tooling
-
⚙️ 22. «Мені потрібен оперативний контроль без перерозподілу»
+⚙️ 22. "I need operational controls without redeploying"
-Командам потрібні швидкі зміни часу виконання під час інцидентів або витрат. +Teams need quick runtime changes during incidents or cost events. -**Як це вирішує OmniRoute:** +**How OmniRoute solves it:** -- Перемикання комбо-активації безпосередньо з інформаційної панелі MCP -- Застосовуйте профілі стійкості з попередньо визначених пакетів політик -- Скинути стан автоматичного вимикача з тієї ж панелі керування +- Switch combo activation directly from MCP dashboard +- Apply resilience profiles from pre-defined policy packs +- Reset circuit breaker state from the same operations panel
-
🔄 23. «Мені потрібна видимість і скасування життєвого циклу завдання A2A»
+🔄 23. "I need live A2A task lifecycle visibility and cancellation"
-Без видимості життєвого циклу інциденти завдань стає важко сортувати. +Without lifecycle visibility, task incidents become hard to triage. -**Як це вирішує OmniRoute:** +**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. «Мені потрібні активні показники потоку для завантаження A2A»
+🌊 24. "I need active stream metrics for A2A load"
-Робочі процеси потокової передачі вимагають оперативного розуміння паралельності та живих з’єднань. +Streaming workflows require operational insight into concurrency and live connections. -**Як це вирішує OmniRoute:** +**How OmniRoute solves it:** -— Лічильники активних потоків інтегровані в статус A2A - -- Мітка часу останнього завдання та підрахунок стану -- Картки інформаційної панелі A2A для моніторингу операцій у реальному часі +- Active stream counters integrated into A2A status +- Last task timestamp and per-state counts +- A2A dashboard cards for real-time ops monitoring
-
🪪 25. «Мені потрібне стандартне виявлення агентів для клієнтів»
+🪪 25. "I need standard agent discovery for clients"
-Зовнішнім клієнтам і оркестрантам потрібні машинозчитувані метадані для адаптації. +External clients and orchestrators need machine-readable metadata for onboarding. -**Як це вирішує OmniRoute:** +**How OmniRoute solves it:** -- Картка агента розкрита на `/.well-known/agent.json` -- Можливості та навички, показані в інтерфейсі користувача користувача -- API стану A2A включає метадані виявлення для автоматизації +- Agent Card exposed at `/.well-known/agent.json` +- Capabilities and skills shown in management UI +- A2A status API includes discovery metadata for automation
-
🧭 26. «Мені потрібна можливість виявлення протоколу в UX продукту»
+🧭 26. "I need protocol discoverability in the product UX"
-Якщо користувачі не можуть виявити поверхні протоколу, якість впровадження та підтримки падає. +If users cannot discover protocol surfaces, adoption and support quality drop. -**Як це вирішує OmniRoute:** +**How OmniRoute solves it:** -— Записи бічної панелі для MCP і A2A - -- Сторінка кінцевої точки Вкладка протоколів із швидким запуском і статусом -- Посилання з огляду на спеціальні інформаційні панелі керування +- 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. «Мені потрібна наскрізна перевірка протоколу з реальними клієнтами»
+🧪 27. "I need end-to-end protocol validation with real clients"
-Пробних тестів недостатньо для перевірки сумісності протоколу перед випуском. +Mock tests are not enough to validate protocol compatibility before release. -**Як це вирішує OmniRoute:** +**How OmniRoute solves it:** -- Комплект E2E, який завантажує програму та використовує реальний клієнтський транспорт MCP SDK -- Клієнт A2A перевіряє потоки виявлення, надсилання, потокової передачі, отримання та скасування -- Перехресна перевірка тверджень щодо аудиту MCP та API завдань A2A +- 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. «Мені потрібна уніфікована можливість спостереження через усі інтерфейси»
+📡 28. "I need unified observability across all interfaces"
-Поділ спостережуваності за протоколом створює сліпі зони та довший MTTR. +Splitting observability by protocol creates blind spots and longer MTTR. -**Як це вирішує OmniRoute:** +**How OmniRoute solves it:** -- Уніфіковані інформаційні панелі/журнали/аналітика в одному продукті -- Справність + аудит + телеметрія запитів на рівнях OpenAI, MCP і A2A -- Операційні API для статусу та автоматизації +- Unified dashboards/logs/analytics in one product +- Health + audit + request telemetry across OpenAI, MCP, and A2A layers +- Operational APIs for status and automation
-
💼 29. «Мені потрібне одне середовище виконання для проксі + інструментів + оркестровки агента»
+💼 29. "I need one runtime for proxy + tools + agent orchestration"
-Запуск багатьох окремих служб збільшує експлуатаційні витрати та частоту збоїв. +Running many separate services increases operational cost and failure modes. -**Як це вирішує OmniRoute:** +**How OmniRoute solves it:** -- OpenAI-сумісний проксі, сервер MCP і сервер A2A в одному стеку -- Спільна автентифікація, стійкість, зберігання даних і можливість спостереження -- Послідовна модель політики на всіх поверхнях взаємодії +- 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
-
-### Приклади Playbooks
+### Example Playbooks (Integrated Use Cases)
-**Playbook A: Максимальна кількість платної підписки + дешеве резервне копіювання**
+**Playbook A: Maximize paid subscription + cheap backup**
```txt
Combo: "maximize-claude"
@@ -688,7 +694,7 @@ Monthly cost: $20 + small backup spend
Outcome: higher quality, near-zero interruption
```
-**Playbook B: стек кодування без витрат**
+**Playbook B: Zero-cost coding stack**
```txt
Combo: "free-forever"
@@ -700,7 +706,7 @@ Monthly cost: $0
Outcome: stable free coding workflow
```
-**Playbook C: резервний ланцюжок 24/7**
+**Playbook C: 24/7 always-on fallback chain**
```txt
Combo: "always-on"
@@ -713,65 +719,132 @@ Combo: "always-on"
Outcome: deep fallback depth for deadline-critical workloads
```
-**Playbook D: Операції агента з MCP + A2A**
+**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/mcp and /dashboard/a2a
-4) Control incidents with resilience profile + task cancellation
+3) Observe via /dashboard/endpoint (MCP and A2A tabs)
+4) Toggle services via inline status controls
```
---
-## ⚡ Швидкий старт
+## 🆓 Start Free — Zero Configuration Cost
-**1. Встановити глобально:**
+> 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 **iFlow** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |
+| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |
+| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |
+| 5 | `/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).
+
+## Швидкий старт
+
+### 1) Install and run
```bash
npm install -g omniroute
omniroute
```
-🎉 Інформаційна панель відкривається в `http://localhost:20128`
+> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:
+>
+> ```bash
+> pnpm install -g omniroute
+> pnpm approve-builds -g # Select all packages → approve
+> omniroute
+> ```
-| Команда | Опис |
-| ----------------------- | ---------------------------------------------- |
-| `omniroute` | Запустити сервер (порт за замовчуванням 20128) |
-| `omniroute --port 3000` | Використовувати спеціальний порт |
-| `omniroute --no-open` | Не відкривати автоматично браузер |
-| `omniroute --help` | Показати довідку |
+Dashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.
-**2. Підключіть БЕЗКОШТОВНОГО провайдера:**
+| 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 |
-Інформаційна панель → Постачальники → Підключити **Claude Code** або **Antigravity** → Вхід OAuth → Готово!
+Optional split-port mode:
-**3. Використовуйте у своєму інструменті CLI:**
-
-```
-Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Settings:
- Endpoint: http://localhost:20128/v1
- API Key: [copy from dashboard]
- Model: if/kimi-k2-thinking
+```bash
+PORT=20128 DASHBOARD_PORT=20129 omniroute
+# API: http://localhost:20128/v1
+# Dashboard: http://localhost:20129
```
-**Ось і все!** Почніть кодувати з БЕЗКОШТОВНИМИ моделями ШІ.
+### 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
+
+```txt
+Base URL: http://localhost:20128/v1
+API Key: [copy from Endpoint page]
+Model: if/kimi-k2-thinking (or any provider/model prefix)
+```
+
+Works with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.
+
+### 4) Enable and validate protocols (v2.0)
+
+**MCP (for tool-driven operations):**
+
+```bash
+omniroute --mcp
+```
+
+Then connect your MCP client over `stdio` and test tools like:
+
+- `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 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
+PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev
```
---
-## 🐳 Докер
+## 🐳 Docker
-OmniRoute доступний як загальнодоступний образ Docker на [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
+OmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
-**Швидкий біг:**
+**Quick run:**
```bash
docker run -d \
@@ -782,7 +855,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**З файлом середовища:**
+**With environment file:**
```bash
# Copy and edit .env first
@@ -797,7 +870,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Використання Docker Compose:**
+**Using Docker Compose:**
```bash
# Base profile (no CLI tools)
@@ -807,255 +880,550 @@ docker compose --profile base up -d
docker compose --profile cli up -d
```
-| Зображення | Тег | Розмір | Опис |
-| ------------------------ | -------- | ------- | -------------------------- |
-| `diegosouzapw/omniroute` | `latest` | ~250 МБ | Останній стабільний випуск |
-| `diegosouzapw/omniroute` | `1.0.3` | ~250 МБ | Поточна версія |
+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.
+- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.
+- 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` | `1.0.3` | ~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
+### Швидкий старт
+
```bash
-npm run electron:dev # Development mode
+# 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)
+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
-| Рівень | Постачальник | Вартість | Скидання квоти | Найкраще для |
-| ------------------ | ---------------- | ------------------------------- | ----------------------------- | ---------------------------- |
-| **💳 ПІДПИСКА** | Клод Код (Pro) | 20 доларів США на місяць | 5 годин + щотижня | Вже підписані |
-| | Codex (Plus/Pro) | $20-200/міс | 5 годин + щотижня | Користувачі OpenAI |
-| | Gemini CLI | **БЕЗКОШТОВНО** | 180 тис./місяць + 1 тис./день | всі! |
-| | Копілот GitHub | $10-19/міс | Щомісяця | Користувачі GitHub |
-| **🔑 КЛЮЧ API** | NVIDIA NIM | **БЕЗКОШТОВНО** (1000 кредитів) | Одноразова | Безкоштовне тестування рівня |
-| | DeepSeek | Оплата за використання | Жодного | Краща ціна/якість |
-| | Groq | Безкоштовний рівень + платний | Оцінка обмежена | Надшвидкий висновок |
-| | xAI (Грок) | Оплата за використання | Жодного | Моделі Grok |
-| | Містраль | Безкоштовний рівень + платний | Оцінка обмежена | Європейський ШІ |
-| | OpenRouter | Оплата за використання | Жодного | 100+ моделей |
-| **💰 ДЕШЕВО** | GLM-4.7 | $0,6/1 млн | Щодня о 10 ранку | Резервне копіювання бюджету |
-| | MiniMax M2.1 | $0,2/1 млн | 5-годинний роликовий | Найдешевший варіант |
-| | Кімі К2 | 9 $/міс квартира | 10 млн токенів/міс | Передбачувана вартість |
-| **🆓 БЕЗКОШТОВНО** | iFlow | $0 | Необмежений | 8 моделей безкоштовно |
-| | Квен | $0 | Необмежений | 3 моделі безкоштовно |
-| | Кіро | $0 | Необмежений | Клод безкоштовно |
+| 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 |
+| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |
+| | 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** | iFlow | **$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 |
-**💡 Порада професіонала:** Почніть із Gemini CLI (180 тис. безкоштовно/місяць) + iFlow (необмежено безкоштовно) = 0 доларів США!
+> 🆕 **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
+iFlow (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
-| Особливість | Що він робить |
-| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| 🎯 **Розумний 4-рівневий резервний варіант** | Авто-маршрут: Підписка → Ключ API → Дешево → Безкоштовно |
-| 📊 **Відстеження квот у реальному часі** | Підрахунок живих токенів + скидання зворотного відліку для кожного постачальника |
-| 🔄 **Формат перекладу** | OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro seamless + відповідь санація |
-| 👥 **Підтримка кількох облікових записів** | Кілька облікових записів на постачальника з інтелектуальним вибором |
-| 🔄 **Автоматичне оновлення токенів** | Маркери OAuth оновлюються автоматично з повторною спробою |
-| 🎨 **Користувацькі комбо** | 6 стратегій: спочатку заповнює, циклічний, p2c, випадковий, найменш використовуваний, оптимізований за витратами |
-| 🧩 **Користувацькі моделі** | Додайте будь-який ідентифікатор моделі до будь-якого постачальника |
-| 🌐 **Wildcard Router** | Динамічно направляйте шаблони `provider/*` до будь-якого постачальника |
-| 🧠 **Мислення про бюджет** | Наскрізний, автоматичний, настроюваний і адаптивний режими для моделей міркування |
-| 🔀 **Model Aliases** | Auto-forward deprecated model IDs to current replacements (built-in + custom) |
-| ⚡ **Background Degradation** | Auto-route background tasks (titles, summaries) to cheaper models |
-| 💬 **Швидке впровадження системи** | Глобальне системне підказка застосовується до всіх запитів |
-| 📄 **API відповідей** | Повна підтримка OpenAI Responses API (`/v1/responses`) для Codex |
+> 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.
-### 🎵 Мультимодальні API
+### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)
-| Особливість | Що він робить |
-| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 🖼️ **Створення зображень** | `/v1/images/generations` — 4 провайдери, 9+ моделей |
-| 📐 **Вбудовування** | `/v1/embeddings` — 6 провайдерів, 9+ моделей |
-| 🎤 **Транскрипція аудіо** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |
-| 🔊 **Створення тексту в мовлення** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) |
-| 🛡️ **Модерації** | `/v1/moderations` — Перевірка безпеки вмісту |
-| 🔀 **Переранжування** | `/v1/rerank` — Переранжування релевантності документа |
+| 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 |
-### 🛡️ Стійкість і безпека
+### 🟢 IFLOW MODELS (Free OAuth — No Credit Card)
-| Особливість | Що він робить |
-| ------------------------------------- | ----------------------------------------------------------------------------------------------------- |
-| 🔌 **Автоматичний вимикач** | Автоматичне відкриття/закриття для кожного постачальника з настроюваними пороговими значеннями |
-| 🛡️ **Anti-Thundering Herd** | Mutex + обмеження швидкості семафора для постачальників ключів API |
-| 🧠 **Семантичний кеш** | Дворівневий кеш (підпис + семантика) зменшує вартість і затримку |
-| ⚡ **Запит на ідемпотентність** | 5-секундне вікно дедупляції для дублікатів запитів |
-| 🔒 **Підробка відбитків пальців TLS** | Обійти виявлення ботів на основі TLS через wreq-js |
-| 🌐 **IP-фільтрація** | Білий/чорний список для керування доступом API |
-| 📊 **Редаговані ліміти ставок** | Конфігурація RPM, мінімальний проміжок і максимальна одночасність на рівні системи |
-| 💾 **Rate Limit Persistence** | Learned limits survive restarts via SQLite with 60s debounce + 24h staleness |
-| 🔄 **Token Refresh Resilience** | Per-provider circuit breaker (5 fails→30min) + 30s timeout per attempt |
-| 🛡 **API Endpoint Protection** | Аутентифікація + блокування постачальника для кінцевої точки `/models` |
-| 🔒 **Видимість проксі** | Кольорові значки: 🟢 глобальний, 🟡 постачальник, 🔵 кожне підключення з відображенням IP |
-| 🌐 **3-рівнева конфігурація проксі** | Налаштуйте проксі-сервери на глобальному рівні, на рівні кожного постачальника чи кожного підключення |
+| 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 |
-### 📊 Спостережливість і аналітика
+### 🟡 QWEN MODELS (Device Code Auth)
-| Особливість | Що він робить |
-| ------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
-| 📝 **Подати запит на реєстрацію** | Режим налагодження з повними журналами запитів/відповідей |
-| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |
-| 💾 **Журнали проксі SQLite** | Постійні журнали проксі зберігаються після перезавантаження сервера |
-| 📊 **Інформаційна панель аналітики** | На основі Recharts: картки статистики, діаграма використання моделей, таблиця провайдерів |
-| 📈 **Відстеження прогресу** | Увімкніть події прогресу SSE для потокового передавання |
-| 🧪 **Оцінки LLM** | Тестування золотого набору з 4 стратегіями матчу |
-| 🔍 **Надіслати запит на телеметрію** | агрегація затримок p50/p95/p99 + трасування X-Request-Id |
-| 📋 **Інформаційна панель журналів** | Уніфікована сторінка з 4 вкладками: журнали запитів, журнали проксі, журнали аудиту, консоль |
-| 🖥️ **Перегляд журналу консолі** | Переглядач у режимі реального часу у стилі терміналу з фільтром рівнів, пошуком, автоматичним прокручуванням |
-| 📑 **Логування на основі файлів** | Перехоплювач консолі захоплює весь вихід у файл журналу JSON із обертанням |
-| 🏥 **Інформаційна панель здоров’я** | Час роботи системи, стани автоматичного вимикача, блокування, статистика кешу |
-| 💰 **Відстеження витрат** | Управління бюджетом + конфігурація ціноутворення для кожної моделі |
+| 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) |
-### ☁️ Розгортання та синхронізація
+### 🟣 GEMINI CLI (Google OAuth)
-| Особливість | Що він робить |
-| ------------------------------------------- | ----------------------------------------------------------------------------------- |
-| 💾 **Хмарна синхронізація** | Синхронізація конфігурації між пристроями через Cloudflare Workers |
-| 🌐 **Розгортайте будь-де** | Localhost, VPS, Docker, Cloudflare Workers |
-| 🔑 **Керування ключами API** | Генерувати, обертати та використовувати ключі API для кожного постачальника |
-| 🧙 **Майстер адаптації** | 4-етапне покрокове налаштування для користувачів, які вперше |
-| 🔧 **Інформаційна панель інструментів CLI** | Налаштувати в один клік Claude, Codex, Cline, OpenClaw, Kilo, Antigravity |
-| 🔄 **Резервне копіювання БД** | Автоматичне резервне копіювання, відновлення, експорт і імпорт для всіх налаштувань |
-| 🌐 **Інтернаціоналізація** | Повний i18n із next-intl — підтримка англійської та португальської (Бразилія) |
-| 🌍 **Вибір мови** | Значок глобуса в заголовку для перемикання мов у реальному часі (🇺🇸/🇧🇷) |
-| 🧹 **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 |
-| 📂 **Каталог користувацьких даних** | `DATA_DIR` змінна env для перевизначення типового шляху зберігання `~/.omniroute` |
+| Model | Prefix | Limit | Rate Limit |
+| ------------------------ | ------ | --------------------------- | ------------- |
+| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |
+| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |
+
+### ⚫ 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
+> iFlow (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 v2.0 is built as an operational platform, not just a relay proxy.
+
+### 🆕 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 Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |
+| 🤖 **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 (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) |
+| 🤝 **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** | 9 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 combo, apply resilience profiles, reset breakers from one control surface |
+
+### 🧠 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** | 6 balancing strategies + fallback chain control |
+| 🌐 **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) |
+| 💬 **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 |
+| ----------------------------------- | -------------------------------------------------------------------------------------- |
+| 🔌 **Circuit Breakers** | Per-model trip/recover with threshold controls |
+| 🎯 **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 |
+| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |
+| 🔑 **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 |
+
+### 📊 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 |
+| 📋 **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 |
+
+### ☁️ Deployment & Platform
+
+| Feature | What It Does |
+| ----------------------------- | --------------------------------------------------------- |
+| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |
+| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |
+| 💾 **Cloud Sync** | Configuration sync via cloud worker |
+| 🔄 **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 |
+
+### Feature Deep Dive
+
+#### Smart fallback with practical cost control
+
+```txt
+Combo: "my-coding-stack"
+ 1. cc/claude-opus-4-6
+ 2. nvidia/llama-3.3-70b
+ 3. glm/glm-4.7
+ 4. if/kimi-k2-thinking
+```
+
+When quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.
+
+#### 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)
+
+#### 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)
🚀 30. «Мені потрібно надсилати агентські робочі процеси без розповсюдження клею-коду»
+🚀 30. "I need to ship agentic workflows without glue-code sprawl"
-Команди втрачають швидкість під час з’єднання кількох спеціальних служб і сценаріїв. +Teams lose velocity when stitching multiple ad-hoc services and scripts. -**Як це вирішує OmniRoute:** +**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)
-` блоків → `reasoning_content` для моделей мислення
-- **Структурований вихід** — `json_schema` → Gemini `responseMimeType`/`responseSchema`
-
-### 👥 Підтримка кількох облікових записів
-
-- Додайте кілька облікових записів для кожного постачальника
-- Автоматична циклічна або пріоритетна маршрутизація
-- Повернення до наступного облікового запису, коли досягається квота
-
-### 🔄 Автоматичне оновлення токенів
-
-- Маркери OAuth автоматично оновлюються до закінчення терміну дії
-- Повторна автентифікація вручну не потрібна
-- Бездоганний досвід у всіх постачальників
-
-### 🎨 Спеціальні комбо
-
-- Створюйте необмежену кількість комбінацій моделей
-- 6 стратегій: спочатку заповнюй, циклічна, сила двох варіантів, випадкова, найменш використовувана, оптимізована за витратами
-- Діліться комбо на різних пристроях за допомогою Cloud Sync
-
-### 🏥 Інформаційна панель здоров'я
-
-- Статус системи (час роботи, версія, використання пам'яті)
-- Стани автоматичного вимикача для кожного постачальника (замкнуто/розімкнуто/напіврозімкнуто)
-- Статус обмеження швидкості та активні блокування
- — Статистика кешу підписів
-- Телеметрія затримки (p50/p95/p99) + кеш підказок
-- Скинути стан здоров'я одним клацанням миші
-
-### 🔧 Ігровий майданчик для перекладачів
-
-OmniRoute містить потужний вбудований Translator Playground із **4 режимами** для налагодження, тестування та моніторингу перекладів API:
-
-| Режим | Опис |
-| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **💻 Ігровий майданчик** | Прямий переклад формату — вставте будь-яке тіло запиту API та миттєво подивіться, як OmniRoute перекладає його між форматами постачальників (OpenAI ↔ Claude ↔ Gemini ↔ Responses API). Включає приклади шаблонів і автоматичне визначення формату. |
-| **💬 Тестер чату** | Надсилайте справжні запити в чат через OmniRoute і переглядайте повну інформацію: ваші дані, перекладений запит, відповідь постачальника та перекладену відповідь. Безцінний для перевірки комбінованої маршрутизації. |
-| **🧪 Тестовий стенд** | Режим пакетного тестування — визначте кілька тестів із різними вхідними та очікуваними результатами, запустіть їх усі одночасно та порівняйте результати між постачальниками та моделями. |
-| **📱 Live Monitor** | Моніторинг запитів у режимі реального часу — спостерігайте за вхідними запитами, коли вони проходять через OmniRoute, переглядайте трансляції форматів у реальному часі та миттєво виявляйте проблеми. |
-
-**Доступ:** Інформаційна панель → Перекладач (бічна панель)
-
-### 💾 Cloud Sync
-
-- Синхронізація постачальників, комбінацій і налаштувань на всіх пристроях
-- Автоматична фонова синхронізація
-- Безпечне зашифроване сховище
+- `GET /api/mcp/status`
+- `GET /api/mcp/tools`
+- `GET /api/mcp/audit`
+- `GET /api/mcp/audit/stats`
-## 🧪 Оцінки (Evals)
+📖 Деталі функції
+🧩 MCP Setup (Model Context Protocol)
-### 🎯 Smart 4-Tier Fallback +Start MCP transport in stdio mode: -Створюйте комбо з автоматичним резервним варіантом: - -``` -Combo: "my-coding-stack" - 1. cc/claude-opus-4-6 (your subscription) - 2. nvidia/llama-3.3-70b (free NVIDIA API) - 3. glm/glm-4.7 (cheap backup, $0.6/1M) - 4. if/kimi-k2-thinking (free fallback) - -→ Auto switches when quota runs out or errors occur +```bash +omniroute --mcp ``` -### 📊 Відстеження квот у реальному часі +Recommended validation flow: -- Споживання токенів на постачальника -- Скидання зворотного відліку (5 годин, щодня, щотижня) -- Оцінка вартості платних рівнів -- Щомісячні звіти про витрати +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: -Плавний переклад між форматами: - -- **OpenAI** ↔ **Клод** ↔ **Близнюки** ↔ **Відповіді OpenAI** -- Ваш інструмент CLI надсилає формат OpenAI → OmniRoute перекладає → Постачальник отримує рідний формат -- Працює з будь-яким інструментом, який підтримує спеціальні кінцеві точки OpenAI -- **Дезінфікація відповіді** — видаляє нестандартні поля для суворої сумісності з OpenAI SDK -- **Нормалізація ролі** — `developer` → `system` для не-OpenAI; `system` → `user` для моделей GLM/ERNIE -- **Вилучення тегів мислення** — `
+
🤝 A2A Setup (Agent2Agent)
-OmniRoute містить вбудовану систему оцінювання для перевірки якості відповіді LLM на відповідність золотому набору. Доступ до нього через **Аналітика → Оцінки** на інформаційній панелі. +Discover the agent: -### Вбудований Золотий набір +```bash +curl http://localhost:20128/.well-known/agent.json +``` -Попередньо завантажений "Золотий набір OmniRoute" містить 10 тестів, які охоплюють: +Send a task: -- Привітання, математика, географія, генерація коду -- Відповідність формату JSON, переклад, розмітка -- Відмова безпеки (шкідливий контент), підрахунок, булева логіка +```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."}]}}' +``` -### Стратегії оцінювання +Manage lifecycle: -| Стратегія | Опис | Приклад | -| ---------- | -------------------------------------------------------------- | -------------------------------- | -| `exact` | Вихідні дані повинні точно відповідати | `"4"` | -| `contains` | Вихідні дані повинні містити підрядок (незалежно від регістру) | `"Paris"` | -| `regex` | Вихідні дані мають відповідати шаблону регулярного виразу | `"1.*2.*3"` | -| `custom` | Спеціальна функція JS повертає true/false | `(output) => output.length > 10` | +- `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: + +```bash +npm run test:protocols:e2e +``` + +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) @@ -1070,7 +1438,7 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Професійна порада:** використовуйте Opus для складних завдань, Sonnet для швидкості. OmniRoute відстежує квоту на модель! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! ### OpenAI Codex (Plus/Pro) @@ -1084,7 +1452,24 @@ Models: cx/gpt-5.1-codex-max ``` -### Gemini CLI (БЕЗКОШТОВНО 180K/місяць!) +#### 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). + +### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -1096,9 +1481,9 @@ Models: gc/gemini-2.5-pro ``` -**Найкраще:** Величезний безкоштовний рівень! Використовуйте це перед платними рівнями. +**Best Value:** Huge free tier! Use this before paid tiers. -### Копілот GitHub +### GitHub Copilot ```bash Dashboard → Providers → Connect GitHub @@ -1114,88 +1499,88 @@ Models:
-
🔑 Постачальники ключів API
+🔑 API Key Providers
-### NVIDIA NIM (БЕЗКОШТОВНІ 1000 кредитів!) +### NVIDIA NIM (FREE developer access — 70+ models) -1. Зареєструйтесь: [build.nvidia.com](https://build.nvidia.com) -2. Отримайте безкоштовний ключ API (1000 кредитів включено) -3. Інформаційна панель → Додати постачальника → NVIDIA NIM: - - Ключ API: `nvapi-your-key` +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` -**Моделі:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct` та понад 50 інших +**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more -**Порада професіонала:** OpenAI-сумісний API — бездоганно працює з перекладом формату OmniRoute! +**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation! ### DeepSeek -1. Зареєструйтеся: [platform.deepseek.com](https://platform.deepseek.com) -2. Отримайте ключ API -3. Інформаційна панель → Додати постачальника → DeepSeek +1. Sign up: [platform.deepseek.com](https://platform.deepseek.com) +2. Get API key +3. Dashboard → Add Provider → DeepSeek -**Моделі:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` +**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` -### Groq (доступний безкоштовний рівень!) +### Groq (Free Tier Available!) -1. Зареєструйтеся: [console.groq.com](https://console.groq.com) -2. Отримайте ключ API (включає безкоштовний рівень) -3. Інформаційна панель → Додати постачальника → Groq +1. Sign up: [console.groq.com](https://console.groq.com) +2. Get API key (free tier included) +3. Dashboard → Add Provider → Groq -**Моделі:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` +**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` -**Професійна порада:** Надшвидкий висновок — найкращий для кодування в реальному часі! +**Pro Tip:** Ultra-fast inference — best for real-time coding! -### OpenRouter (100+ моделей) +### OpenRouter (100+ Models) -1. Зареєструйтеся: [openrouter.ai](https://openrouter.ai) -2. Отримайте ключ API -3. Інформаційна панель → Додати провайдера → OpenRouter +1. Sign up: [openrouter.ai](https://openrouter.ai) +2. Get API key +3. Dashboard → Add Provider → OpenRouter -**Моделі:** Отримуйте доступ до понад 100 моделей від усіх основних постачальників за допомогою єдиного ключа API. +**Models:** Access 100+ models from all major providers through a single API key.
-
💰 Дешеві постачальники (резервні)
+💰 Cheap Providers (Backup)
-### GLM-4.7 (щоденне скидання, $0,6/1 млн) +### GLM-4.7 (Daily reset, $0.6/1M) -1. Зареєструйтеся: [Zhipu AI](https://open.bigmodel.cn/) -2. Отримайте ключ API від Coding Plan -3. Інформаційна панель → Додати ключ API: - - Постачальник: `glm` - - Ключ API: `your-key` +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` -**Використовуйте:** `glm/glm-4.7` +**Use:** `glm/glm-4.7` -**Професійна порада:** План кодування пропонує 3x квоту за 1/7 вартості! Скидання щодня о 10:00. +**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -### MiniMax M2.1 (5 годин скидання, $0,20/1 млн) +### MiniMax M2.1 (5h reset, $0.20/1M) -1. Зареєструйтеся: [MiniMax](https://www.minimax.io/) -2. Отримайте ключ API -3. Інформаційна панель → Додати ключ API +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key +3. Dashboard → Add API Key -**Використовуйте:** `minimax/MiniMax-M2.1` +**Use:** `minimax/MiniMax-M2.1` -**Порада:** Найдешевший варіант для довгого контексту (1 млн токенів)! +**Pro Tip:** Cheapest option for long context (1M tokens)! -### Kimi K2 ($9/місяць) +### Kimi K2 ($9/month flat) -1. Підпишіться: [Moonshot AI](https://platform.moonshot.ai/) -2. Отримайте ключ API -3. Інформаційна панель → Додати ключ API +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key +3. Dashboard → Add API Key -**Використання:** `kimi/kimi-latest` +**Use:** `kimi/kimi-latest` -**Професійна порада:** Фіксовані 9 доларів США на місяць за 10 мільйонів токенів = 0,90 доларів США за 1 млн. ефективних витрат! +**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
-
🆓 БЕЗКОШТОВНІ постачальники (аварійне резервне копіювання)
+🆓 FREE Providers (Emergency Backup)
-### iFlow (8 БЕЗКОШТОВНИХ моделей) +### iFlow (5 FREE models via OAuth) ```bash Dashboard → Connect iFlow @@ -1210,7 +1595,7 @@ Models: if/deepseek-r1 ``` -### Qwen (3 БЕЗКОШТОВНІ моделі) +### Qwen (4 FREE models via Device Code) ```bash Dashboard → Connect Qwen @@ -1222,7 +1607,7 @@ Models: qw/qwen3-coder-flash ``` -### Кіро (Клод БЕЗКОШТОВНО) +### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro @@ -1237,9 +1622,9 @@ Models:
-
🎨 Створення комбо
+🎨 Create Combos
-### Приклад 1: максимізація підписки → дешеве резервне копіювання +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -1253,7 +1638,7 @@ Models: Use in CLI: premium-coding ``` -### Приклад 2: лише безкоштовно (нульова вартість) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -1268,9 +1653,9 @@ Cost: $0 forever!
-
---
-## 🐛 Усунення несправностей
+## Усунення несправностей
🔧 Інтеграція CLI
+🔧 CLI Integration
-### Курсор IDE +### Cursor IDE ``` Settings → Models → Advanced: @@ -1279,9 +1664,9 @@ Settings → Models → Advanced: Model: cc/claude-opus-4-6 ``` -### Клод Код +### Claude Code -Використовуйте сторінку **Інструменти CLI** на інформаційній панелі для налаштування одним клацанням миші або редагуйте `~/.claude/settings.json` вручну. +Use the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually. ### Codex CLI @@ -1294,13 +1679,13 @@ codex "your prompt" ### OpenClaw -**Варіант 1 — Інформаційна панель (рекомендовано):** +**Option 1 — Dashboard (recommended):** ``` Dashboard → CLI Tools → OpenClaw → Select Model → Apply ``` -**Варіант 2 — вручну:** Редагувати `~/.openclaw/openclaw.json`: +**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`: ```json { @@ -1316,9 +1701,9 @@ Dashboard → CLI Tools → OpenClaw → Select Model → Apply } ``` -> **Примітка:** OpenClaw працює лише з локальним OmniRoute. Використовуйте `127.0.0.1` замість `localhost`, щоб уникнути проблем із вирішенням IPv6. +> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues. -### Cline / Продовжити / RooCode +### Cline / Continue / RooCode ``` Settings → API Configuration: @@ -1328,112 +1713,245 @@ Settings → API Configuration: 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. +
- Hạn mức đăng ký hết hạn không được sử dụng hàng tháng
-- Giới hạn tốc độ khiến bạn không thể viết mã giữa chừng
-- API đắt tiền ($20-50/tháng cho mỗi nhà cung cấp)
-- Chuyển đổi thủ công giữa các nhà cung cấp
-
-**OmniRoute giải quyết vấn đề này:**
-
-- ✅ **Tối đa hóa số lượt đăng ký** - Theo dõi hạn ngạch, sử dụng từng bit trước khi đặt lại
-- ✅ **Tự động dự phòng** - Đăng ký → Khóa API → Giá rẻ → Miễn phí, không có thời gian ngừng hoạt động
-- ✅ **Nhiều tài khoản** - Luân chuyển giữa các tài khoản cho mỗi nhà cung cấp
-- ✅ **Universal** - Hoạt động với Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, mọi công cụ CLI
-
----
-
-## 📧 Hỗ trợ
-
-> 💬 **Tham gia cộng đồng của chúng tôi!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Nhận trợ giúp, chia sẻ mẹo và luôn cập nhật.
-
-- **Trang web**: [omniroute.online](https://omniroute.online)
+- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Vấn đề**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Dự án gốc**: [9router by decolua](https://github.com/decolua/9router)
+- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 Nó hoạt động như thế nào
+## 🔄 How It Works
```
┌─────────────┐
@@ -227,452 +236,453 @@ Result: Never stop coding, minimal cost
---
-## 🎯 OmniRoute giải quyết được gì — 30 điểm khó thực sự và trường hợp sử dụng
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **Mọi nhà phát triển sử dụng công cụ AI đều phải đối mặt với những vấn đề này hàng ngày.** OmniRoute được xây dựng để giải quyết tất cả — từ chi phí vượt mức cho đến chặn khu vực, từ luồng OAuth bị hỏng đến hoạt động giao thức và khả năng quan sát của doanh nghiệp.
+> **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.
订阅配额每月未使用就过期
-- 速率限制在编程中途停止你
-- 昂贵的 API（每个提供商 $20-50/月）
-- 手动在提供商间切换
-
-**OmniRoute 解决这些问题：**
-
-- ✅ **最大化订阅** — 追踪配额，在重置前用完每一点
-- ✅ **自动故障转移** — 订阅 → API Key → 低价 → 免费，零停机
-- ✅ **多账号** — 每个提供商的账号轮询
-- ✅ **通用** — 适用于 Claude Code、Codex、Gemini CLI、Cursor、Cline、OpenClaw、任何 CLI 工具
-
----
-
-## 📧 支持
-
-> 💬 **加入我们的社区！** [WhatsApp 群组](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — 获取帮助、分享技巧、了解最新动态。
-
-- **网站**: [omniroute.online](https://omniroute.online)
+- **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**: [社区群组](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **原始项目**: [decolua 的 9router](https://github.com/decolua/9router)
+- **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`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 工作原理
+## 🔄 How It Works
```
┌─────────────┐
-│ 您的 CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
-│ 工具 │
+│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
+│ Tool │
└──────┬──────┘
│ http://localhost:20128/v1
↓
┌─────────────────────────────────────────┐
-│ OmniRoute（智能路由器） │
-│ • 格式转换（OpenAI ↔ Claude） │
-│ • 配额追踪 + Embeddings + 图像 │
-│ • 自动令牌刷新 │
+│ OmniRoute (Smart Router) │
+│ • Format translation (OpenAI ↔ Claude) │
+│ • Quota tracking + Embeddings + Images │
+│ • Auto token refresh │
└──────┬──────────────────────────────────┘
│
- ├─→ [第1层: 订阅] Claude Code, Codex, Gemini CLI
- │ ↓ 配额用完
- ├─→ [第2层: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM 等
- │ ↓ 预算限制
- ├─→ [第3层: 低价] GLM ($0.6/1M), MiniMax ($0.2/1M)
- │ ↓ 预算限制
- └─→ [第4层: 免费] iFlow, Qwen, Kiro（无限制）
+ ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI
+ │ ↓ 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] iFlow, Qwen, Kiro (unlimited)
-结果：永不停止编程，成本最低
+Result: Never stop coding, minimal cost
```
---
-## 🎯 OmniRoute 解决了什么 — 30 个真正的痛点和用例
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **每个使用 AI 工具的开发人员每天都会面临这些问题。** OmniRoute 的构建是为了解决所有这些问题 - 从成本超支到区域封锁，从损坏的 OAuth 流程到协议操作和企业可观察性。
+> **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.
Натисніть, щоб розгорнути посібник з усунення несправностей
+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** -— Вичерпана квота на підписку → Повернення до GLM/MiniMax +- Subscription quota out → Fallback to GLM/MiniMax +- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -- Додати комбо: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +**OAuth token expired** -**Термін дії маркера OAuth минув** +- Auto-refreshed by OmniRoute +- If issues persist: Dashboard → Provider → Reconnect -— Автоматично оновлено OmniRoute +**High costs** -- Якщо проблеми не зникають: Інформаційна панель → Постачальник → Повторне підключення +- Check usage stats in Dashboard → Costs +- Switch primary model to GLM/MiniMax +- Use free tier (Gemini CLI, iFlow) for non-critical tasks -**Високі витрати** +**Dashboard/API ports are wrong** -- Перевірте статистику використання в Інформаційній панелі → Витрати -- Переключіть основну модель на GLM/MiniMax -- Використовуйте безкоштовний рівень (Gemini CLI, iFlow) для некритичних завдань +- `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** -- Встановити `PORT=20128` та `NEXT_PUBLIC_BASE_URL=http://localhost:20128` +- 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** -- Переконайтеся, що `BASE_URL` вказує на ваш запущений екземпляр -- Перевірте `CLOUD_URL` вказує на очікувану кінцеву точку хмари -- Зберігайте значення `NEXT_PUBLIC_*` у відповідності зі значеннями на стороні сервера +- Check `INITIAL_PASSWORD` in `.env` +- If unset, fallback password is `123456` -**Перший вхід не працює** +**No request logs** -- Перевірте `INITIAL_PASSWORD` в `.env` -- Якщо не встановлено, резервний пароль – `123456` +- Set `ENABLE_REQUEST_LOGS=true` in `.env` -**Немає журналів запитів** +**Connection test shows "Invalid" for OpenAI-compatible providers** -- Установіть `ENABLE_REQUEST_LOGS=true` в `.env` +- Many providers don't expose a `/models` endpoint +- OmniRoute v1.0.6+ includes fallback validation via chat completions +- Ensure base URL includes `/v1` suffix -**Тест з’єднання показує «Недійсне» для OpenAI-сумісних постачальників** - -- Багато постачальників не розкривають кінцеву точку `/models` -- OmniRoute v1.0.6+ включає резервну перевірку через завершення чату -- Переконайтеся, що базова URL-адреса містить суфікс `/v1` - -### 🔐 OAuth +### 🔐 OAuth on a Remote Server + -> **⚠️ ВАЖЛИВО для використання OmniRoute у віддаленому VPS/Docker/сервері** +> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server** -### OAuth +#### Why does Antigravity / Gemini CLI OAuth fail on remote servers? -Провідники **Antigravity** і **Gemini CLI** використовують **Google OAuth 2.0** для автентифікації. Google вимагає, щоб `redirect_uri` не використовував fluxo OAuth, який **exatamente** має URI перед кадастрадами без додатка Google Cloud Console. +The **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console. -Оскільки повноваження OAuth embutidas, OmniRoute не встановлено в кадастрадах **apenas para `localhost`**. Якщо ви маєте доступ до OmniRoute у віддаленому сервері (наприклад: `https://omniroute.meuservidor.com`), або Google rejeita a autenticação com: +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 ``` -### Рішення: налаштуйте власні облікові записи OAuth +#### Solution: Configure your own OAuth credentials -Потрібно точно написати **Ідентифікатор клієнта OAuth 2.0** у Google Cloud Console через URI вашого сервера. +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 + +# For Gemini CLI: +GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com +GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +``` + +**6. Restart OmniRoute** + +```bash +# npm: +npm run dev + +# Docker: +docker restart omniroute +``` + +**7. Try connecting again** + +Dashboard → Providers → Antigravity (or Gemini CLI) → OAuth + +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. + +--- + +
+
-- **Серед виконання**: Node.js 18–22 LTS (⚠️ Node.js 24+ **не підтримується** — рідні двійкові файли `better-sqlite3` несумісні)
-- **Мова**: TypeScript 5.9 — **100% TypeScript** для `src/` та `open-sse/` (версія 1.0.6)
-- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4
-- **База даних**: LowDB (JSON) + SQLite (стан домену + журнали проксі)
-- **Потокове передавання**: події, надіслані сервером (SSE)
-- **Auth**: OAuth 2.0 (PKCE) + JWT + ключі API
-- **Тестування**: програма для тестування Node.js (368+ модульних тестів)
-- **CI/CD**: дії GitHub (автоматична публікація npm + Docker Hub після випуску)
-- **Веб-сайт**: [omniroute.online](https://omniroute.online)
-- **Пакет**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
-- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
-- **Стійкість**: автоматичний вимикач, експоненціальна віддача, захист від громового стада, підробка TLS
-
----
-
-## 📖 Документація
-
-| Документ | Опис |
-| -------------------------------------------- | ----------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Постачальники, комбо, інтеграція CLI, розгортання |
-| [API Reference](docs/API_REFERENCE.md) | Усі кінцеві точки з прикладами |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Загальні проблеми та рішення |
-| [Architecture](docs/ARCHITECTURE.md) | Архітектура системи та внутрішні |
-| [Contributing](CONTRIBUTING.md) | Розробка установки та рекомендацій |
-| [OpenAPI Spec](docs/openapi.yaml) | Специфікація OpenAPI 3.0 |
-| [Security Policy](SECURITY.md) | Повідомлення про вразливості та методи безпеки |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Повний посібник: налаштування VM + nginx + Cloudflare |
-| [Features Gallery](docs/FEATURES.md) | Огляд інформаційної панелі зі знімками екрана |
-
-### 📸 Попередній перегляд інформаційної панелі
+## 🛠️ Tech Stack
🇧🇷 Versão em Português
+ +#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos? + +Os provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo. + +As credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticação com: + +``` +Error 400: redirect_uri_mismatch +``` + +#### Solução: Configure suas próprias credenciais OAuth + +Você precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor. #### Passo a passo -**1. Доступ до Google Cloud Console** +**1. Acesse o Google Cloud Console** Abra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) -**2. Crie um novo OAuth 2.0 ID клієнта** +**2. Crie um novo OAuth 2.0 Client ID** -- Натисніть **"+ Створити облікові дані"** → **"Ідентифікатор клієнта OAuth"** -- Tipo de aplicativo: **"Веб-програма"** -- Назва: escolha qualquer nome (наприклад: `OmniRoute Remote`) +- Clique em **"+ Create Credentials"** → **"OAuth client ID"** +- Tipo de aplicativo: **"Web application"** +- Nome: escolha qualquer nome (ex: `OmniRoute Remote`) -**3. Додайте як авторизовані URI перенаправлення** +**3. Adicione as Authorized Redirect URIs** -Без поля **"Авторизовані URI перенаправлення"**, додайте: +No campo **"Authorized redirect URIs"**, adicione: ``` https://seu-servidor.com/callback ``` -> Замініть `seu-servidor.com` домен або IP на свій сервер (включно з необхідним портом, наприклад: `http://45.33.32.156:20128/callback`). +> Substitua `seu-servidor.com` pelo domínio ou IP do seu servidor (inclua a porta se necessário, ex: `http://45.33.32.156:20128/callback`). -**4. Зберегти електронну копію як ідентифікацію** +**4. Salve e copie as credenciais** -Наприклад, Google показує **Ідентифікатор клієнта** і **Секрет клієнта**. +Após criar, o Google mostrará o **Client ID** e o **Client Secret**. -**5. Налаштувати як variáveis de ambiente** +**5. Configure as variáveis de ambiente** -Немає `.env` (або наших варіантів середовища Docker): +No seu `.env` (ou nas variáveis de ambiente do Docker): ```bash # Para Antigravity: @@ -1458,21 +1976,21 @@ docker restart omniroute **7. Tente conectar novamente** -Інформаційна панель → Постачальники → Антигравітація (або Gemini CLI) → OAuth +Dashboard → Providers → Antigravity (ou Gemini CLI) → OAuth -Agora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a authenticação funcionará. +Agora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará. --- -### Тимчасове вирішення проблеми (необхідне налаштування облікових записів) +#### Workaround temporário (sem configurar credenciais próprias) Se não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**: -1. OmniRoute скидає URL-адресу авторизації Google -2. Якщо ви авторизуєтеся, перенаправлення даних Google для `localhost` (неможливо віддалено від сервера) -3. **Скопіюйте повну URL-адресу** для переходу до вашого браузера (повідомте, що сторінка не створена) +1. O OmniRoute abrirá a URL de autorização do Google +2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto) +3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue) 4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute -5. Натисніть **"Підключити"** +5. Clique em **"Connect"** > Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não. @@ -1480,128 +1998,123 @@ Se não quiser criar credenciais próprias agora, ainda é possível usar o flux --- -## 🛠️ +
-
---
-## 🗺️
+## Документація
-OmniRoute має **заплановано понад 210 функцій** на кількох етапах розробки. Ось ключові області:
-
-| Категорія | Заплановані особливості | Основні моменти |
-| -------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| 🧠 **Маршрутизація та інтелект** | 25+ | Маршрутизація з найменшою затримкою, маршрутизація на основі тегів, попередній перегляд квот, вибір облікового запису P2C |
-| 🔒 **Безпека та відповідність** | 20+ | Захист SSRF, маскування облікових даних, обмеження швидкості для кінцевої точки, визначення обсягу ключа керування |
-| 📊 **Спостережливість** | 15+ | Інтеграція OpenTelemetry, моніторинг квот у реальному часі, відстеження витрат на модель |
-| 🔄 **Інтеграція постачальників** | 20+ | Реєстр динамічної моделі, час відновлення провайдера, Codex із кількома обліковими записами, розбір квоти Copilot |
-| ⚡ **Виконання** | 15+ | Подвійний рівень кешу, кеш запитів, кеш відповідей, потокове підтримання активності, пакетний API |
-| 🌐 **Екосистема** | 10+ | API WebSocket, гаряче перезавантаження конфігурації, розподілене сховище конфігурацій, комерційний режим |
-
-### 🔜 Незабаром
-
-- 🔗 **Інтеграція OpenCode** — власна підтримка постачальника для IDE кодування OpenCode AI
-- 🔗 **Інтеграція TRAE** — повна підтримка інфраструктури розробки TRAE AI
-- 📦 **Batch API** — асинхронна пакетна обробка масових запитів
-- 🎯 **Маршрутизація на основі тегів** — Маршрутизація запитів на основі спеціальних тегів і метаданих
-- 💰 **Стратегія найнижчої вартості** — автоматично вибирайте найдешевшого доступного постачальника
-
-> 📝 Повні специфікації функцій доступні в [link](docs/new-features/) (217 детальних специфікацій)
+| Document | Description |
+| ---------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 16 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/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
+| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
-## 👥 Автори
+## 🗺️ Roadmap
+
+OmniRoute has **210+ 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, P2C account selection |
+| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |
+| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |
+| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider 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
[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
-### Як зробити внесок
+### How to Contribute
-1. Розгалужте репозиторій
-2. Створіть свою гілку функцій (`git checkout -b feature/amazing-feature`)
-3. Зафіксуйте свої зміни (`git commit -m 'Add amazing feature'`)
-4. Push до відділення (`git push origin feature/amazing-feature`)
-5. Відкрийте Pull Request
+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
-Див. [CONTRIBUTING.md](CONTRIBUTING.md), щоб отримати докладні вказівки.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
-### Випуск нової версії
+### Releasing a New Version
```bash
# Create a release — npm publish happens automatically
-gh release create v1.0.6 --title "v1.0.6" --generate-notes
+gh release create v2.0.0 --title "v2.0.0" --generate-notes
```
---
-## 📊 Зоряна історія
+## 📊 Star History
## Stargazers over time
## [](https://starchart.cc/diegosouzapw/OmniRoute)
-## 🙏 Подяка
+## 🙏 Acknowledgments
-Особлива подяка **[9router](https://github.com/decolua/9router)** від **[decolua](https://github.com/decolua)** — оригінального проекту, який надихнув цей форк. OmniRoute спирається на цю неймовірну основу завдяки додатковим функціям, мультимодальним API і повному перепису TypeScript.
+Special thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.
-Особлива подяка **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — оригінальній реалізації Go, яка надихнула цей порт JavaScript.
+Special thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.
---
-## 📄 Ліцензія
+## Ліцензія
-Ліцензія Массачусетського технологічного інституту – подробиці див. [LICENSE](LICENSE).
+MIT License - see [LICENSE](LICENSE) for details.
---
Натисніть, щоб переглянути знімки панелі інструментів
+Click to expand tech stack details
-| Сторінка | Скріншот | -| ------------------------ | ------------------------------------------------- | -| **Постачальники** |  | -| **Комбінації** |  | -| **Аналітика** |  | -| **Здоров'я** |  | -| **Перекладач** |  | -| **Налаштування** |  | -| **Інструменти CLI** |  | -| **Журнали використання** |  | -| **Кінцева точка** |  | +- **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**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions) +- **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
- Створено з ❤️ для розробників, які працюють у режимі 24/7
+ Built with ❤️ for developers who code 24/7
omniroute.online
+
diff --git a/docs/i18n/uk-UA/docs/FEATURES.md b/docs/i18n/uk-UA/docs/FEATURES.md
new file mode 100644
index 0000000000..68b009832d
--- /dev/null
+++ b/docs/i18n/uk-UA/docs/FEATURES.md
@@ -0,0 +1,145 @@
+# OmniRoute — Dashboard Features Gallery (Українська)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/FEATURES.md) · 🇪🇸 [es](../../es/docs/FEATURES.md) · 🇫🇷 [fr](../../fr/docs/FEATURES.md) · 🇩🇪 [de](../../de/docs/FEATURES.md) · 🇮🇹 [it](../../it/docs/FEATURES.md) · 🇷🇺 [ru](../../ru/docs/FEATURES.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FEATURES.md) · 🇯🇵 [ja](../../ja/docs/FEATURES.md) · 🇰🇷 [ko](../../ko/docs/FEATURES.md) · 🇸🇦 [ar](../../ar/docs/FEATURES.md) · 🇮🇳 [in](../../in/docs/FEATURES.md) · 🇹🇭 [th](../../th/docs/FEATURES.md) · 🇻🇳 [vi](../../vi/docs/FEATURES.md) · 🇮🇩 [id](../../id/docs/FEATURES.md) · 🇲🇾 [ms](../../ms/docs/FEATURES.md) · 🇳🇱 [nl](../../nl/docs/FEATURES.md) · 🇵🇱 [pl](../../pl/docs/FEATURES.md) · 🇸🇪 [sv](../../sv/docs/FEATURES.md) · 🇳🇴 [no](../../no/docs/FEATURES.md) · 🇩🇰 [da](../../da/docs/FEATURES.md) · 🇫🇮 [fi](../../fi/docs/FEATURES.md) · 🇵🇹 [pt](../../pt/docs/FEATURES.md) · 🇷🇴 [ro](../../ro/docs/FEATURES.md) · 🇭🇺 [hu](../../hu/docs/FEATURES.md) · 🇧🇬 [bg](../../bg/docs/FEATURES.md) · 🇸🇰 [sk](../../sk/docs/FEATURES.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FEATURES.md) · 🇮🇱 [he](../../he/docs/FEATURES.md) · 🇵🇭 [phi](../../phi/docs/FEATURES.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FEATURES.md)
+
+---
+
+Visual guide to every section of the OmniRoute dashboard.
+
+---
+
+## 🔌 Providers
+
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
+
+
+
+---
+
+## 🎨 Combos
+
+Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
+
+
+
+---
+
+## 📊 Analytics
+
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
+
+
+
+---
+
+## 🏥 System Health
+
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+
+
+
+---
+
+## 🔧 Translator Playground
+
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
+
+
+
+---
+
+## 🎮 Model Playground _(v2.0.9+)_
+
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
+
+---
+
+## 🎨 Themes _(v2.0.5+)_
+
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
+
+## ⚙️ Settings
+
+Comprehensive settings panel with tabs:
+
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning
+- **Advanced** — Configuration overrides
+
+
+
+---
+
+## 🔧 CLI Tools
+
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
+
+
+
+---
+
+## 🤖 CLI Agents _(v2.0.11+)_
+
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
+
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
+
+---
+
+## 🖼️ Media _(v2.0.3+)_
+
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
+
+## 📝 Request Logs
+
+Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
+
+
+
+---
+
+## 🌐 API Endpoint
+
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
+
+
+
+---
+
+## 🔑 API Key Management
+
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
+
+---
+
+## 📋 Audit Log
+
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
+
+---
+
+## 🖥️ Desktop Application
+
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
+
+Key features:
+
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
+
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.
diff --git a/docs/i18n/vi/README.md b/docs/i18n/vi/README.md
index ab1daaa815..4611c26358 100644
--- a/docs/i18n/vi/README.md
+++ b/docs/i18n/vi/README.md
@@ -1,24 +1,94 @@
-omniroute.online
-
-
- # 🚀 OmniRoute — Cổng AI miễn phí
+# 🚀 OmniRoute — The Free AI Gateway (Tiếng Việt)
-### Không bao giờ ngừng viết mã. Định tuyến thông minh tới **Mô hình AI MIỄN PHÍ và chi phí thấp** với tính năng dự phòng tự động.
-
-_Proxy API phổ quát của bạn — một điểm cuối, hơn 36 nhà cung cấp, không có thời gian ngừng hoạt động._
-
-**Hoàn thành cuộc trò chuyện • Nhúng • Tạo hình ảnh • Âm thanh • Sắp xếp lại • 100% TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Nhà cung cấp AI miễn phí cho các tác nhân mã hóa yêu thích của bạn
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Kết nối mọi công cụ IDE hoặc CLI được hỗ trợ bởi AI thông qua OmniRoute — cổng API miễn phí để mã hóa không giới hạn._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+` tags no longer leak to clients in SSE streaming responses (#585) |
+| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with per-provider/account quota enforcement, idempotency, SHA-256 storage, and optional GitHub issue reporting |
+| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG → generic fallback chain |
+| 🔄 **Model Auto-Sync** | 24h scheduler and manual UI toggle to sync model lists for built-in and custom OpenAI-compatible providers |
+| 🌐 **OpenCode Zen/Go** | Two new providers from @kang-heewon via PR #530: free tier + subscription tier via `OpencodeExecutor` |
+| 🐛 **Gemini CLI OAuth** | Actionable error when `GEMINI_OAUTH_CLIENT_SECRET` is missing in Docker (was cryptic Google error) |
+| 🐛 **OpenCode config** | `saveOpenCodeConfig()` now correctly writes TOML to `XDG_CONFIG_HOME` |
+| 🐛 **Pinned model override** | `body.model` correctly set to `pinnedModel` on context-cache protection |
+| 🐛 **Codex/Claude loop** | `tool_result` blocks now converted to text to stop infinite loops |
+| 🐛 **Login redirect** | Login no longer freezes after skipping password setup |
+| 🐛 **Windows paths** | MSYS2/Git-Bash paths (`/c/...`) normalized to `C:\...` automatically |
+
+---
+
+## 🖼️ Main Dashboard
+
+
-📡 Tất cả đại lý kết nối qua ` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**Stop wasting money and hitting limits:**
-### 🆕 What's New in v3.0.0
+- Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**OmniRoute solves this:**
+
+- ✅ **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
+- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool
---
-[](https://www.npmjs.com/package/omniroute)
-[](https://hub.docker.com/r/diegosouzapw/omniroute)
-[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
-[](https://omniroute.online)
-[](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
+## 📧 Support
-[🌐 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)
+> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.
-🌐 **Available in:** 🇺🇸 [English](../../README.md) | 🇧🇷 [Português (Brasil)](../pt-BR/README.md) | 🇪🇸 [Español](../es/README.md) | 🇫🇷 [Français](../fr/README.md) | 🇮🇹 [Italiano](../it/README.md) | 🇷🇺 [Русский](../ru/README.md) | 🇨🇳 [中文 (简体)](../zh-CN/README.md) | 🇩🇪 [Deutsch](../de/README.md) | 🇮🇳 [हिन्दी](../in/README.md) | 🇹🇭 [ไทย](../th/README.md) | 🇺🇦 [Українська](../uk-UA/README.md) | 🇸🇦 [العربية](../ar/README.md) | 🇯🇵 [日本語](../ja/README.md) | 🇻🇳 [Tiếng Việt](../vi/README.md) | 🇧🇬 [Български](../bg/README.md) | 🇩🇰 [Dansk](../da/README.md) | 🇫🇮 [Suomi](../fi/README.md) | 🇮🇱 [עברית](../he/README.md) | 🇭🇺 [Magyar](../hu/README.md) | 🇮🇩 [Bahasa Indonesia](../id/README.md) | 🇰🇷 [한국어](../ko/README.md) | 🇲🇾 [Bahasa Melayu](../ms/README.md) | 🇳🇱 [Nederlands](../nl/README.md) | 🇳🇴 [Norsk](../no/README.md) | 🇵🇹 [Português (Portugal)](../pt/README.md) | 🇷🇴 [Română](../ro/README.md) | 🇵🇱 [Polski](../pl/README.md) | 🇸🇰 [Slovenčina](../sk/README.md) | 🇸🇪 [Svenska](../sv/README.md) | 🇵🇭 [Filipino](../phi/README.md)
-
-
-
----
-
-## 🖼️
-
-
-
- # 🚀 OmniRoute — Cổng AI miễn phí
+# 🚀 OmniRoute — The Free AI Gateway (Tiếng Việt)
-### Không bao giờ ngừng viết mã. Định tuyến thông minh tới **Mô hình AI MIỄN PHÍ và chi phí thấp** với tính năng dự phòng tự động.
-
-_Proxy API phổ quát của bạn — một điểm cuối, hơn 36 nhà cung cấp, không có thời gian ngừng hoạt động._
-
-**Hoàn thành cuộc trò chuyện • Nhúng • Tạo hình ảnh • Âm thanh • Sắp xếp lại • 100% TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 Nhà cung cấp AI miễn phí cho các tác nhân mã hóa yêu thích của bạn
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_Kết nối mọi công cụ IDE hoặc CLI được hỗ trợ bởi AI thông qua OmniRoute — cổng API miễn phí để mã hóa không giới hạn._
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+
+
+[](https://www.npmjs.com/package/omniroute)
+[](https://www.npmjs.com/package/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
+[](https://omniroute.online)
+[](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)
+
+
+
+🌐 **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)
+
+---
+
+## 🆕 What's New in v3.0.0
+
+> **Upgrading from v2.9.5?** — See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes.
+
+| Area | Change |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection remediation |
+| ✅ **Route Validation** | All 176 API routes now validated with Zod schemas + `validateBody()` — CI `check:route-validation:t06` passes |
+| 🐛 **omniModel Tag Leak** | Internal `
+
+
+
+---
+
+## 📸 Dashboard Preview
+
+
+
+
+
+---
+
+### 🤖 Free AI Provider for your favorite coding agents
+
+_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._
Click to see dashboard screenshots
+ +| Page | Screenshot | +| -------------- | ------------------------------------------------- | +| **Providers** |  | +| **Combos** |  | +| **Analytics** |  | +| **Health** |  | +| **Translator** |  | +| **Settings** |  | +| **CLI Tools** |  | +| **Usage Logs** |  | +| **Endpoints** |  | + +|
-
+
OpenClaw @@ -92,113 +162,52 @@ _Kết nối mọi công cụ IDE hoặc CLI được hỗ trợ bởi AI thông |
http://localhost:20128/v1 hoặc http://cloud.omniroute.online/v1 — một cấu hình, số mô hình và hạn ngạch không giới hạn
+📡 All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 — one config, unlimited models and quota
---
-### 🆕 What's New in v3.0.0
+## 🤔 Why OmniRoute?
-| Area | Change |
-| ------------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal ` Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `
-
-
-
----
-
-## 📸
-
-
-
-
-
----
-
-## 🤔 Tại sao lại là OmniRoute?
-
-**Ngưng lãng phí tiền và đạt đến giới hạn:**
-
-- ...
- -| # | # | -| ----- | ---------------------------------------- | -| **1** |  | -| **2** |  | -| **3** |  | -| **4** |  | -| **5** |  | -| **6** |  | -| **7** |  | -| **8** |  | -| **9** |  | - - Hạn mức đăng ký hết hạn không được sử dụng hàng tháng
-- Giới hạn tốc độ khiến bạn không thể viết mã giữa chừng
-- API đắt tiền ($20-50/tháng cho mỗi nhà cung cấp)
-- Chuyển đổi thủ công giữa các nhà cung cấp
-
-**OmniRoute giải quyết vấn đề này:**
-
-- ✅ **Tối đa hóa số lượt đăng ký** - Theo dõi hạn ngạch, sử dụng từng bit trước khi đặt lại
-- ✅ **Tự động dự phòng** - Đăng ký → Khóa API → Giá rẻ → Miễn phí, không có thời gian ngừng hoạt động
-- ✅ **Nhiều tài khoản** - Luân chuyển giữa các tài khoản cho mỗi nhà cung cấp
-- ✅ **Universal** - Hoạt động với Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, mọi công cụ CLI
-
----
-
-## 📧 Hỗ trợ
-
-> 💬 **Tham gia cộng đồng của chúng tôi!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Nhận trợ giúp, chia sẻ mẹo và luôn cập nhật.
-
-- **Trang web**: [omniroute.online](https://omniroute.online)
+- **Website**: [omniroute.online](https://omniroute.online)
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
-- **Vấn đề**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **Dự án gốc**: [9router by decolua](https://github.com/decolua/9router)
+- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 Nó hoạt động như thế nào
+## 🔄 How It Works
```
┌─────────────┐
@@ -227,452 +236,453 @@ Result: Never stop coding, minimal cost
---
-## 🎯 OmniRoute giải quyết được gì — 30 điểm khó thực sự và trường hợp sử dụng
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **Mọi nhà phát triển sử dụng công cụ AI đều phải đối mặt với những vấn đề này hàng ngày.** OmniRoute được xây dựng để giải quyết tất cả — từ chi phí vượt mức cho đến chặn khu vực, từ luồng OAuth bị hỏng đến hoạt động giao thức và khả năng quan sát của doanh nghiệp.
+> **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.
-
💸 1. "Tôi trả tiền cho một thuê bao đắt tiền nhưng vẫn bị gián đoạn bởi các giới hạn"
+💸 1. "I pay for an expensive subscription but still get interrupted by limits"
-Các nhà phát triển trả 20–200 USD/tháng cho Claude Pro, Codex Pro hoặc GitHub Copilot. Ngay cả khi trả tiền, hạn ngạch vẫn có mức trần - 5 giờ sử dụng, giới hạn hàng tuần hoặc giới hạn tốc độ mỗi phút. Giữa phiên mã hóa, nhà cung cấp ngừng phản hồi và nhà phát triển mất đi dòng chảy và năng suất. +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. -**Cách OmniRoute giải quyết vấn đề này:** +**How OmniRoute solves it:** -- **Dự phòng 4 tầng thông minh** — Nếu hết hạn ngạch đăng ký, tự động chuyển hướng đến Khóa API → Giá rẻ → Miễn phí mà không cần can thiệp thủ công -- **Theo dõi hạn ngạch theo thời gian thực** — Hiển thị mức tiêu thụ mã thông báo trong thời gian thực với tính năng đếm ngược đặt lại (5 giờ, hàng ngày, hàng tuần) -- **Hỗ trợ nhiều tài khoản** — Nhiều tài khoản cho mỗi nhà cung cấp với tính năng tự động quay vòng — khi hết một tài khoản, hãy chuyển sang tài khoản tiếp theo -- **Combo tùy chỉnh** — Chuỗi dự phòng có thể tùy chỉnh với 6 chiến lược cân bằng (điền trước, quay vòng, P2C, ngẫu nhiên, ít sử dụng nhất, tối ưu hóa chi phí) -- **Hạn ngạch kinh doanh Codex** — Giám sát hạn ngạch không gian làm việc của Doanh nghiệp/Nhóm trực tiếp trong bảng điều khiển +- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention +- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly) +- **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 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
-` từ các mô hình như DeepSeek R1 thành `reasoning_content` được tiêu chuẩn hóa
-- **Đầu ra có cấu trúc cho Gemini** — `json_schema` → `responseMimeType`/`responseSchema` chuyển đổi tự động
-- **`stream` mặc định là `false`** — Phù hợp với thông số OpenAI, tránh SSE không mong muốn trong SDK Python/Rust/Go
+- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 67+ 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
🔌 2. "Tôi cần sử dụng nhiều nhà cung cấp nhưng mỗi nhà cung cấp có một API khác nhau"
+🔌 2. "I need to use multiple providers but each has a different API"
-OpenAI sử dụng một định dạng, Claude (Anthropic) sử dụng một định dạng khác, Gemini lại sử dụng một định dạng khác. Nếu nhà phát triển muốn thử nghiệm các mô hình từ các nhà cung cấp khác nhau hoặc dự phòng giữa các nhà cung cấp đó, họ cần phải định cấu hình lại SDK, thay đổi điểm cuối, xử lý các định dạng không tương thích. Các nhà cung cấp tùy chỉnh (FriendLI, NIM) có các điểm cuối mô hình không chuẩn. +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. -**Cách OmniRoute giải quyết vấn đề này:** +**How OmniRoute solves it:** -- **Điểm cuối hợp nhất** — Một `http://localhost:20128/v1` duy nhất đóng vai trò là proxy cho tất cả hơn 36 nhà cung cấp -- **Dịch định dạng** — Tự động và minh bạch: OpenAI ↔ Claude ↔ Gemini ↔ API phản hồi -- **Sạch hóa phản hồi** — Loại bỏ các trường không chuẩn (`x_groq`, `usage_breakdown`, `service_tier`) phá vỡ OpenAI SDK v1.83+ -- **Chuẩn hóa vai trò** — Chuyển đổi `developer` → `system` cho các nhà cung cấp không thuộc OpenAI; `system` → `user` cho GLM/ERNIE -- **Think Tag Extraction** — Trích xuất các khối `
-
🌐 3. "Nhà cung cấp AI của tôi chặn khu vực/quốc gia của tôi"
+🌐 3. "My AI provider blocks my region/country"
-Các nhà cung cấp như OpenAI/Codex chặn quyền truy cập từ các khu vực địa lý nhất định. Người dùng gặp phải các lỗi như `unsupported_country_region_territory` trong quá trình kết nối OAuth và API. Điều này đặc biệt gây khó chịu cho các nhà phát triển từ các nước đang phát triển. +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. -**Cách OmniRoute giải quyết vấn đề này:** +**How OmniRoute solves it:** -- **Cấu hình proxy 3 cấp** — Proxy có thể định cấu hình ở 3 cấp độ: toàn cầu (tất cả lưu lượng truy cập), mỗi nhà cung cấp (chỉ một nhà cung cấp) và mỗi kết nối/khóa -- **Huy hiệu proxy được mã hóa màu** — Chỉ báo trực quan: 🟢 proxy toàn cầu, 🟡 proxy nhà cung cấp, 🔵 proxy kết nối, luôn hiển thị IP -- **Trao đổi mã thông báo OAuth thông qua proxy** — Luồng OAuth cũng đi qua proxy, giải quyết `unsupported_country_region_territory` -- **Kiểm tra kết nối qua Proxy** — Kiểm tra kết nối sử dụng proxy đã định cấu hình (không cần bỏ qua trực tiếp nữa) -- **Hỗ trợ SOCKS5** — Hỗ trợ proxy SOCKS5 đầy đủ cho định tuyến đi -- **Giả mạo dấu vân tay TLS** — Dấu vân tay TLS giống trình duyệt thông qua `wreq-js` để vượt qua khả năng phát hiện bot +- **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
-` prefix
-- **Combo chỉ miễn phí** — Chuỗi `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = $0/tháng mà không có thời gian ngừng hoạt động
-- **Tín dụng miễn phí NVIDIA NIM** — Tích hợp 1000 tín dụng miễn phí
-- **Chiến lược tối ưu hóa chi phí** — Chiến lược định tuyến tự động chọn nhà cung cấp sẵn có rẻ nhất
+- **Free-Only Combos** — Chain `gc/gemini-3-flash → 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
🆓 4. "Tôi muốn sử dụng AI để viết mã nhưng tôi không có tiền"
+🆓 4. "I want to use AI for coding but I have no money"
-Không phải ai cũng có thể trả 20–200 USD/tháng để đăng ký AI. Sinh viên, nhà phát triển từ các quốc gia mới nổi, những người có sở thích và người làm nghề tự do cần được tiếp cận với các mô hình chất lượng với chi phí bằng 0. +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. -**Cách OmniRoute giải quyết vấn đề này:** +**How OmniRoute solves it:** -- **Tích hợp sẵn nhà cung cấp cấp miễn phí** — Hỗ trợ riêng cho các nhà cung cấp miễn phí 100%: iFlow (8 mẫu không giới hạn), Qwen (3 mẫu không giới hạn), Kiro (Claude miễn phí), Gemini CLI (miễn phí 180K/tháng) +- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free) - **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/
-
🔒 5. "Tôi cần bảo vệ cổng AI của mình khỏi bị truy cập trái phép"
+🔒 5. "I need to protect my AI gateway from unauthorized access"
-Khi đưa cổng AI vào mạng (LAN, VPS, Docker), bất kỳ ai có địa chỉ đều có thể sử dụng mã thông báo/hạn ngạch của nhà phát triển. Nếu không có biện pháp bảo vệ, các API dễ bị lạm dụng, chèn ép và lạm dụng. +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. -**Cách OmniRoute giải quyết vấn đề này:** +**How OmniRoute solves it:** -- **Quản lý khóa API** — Tạo, xoay vòng và xác định phạm vi cho mỗi nhà cung cấp bằng trang `/dashboard/api-manager` chuyên dụng -- **Quyền cấp mô hình** — Hạn chế khóa API đối với các mô hình cụ thể (`openai/*`, mẫu ký tự đại diện), với nút chuyển đổi Cho phép tất cả/Hạn chế -- **Bảo vệ điểm cuối API** — Yêu cầu khóa cho `/v1/models` và chặn các nhà cung cấp cụ thể khỏi danh sách -- **Auth Guard + CSRF Protection** — Tất cả các tuyến bảng điều khiển được bảo vệ bằng phần mềm trung gian `withAuth` + mã thông báo CSRF -- **Giới hạn tốc độ** — Giới hạn tốc độ trên mỗi IP với các cửa sổ có thể định cấu hình -- **Lọc IP** — Danh sách cho phép/danh sách chặn để kiểm soát truy cập -- **Prompt Tiêm Guard** — Khử trùng các mẫu nhắc nhở độc hại -- **Mã hóa AES-256-GCM** — Thông tin xác thực được mã hóa ở trạng thái lưu trữ +- **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. "Nhà cung cấp của tôi ngừng hoạt động và tôi mất luồng mã hóa"
+🛑 6. "My provider went down and I lost my coding flow"
-Các nhà cung cấp AI có thể trở nên không ổn định, trả về lỗi 5xx hoặc đạt giới hạn tốc độ tạm thời. Nếu một nhà phát triển phụ thuộc vào một nhà cung cấp duy nhất thì họ sẽ bị gián đoạn. Nếu không có bộ ngắt mạch, việc thử lại nhiều lần có thể làm hỏng ứng dụng. +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. -**Cách OmniRoute giải quyết vấn đề này:** +**How OmniRoute solves it:** -- **Bộ ngắt mạch cho mỗi nhà cung cấp** — Tự động mở/đóng với ngưỡng có thể định cấu hình và thời gian hồi chiêu (Đóng/Mở/Nửa mở) -- **Thời gian chờ theo cấp số nhân** — Độ trễ thử lại lũy tiến -- **Bầy chống sấm sét** — Mutex + bảo vệ semaphore chống lại các cơn bão thử lại đồng thời -- **Chuỗi dự phòng kết hợp** — Nếu nhà cung cấp chính không thành công, nó sẽ tự động rơi qua chuỗi mà không cần can thiệp -- **Combo Circuit Breaker** — Tự động vô hiệu hóa các nhà cung cấp bị lỗi trong chuỗi kết hợp - | 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format | -- **Bảng thông tin sức khỏe** — Giám sát thời gian hoạt động, trạng thái ngắt mạch, khóa, số liệu thống kê bộ nhớ đệm, độ trễ p50/p95/p99 +- **Circuit Breaker per-model** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks +- **Exponential Backoff** — Progressive retry delays +- **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 +- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain +- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
-
🔧 7. "Cấu hình từng công cụ AI thật tẻ nhạt và lặp đi lặp lại"
+🔧 7. "Configuring each AI tool is tedious and repetitive"
-Nhà phát triển sử dụng Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Mỗi công cụ cần một cấu hình khác nhau (điểm cuối API, khóa, mô hình). Việc cấu hình lại khi chuyển đổi nhà cung cấp hoặc mô hình là một sự lãng phí thời gian. +Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time. -**Cách OmniRoute giải quyết vấn đề này:** +**How OmniRoute solves it:** -- **Bảng điều khiển công cụ CLI** — Trang chuyên dụng với thiết lập bằng một cú nhấp chuột cho Claude Code, Codex CLI, OpenClaw, Kilo Code, AntiGravity, Cline -- **Trình tạo cấu hình GitHub Copilot** — Tạo `chatLanguageModels.json` cho Mã VS với lựa chọn mô hình hàng loạt -- **Trình hướng dẫn tích hợp** — Thiết lập 4 bước có hướng dẫn cho người dùng lần đầu -- **Một điểm cuối, tất cả các kiểu máy** — Định cấu hình `http://localhost:20128/v1` một lần, truy cập hơn 36 nhà cung cấp +- **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 67+ providers
-
🔑 8. "Quản lý mã thông báo OAuth từ nhiều nhà cung cấp là địa ngục"
+🔑 8. "Managing OAuth tokens from multiple providers is hell"
-Claude Code, Codex, Gemini CLI, Copilot — tất cả đều sử dụng OAuth 2.0 với các mã thông báo sắp hết hạn. Các nhà phát triển cần liên tục xác thực lại, xử lý `client_secret is missing`, `redirect_uri_mismatch` và các lỗi trên máy chủ từ xa. OAuth trên LAN/VPS đặc biệt có vấn đề. +Claude Code, Codex, Gemini CLI, 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. -**Cách OmniRoute giải quyết vấn đề này:** +**How OmniRoute solves it:** -- **Tự động làm mới mã thông báo** — Làm mới mã thông báo OAuth ở chế độ nền trước khi hết hạn -- **Tích hợp OAuth 2.0 (PKCE)** — Luồng tự động cho Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow -- **OAuth nhiều tài khoản** — Nhiều tài khoản cho mỗi nhà cung cấp thông qua trích xuất mã thông báo JWT/ID -- **OAuth LAN/Remote Fix** — Phát hiện IP riêng cho `redirect_uri` + chế độ URL thủ công cho máy chủ từ xa -- **OAuth đằng sau Nginx** — Sử dụng `window.location.origin` để tương thích với proxy ngược -- **Hướng dẫn OAuth từ xa** — Hướng dẫn từng bước về thông tin đăng nhập Google Cloud trên VPS/Docker +- **Auto Token Refresh** — OAuth tokens refresh in background before expiration +- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow +- **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. "Tôi không biết mình đang chi bao nhiêu hay ở đâu"
+📊 9. "I don't know how much I'm spending or where"
-Các nhà phát triển sử dụng nhiều nhà cung cấp trả phí nhưng không có quan điểm thống nhất về chi tiêu. Mỗi nhà cung cấp có trang tổng quan thanh toán riêng nhưng không có chế độ xem tổng hợp. Chi phí bất ngờ có thể chồng chất. +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. -**Cách OmniRoute giải quyết vấn đề này:** +**How OmniRoute solves it:** -- **Bảng thông tin phân tích chi phí** — Theo dõi chi phí mỗi mã thông báo và quản lý ngân sách cho mỗi nhà cung cấp -- **Giới hạn ngân sách cho mỗi cấp** — Mức chi tiêu trần cho mỗi cấp kích hoạt dự phòng tự động -- **Cấu hình định giá theo mẫu** — Giá có thể định cấu hình cho mỗi mẫu -- **Thống kê sử dụng trên mỗi khóa API** — Số lượng yêu cầu và dấu thời gian được sử dụng lần cuối trên mỗi khóa -- **Bảng thông tin phân tích** — Thẻ thống kê, biểu đồ sử dụng mô hình, bảng nhà cung cấp với tỷ lệ thành công và độ trễ +- **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. "Tôi không thể chẩn đoán lỗi và sự cố trong cuộc gọi AI"
+🐛 10. "I can't diagnose errors and problems in AI calls"
-Khi cuộc gọi không thành công, nhà phát triển không biết liệu đó có phải là giới hạn tốc độ, mã thông báo đã hết hạn, sai định dạng hay lỗi nhà cung cấp hay không. Nhật ký bị phân mảnh trên các thiết bị đầu cuối khác nhau. Nếu không có khả năng quan sát được thì việc gỡ lỗi chỉ là thử và sai. +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. -**Cách OmniRoute giải quyết vấn đề này:** +**How OmniRoute solves it:** -- **Bảng điều khiển nhật ký hợp nhất** — 4 tab: Nhật ký yêu cầu, Nhật ký proxy, Nhật ký kiểm tra, Bảng điều khiển -- **Trình xem nhật ký bảng điều khiển** — Trình xem kiểu thiết bị đầu cuối thời gian thực với các cấp độ được mã hóa màu, tự động cuộn, tìm kiếm, lọc -- **Nhật ký proxy SQLite** — Nhật ký liên tục vẫn tồn tại khi máy chủ khởi động lại -- **Sân chơi dịch thuật** — 4 chế độ gỡ lỗi: Sân chơi (dịch định dạng), Trình kiểm tra trò chuyện (khứ hồi), Bàn thử nghiệm (hàng loạt), Giám sát trực tiếp (thời gian thực) -- **Yêu cầu đo từ xa** — độ trễ p50/p95/p99 + truy tìm X-Request-Id -- **Ghi nhật ký dựa trên tệp bằng xoay vòng** — Trình chặn chặn bảng điều khiển ghi lại mọi thứ vào nhật ký JSON bằng cách xoay vòng dựa trên kích thước +- **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 Proxy Logs** — Persistent logs that survive server restarts +- **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 Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation +- **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. "Việc triển khai và bảo trì cổng rất phức tạp"
+🏗️ 11. "Deploying and maintaining the gateway is complex"
-Việc cài đặt, định cấu hình và duy trì proxy AI trên các môi trường khác nhau (cục bộ, VPS, Docker, đám mây) tốn nhiều công sức. Các vấn đề như đường dẫn được mã hóa cứng, `EACCES` trên thư mục, xung đột cổng và các bản dựng đa nền tảng sẽ gây thêm rắc rối. +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. -**Cách OmniRoute giải quyết vấn đề này:** +**How OmniRoute solves it:** -- **npm cài đặt toàn cầu** — `npm install -g omniroute && omniroute` — đã xong -- **Docker Đa nền tảng** — AMD64 + ARM64 gốc (Apple Silicon, AWS Graviton, Raspberry Pi) -- **Hồ sơ soạn thảo Docker** — `base` (không có công cụ CLI) và `cli` (với Claude Code, Codex, OpenClaw) -- **Ứng dụng máy tính để bàn điện tử** — Ứng dụng gốc dành cho Windows/macOS/Linux với khay hệ thống, tự động khởi động, chế độ ngoại tuyến -- **Chế độ chia cổng** — API và Bảng điều khiển trên các cổng riêng biệt cho các tình huống nâng cao (proxy ngược, mạng vùng chứa) -- **Cloud Sync** — Đồng bộ hóa cấu hình giữa các thiết bị thông qua Cloudflare Workers -- **Sao lưu DB** — Tự động sao lưu, khôi phục, xuất và nhập tất cả cài đặt +- **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
-
🌍 12. "Giao diện chỉ có tiếng Anh và nhóm của tôi không nói được tiếng Anh"
+🌍 12. "The interface is English-only and my team doesn't speak English"
-Các đội ở các quốc gia không nói tiếng Anh, đặc biệt là ở Châu Mỹ Latinh, Châu Á và Châu Âu, gặp khó khăn với giao diện chỉ có tiếng Anh. Rào cản ngôn ngữ làm giảm khả năng tiếp nhận và tăng lỗi cấu hình. +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. -**Cách OmniRoute giải quyết vấn đề này:** +**How OmniRoute solves it:** -- **Bảng điều khiển i18n — 30 ngôn ngữ** — Tất cả hơn 500 phím được dịch bao gồm tiếng Ả Rập, tiếng Bungari, tiếng Đan Mạch, tiếng Đức, tiếng Tây Ban Nha, tiếng Phần Lan, tiếng Pháp, tiếng Do Thái, tiếng Hindi, tiếng Hungary, tiếng Indonesia, tiếng Ý, tiếng Nhật, tiếng Hàn, tiếng Mã Lai, tiếng Hà Lan, tiếng Na Uy, tiếng Ba Lan, tiếng Bồ Đào Nha (PT/BR), tiếng Rumani, tiếng Nga, tiếng Slovak, tiếng Thụy Điển, tiếng Thái, tiếng Ukraina, tiếng Việt, tiếng Trung, tiếng Philipin, tiếng Anh -- **Hỗ trợ RTL** — Hỗ trợ từ phải sang trái cho tiếng Ả Rập và tiếng Do Thái -- **README đa ngôn ngữ** — 30 bản dịch tài liệu hoàn chỉnh -- **Bộ chọn ngôn ngữ** — Biểu tượng quả cầu trong tiêu đề để chuyển đổi theo thời gian thực +- **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. "Tôi cần nhiều hơn là trò chuyện - tôi cần nội dung nhúng, hình ảnh, âm thanh"
+🔄 13. "I need more than chat — I need embeddings, images, audio"
-AI không chỉ hoàn thành cuộc trò chuyện. Nhà phát triển cần tạo hình ảnh, phiên âm âm thanh, tạo phần nhúng cho RAG, sắp xếp lại tài liệu và kiểm duyệt nội dung. Mỗi API có điểm cuối và định dạng khác nhau. +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. -**Cách OmniRoute giải quyết vấn đề này:** +**How OmniRoute solves it:** -- **Nhúng** — `/v1/embeddings` với 6 nhà cung cấp và hơn 9 mẫu máy -- **Tạo hình ảnh** — `/v1/images/generations` với 10 nhà cung cấp và hơn 20 mô hình (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, AntiGravity, SD WebUI, ComfyUI) -- **Chuyển văn bản thành video** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) và SD WebUI -- **Chuyển văn bản thành nhạc** — `/v1/music/generations` — ComfyUI (Mở âm thanh ổn định, MusicGen) -- **Phiên âm âm thanh** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3 -- **Chuyển văn bản thành giọng nói** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, Inworld, Cartesia, PlayHT, + các nhà cung cấp hiện có -- **Kiểm duyệt** — `/v1/moderations` — Kiểm tra an toàn nội dung -- **Sắp xếp lại** — `/v1/rerank` — Sắp xếp lại mức độ liên quan của tài liệu -- **API phản hồi** — Hỗ trợ đầy đủ `/v1/responses` cho Codex +- **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. "Tôi không có cách nào để kiểm tra và so sánh chất lượng giữa các mẫu"
+🧪 14. "I have no way to test and compare quality across models"
-Các nhà phát triển muốn biết mô hình nào là tốt nhất cho trường hợp sử dụng của họ — mã, dịch thuật, lý luận — nhưng việc so sánh thủ công rất chậm. Không có công cụ đánh giá tích hợp nào tồn tại. +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. -**Cách OmniRoute giải quyết vấn đề này:** +**How OmniRoute solves it:** -- **Đánh giá LLM** — Bộ thử nghiệm vàng với 10 trường hợp tải sẵn bao gồm lời chào, toán, địa lý, tạo mã, tuân thủ JSON, dịch thuật, đánh dấu, từ chối an toàn -- **4 Chiến lược kết hợp** — `exact`, `contains`, `regex`, `custom` (chức năng JS) -- **Băng thử nghiệm sân chơi dịch giả** — Thử nghiệm hàng loạt với nhiều đầu vào và đầu ra dự kiến, so sánh giữa các nhà cung cấp -- **Trình kiểm tra trò chuyện** — Toàn bộ chuyến đi với kết xuất phản hồi trực quan -- **Live Monitor** — Luồng thời gian thực của tất cả các yêu cầu truyền qua proxy +- **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. "Tôi cần mở rộng quy mô mà không làm giảm hiệu suất"
+📈 15. "I need to scale without losing performance"
-Khi khối lượng yêu cầu tăng lên mà không lưu vào bộ nhớ đệm thì các câu hỏi tương tự sẽ tạo ra chi phí trùng lặp. Nếu không có tính tạm thời, các yêu cầu trùng lặp sẽ bị lãng phí. Giới hạn tỷ lệ cho mỗi nhà cung cấp phải được tôn trọng. +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. -**Cách OmniRoute giải quyết vấn đề này:** +**How OmniRoute solves it:** -- **Bộ nhớ đệm ngữ nghĩa** — Bộ nhớ đệm hai tầng (chữ ký + ngữ nghĩa) giúp giảm chi phí và độ trễ -- **Yêu cầu Idempotency** — Khoảng thời gian loại bỏ trùng lặp 5 giây cho các yêu cầu giống hệt nhau -- **Phát hiện giới hạn tỷ lệ** — RPM của mỗi nhà cung cấp, khoảng cách tối thiểu và theo dõi đồng thời tối đa -- **Giới hạn tỷ lệ có thể chỉnh sửa** — Giá trị mặc định có thể định cấu hình trong Cài đặt → Khả năng phục hồi với tính bền bỉ -- **Bộ đệm xác thực khóa API** — Bộ đệm 3 tầng cho hiệu suất sản xuất -- **Bảng thông tin sức khỏe với phép đo từ xa** — độ trễ p50/p95/p99, số liệu thống kê bộ nhớ đệm, thời gian hoạt động +- **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 +- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence +- **API Key Validation Cache** — 3-tier cache for production performance +- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
-
🤖 16. "Tôi muốn kiểm soát hành vi của mô hình trên toàn cầu"
+🤖 16. "I want to control model behavior globally"
-Các nhà phát triển muốn tất cả phản hồi bằng một ngôn ngữ cụ thể, với giọng điệu cụ thể hoặc muốn giới hạn các mã thông báo lý luận. Việc định cấu hình điều này trong mọi công cụ/yêu cầu là không thực tế. +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. -**Cách OmniRoute giải quyết vấn đề này:** +**How OmniRoute solves it:** -- **Tiêm nhắc nhở hệ thống** — Lời nhắc chung được áp dụng cho tất cả các yêu cầu -- **Xác thực ngân sách tư duy** — Kiểm soát phân bổ mã thông báo hợp lý cho mỗi yêu cầu (chuyển qua, tự động, tùy chỉnh, thích ứng) -- **6 Chiến lược định tuyến** — Chiến lược toàn cầu xác định cách phân phối yêu cầu -- **Bộ định tuyến ký tự đại diện** — Các mẫu `provider/*` tự động định tuyến tới bất kỳ nhà cung cấp nào -- **Bật/Tắt kết hợp chuyển đổi** — Chuyển đổi kết hợp trực tiếp từ bảng điều khiển -- **Chuyển đổi nhà cung cấp** — Bật/tắt tất cả kết nối cho nhà cung cấp chỉ bằng một cú nhấp chuột -- **Nhà cung cấp bị chặn** — Loại trừ các nhà cung cấp cụ thể khỏi danh sách `/v1/models` +- **System Prompt Injection** — Global prompt applied to all requests +- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive) +- **6 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 +- **Provider Toggle** — Enable/disable all connections for a provider with one click +- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
-
🧰 17. "Tôi cần các công cụ MCP làm khả năng của sản phẩm hạng nhất"
+🧰 17. "I need MCP tools as first-class product capabilities"
-Nhiều cổng AI chỉ hiển thị MCP dưới dạng chi tiết triển khai ẩn. Các nhóm cần một lớp hoạt động rõ ràng và dễ quản lý. +Many AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer. -**Cách OmniRoute giải quyết vấn đề này:** +**How OmniRoute solves it:** -- MCP xuất hiện trong tab điều hướng bảng điều khiển và giao thức điểm cuối -- Trang quản lý MCP chuyên dụng với quy trình, công cụ, phạm vi và kiểm tra -- Tích hợp tính năng khởi động nhanh cho `omniroute --mcp` và quá trình cài đặt ứng dụng khách +- 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. "Tôi cần phối hợp A2A với đường dẫn tác vụ đồng bộ hóa + truyền phát"
+🧠 18. "I need A2A orchestration with sync + stream task paths"
-Quy trình làm việc của tổng đài viên cần cả phản hồi trực tiếp và thực thi theo luồng trong thời gian dài với khả năng kiểm soát vòng đời. +Agent workflows need both direct replies and long-running streamed execution with lifecycle control. -**Cách OmniRoute giải quyết vấn đề này:** +**How OmniRoute solves it:** -- Điểm cuối JSON-RPC A2A (`POST /a2a`) với `message/send` và `message/stream` -- Truyền phát SSE với sự lan truyền trạng thái đầu cuối -- API vòng đời tác vụ cho `tasks/get` và `tasks/cancel` +- 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. "Tôi cần tình trạng quy trình MCP thực sự, trạng thái không đoán được"
+🛰️ 19. "I need real MCP process health, not guessed status"
-Các nhóm vận hành cần biết liệu MCP có thực sự tồn tại hay không, chứ không chỉ là liệu API có thể truy cập được hay không. +Operational teams need to know if MCP is actually alive, not just whether an API is reachable. -**Cách OmniRoute giải quyết vấn đề này:** +**How OmniRoute solves it:** -- Tệp nhịp tim thời gian chạy với PID, dấu thời gian, vận chuyển, số lượng công cụ và chế độ phạm vi -- API trạng thái MCP kết hợp nhịp tim + hoạt động gần đây -- Thẻ trạng thái giao diện người dùng về độ mới của quy trình/thời gian hoạt động/nhịp tim +- 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. "Tôi cần thực thi công cụ MCP có thể kiểm tra được"
+📋 20. "I need auditable MCP tool execution"
-Khi các công cụ thay đổi cấu hình hoặc kích hoạt các hành động vận hành, các nhóm cần truy xuất nguồn gốc pháp lý. +When tools mutate config or trigger ops actions, teams need forensic traceability. -**Cách OmniRoute giải quyết vấn đề này:** +**How OmniRoute solves it:** -- Ghi nhật ký kiểm tra được hỗ trợ bởi SQLite cho các lệnh gọi công cụ MCP -- Bộ lọc theo công cụ, thành công/thất bại, khóa API và phân trang -- Bảng kiểm tra bảng điều khiển + điểm cuối thống kê để tự động hóa +- 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. "Tôi cần quyền MCP trong phạm vi cho mỗi lần tích hợp"
+🔐 21. "I need scoped MCP permissions per integration"
-Các khách hàng khác nhau phải có quyền truy cập ít đặc quyền nhất vào các danh mục công cụ. +Different clients should have least-privilege access to tool categories. -**Cách OmniRoute giải quyết vấn đề này:** +**How OmniRoute solves it:** -- 9 phạm vi MCP chi tiết để truy cập công cụ được kiểm soát -- Thực thi phạm vi và khả năng hiển thị trong giao diện người dùng quản lý MCP -- Tư thế mặc định an toàn cho dụng cụ vận hành +- 9 granular MCP scopes for controlled tool access +- Scope enforcement and visibility in MCP management UI +- Safe default posture for operational tooling
-
⚙️ 22. "Tôi cần kiểm soát hoạt động mà không cần triển khai lại"
+⚙️ 22. "I need operational controls without redeploying"
-Các nhóm cần thay đổi thời gian chạy nhanh trong các sự cố hoặc sự kiện tốn kém. +Teams need quick runtime changes during incidents or cost events. -**Cách OmniRoute giải quyết vấn đề này:** +**How OmniRoute solves it:** -- Chuyển đổi kích hoạt kết hợp trực tiếp từ bảng điều khiển MCP -- Áp dụng hồ sơ khả năng phục hồi từ các gói chính sách được xác định trước -- Đặt lại trạng thái ngắt mạch từ cùng bảng vận hành +- Switch combo activation directly from MCP dashboard +- Apply resilience profiles from pre-defined policy packs +- Reset circuit breaker state from the same operations panel
-
🔄 23. "Tôi cần khả năng hiển thị và hủy trực tiếp trong vòng đời nhiệm vụ A2A"
+🔄 23. "I need live A2A task lifecycle visibility and cancellation"
-Nếu không có khả năng hiển thị vòng đời, các sự cố trong nhiệm vụ sẽ khó phân loại. +Without lifecycle visibility, task incidents become hard to triage. -**Cách OmniRoute giải quyết vấn đề này:** +**How OmniRoute solves it:** -- Liệt kê/lọc nhiệm vụ theo trạng thái/kỹ năng với phân trang -- Xem chi tiết về siêu dữ liệu, sự kiện và hiện vật của nhiệm vụ -- Điểm cuối hủy tác vụ và hành động UI có xác nhận +- 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. "Tôi cần số liệu luồng hoạt động cho tải A2A"
+🌊 24. "I need active stream metrics for A2A load"
-Luồng công việc phát trực tuyến yêu cầu hiểu biết sâu sắc về hoạt động đồng thời và kết nối trực tiếp. +Streaming workflows require operational insight into concurrency and live connections. -**Cách OmniRoute giải quyết vấn đề này:** +**How OmniRoute solves it:** -- Bộ đếm luồng hoạt động được tích hợp vào trạng thái A2A -- Dấu thời gian nhiệm vụ cuối cùng và số lượng trên mỗi trạng thái -- Thẻ bảng điều khiển A2A để theo dõi hoạt động theo thời gian thực +- Active stream counters integrated into A2A status +- Last task timestamp and per-state counts +- A2A dashboard cards for real-time ops monitoring
-
🪪 25. "Tôi cần phát hiện đại lý tiêu chuẩn cho khách hàng"
+🪪 25. "I need standard agent discovery for clients"
-Máy khách và người điều phối bên ngoài cần siêu dữ liệu có thể đọc được bằng máy để triển khai. +External clients and orchestrators need machine-readable metadata for onboarding. -**Cách OmniRoute giải quyết vấn đề này:** +**How OmniRoute solves it:** -- Thẻ đại lý bị lộ tại `/.well-known/agent.json` -- Khả năng và kỹ năng thể hiện trong UI quản lý -- API trạng thái A2A bao gồm siêu dữ liệu khám phá để tự động hóa +- Agent Card exposed at `/.well-known/agent.json` +- Capabilities and skills shown in management UI +- A2A status API includes discovery metadata for automation
-
🧭 26. "Tôi cần khả năng khám phá giao thức trong UX sản phẩm"
+🧭 26. "I need protocol discoverability in the product UX"
-Nếu người dùng không thể khám phá các bề mặt giao thức, chất lượng chấp nhận và hỗ trợ sẽ giảm. +If users cannot discover protocol surfaces, adoption and support quality drop. -**Cách OmniRoute giải quyết vấn đề này:** +**How OmniRoute solves it:** -- Các mục thanh bên cho MCP và A2A -- Tab Giao thức của trang điểm cuối với trạng thái và khởi động nhanh -- Liên kết từ tổng quan đến bảng điều khiển quản lý chuyên dụng +- 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. "Tôi cần xác thực giao thức end-to-end với khách hàng thực"
+🧪 27. "I need end-to-end protocol validation with real clients"
-Các thử nghiệm mô phỏng không đủ để xác thực tính tương thích của giao thức trước khi phát hành. +Mock tests are not enough to validate protocol compatibility before release. -**Cách OmniRoute giải quyết vấn đề này:** +**How OmniRoute solves it:** -- Bộ E2E khởi động ứng dụng và sử dụng vận chuyển máy khách MCP SDK thực -- Máy khách A2A kiểm tra các luồng khám phá, gửi, truyền phát, nhận và hủy -- Kiểm tra chéo các xác nhận đối với kiểm tra MCP và API nhiệm vụ A2A +- 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. "Tôi cần khả năng quan sát thống nhất trên tất cả các giao diện"
+📡 28. "I need unified observability across all interfaces"
-Việc phân chia khả năng quan sát theo giao thức sẽ tạo ra các điểm mù và MTTR dài hơn. +Splitting observability by protocol creates blind spots and longer MTTR. -**Cách OmniRoute giải quyết vấn đề này:** +**How OmniRoute solves it:** -- Bảng điều khiển/nhật ký/phân tích thống nhất trong một sản phẩm -- Sức khỏe + kiểm toán + yêu cầu đo từ xa trên các lớp OpenAI, MCP và A2A -- API hoạt động cho trạng thái và tự động hóa +- Unified dashboards/logs/analytics in one product +- Health + audit + request telemetry across OpenAI, MCP, and A2A layers +- Operational APIs for status and automation
-
💼 29. "Tôi cần một thời gian chạy cho proxy + công cụ + điều phối tác nhân"
+💼 29. "I need one runtime for proxy + tools + agent orchestration"
-Việc chạy nhiều dịch vụ riêng biệt làm tăng chi phí vận hành và các chế độ lỗi. +Running many separate services increases operational cost and failure modes. -**Cách OmniRoute giải quyết vấn đề này:** +**How OmniRoute solves it:** -- Proxy tương thích với OpenAI, máy chủ MCP và máy chủ A2A trong một ngăn xếp -- Chia sẻ xác thực, khả năng phục hồi, lưu trữ dữ liệu và khả năng quan sát -- Mô hình chính sách nhất quán trên tất cả các bề mặt tương tác +- 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
-
-### Sách hướng dẫn ví dụ (Trường hợp sử dụng tích hợp)
+### Example Playbooks (Integrated Use Cases)
-**Playbook A: Tối đa hóa đăng ký trả phí + dự phòng giá rẻ**
+**Playbook A: Maximize paid subscription + cheap backup**
```txt
Combo: "maximize-claude"
@@ -684,7 +694,7 @@ Monthly cost: $20 + small backup spend
Outcome: higher quality, near-zero interruption
```
-**Playbook B: Ngăn xếp mã hóa không tốn phí**
+**Playbook B: Zero-cost coding stack**
```txt
Combo: "free-forever"
@@ -696,7 +706,7 @@ Monthly cost: $0
Outcome: stable free coding workflow
```
-**Playbook C: chuỗi dự phòng luôn hoạt động 24/7**
+**Playbook C: 24/7 always-on fallback chain**
```txt
Combo: "always-on"
@@ -709,65 +719,132 @@ Combo: "always-on"
Outcome: deep fallback depth for deadline-critical workloads
```
-**Playbook D: Tác nhân hoạt động với MCP + A2A**
+**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/mcp and /dashboard/a2a
-4) Control incidents with resilience profile + task cancellation
+3) Observe via /dashboard/endpoint (MCP and A2A tabs)
+4) Toggle services via inline status controls
```
---
-## ⚡ Bắt đầu nhanh
+## 🆓 Start Free — Zero Configuration Cost
-**1. Cài đặt trên toàn cầu:**
+> 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 **iFlow** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |
+| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |
+| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |
+| 5 | `/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).
+
+## Bắt đầu nhanh
+
+### 1) Install and run
```bash
npm install -g omniroute
omniroute
```
-🎉 Trang tổng quan mở lúc `http://localhost:20128`
+> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:
+>
+> ```bash
+> pnpm install -g omniroute
+> pnpm approve-builds -g # Select all packages → approve
+> omniroute
+> ```
-| Lệnh | Mô tả |
-| ----------------------- | --------------------------------------- |
-| `omniroute` | Máy chủ khởi động (cổng mặc định 20128) |
-| `omniroute --port 3000` | Sử dụng cổng tùy chỉnh |
-| `omniroute --no-open` | Không tự động mở trình duyệt |
-| `omniroute --help` | Hiển thị trợ giúp |
+Dashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.
-**2. Kết nối nhà cung cấp MIỄN PHÍ:**
+| 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 |
-Bảng điều khiển → Nhà cung cấp → Kết nối **Mã Claude** hoặc **AntiGravity** → Đăng nhập OAuth → Xong!
+Optional split-port mode:
-**3. Sử dụng trong công cụ CLI của bạn:**
-
-```
-Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Settings:
- Endpoint: http://localhost:20128/v1
- API Key: [copy from dashboard]
- Model: if/kimi-k2-thinking
+```bash
+PORT=20128 DASHBOARD_PORT=20129 omniroute
+# API: http://localhost:20128/v1
+# Dashboard: http://localhost:20129
```
-**Chỉ vậy thôi!** Bắt đầu viết mã với các mô hình AI MIỄN PHÍ.
+### 2) Connect providers and create your API key
-**Thay thế - chạy từ nguồn:**
+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
+
+```txt
+Base URL: http://localhost:20128/v1
+API Key: [copy from Endpoint page]
+Model: if/kimi-k2-thinking (or any provider/model prefix)
+```
+
+Works with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.
+
+### 4) Enable and validate protocols (v2.0)
+
+**MCP (for tool-driven operations):**
+
+```bash
+omniroute --mcp
+```
+
+Then connect your MCP client over `stdio` and test tools like:
+
+- `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 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
+PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev
```
---
## 🐳 Docker
-OmniRoute có sẵn dưới dạng hình ảnh Docker công khai trên [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
+OmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
-**Chạy nhanh:**
+**Quick run:**
```bash
docker run -d \
@@ -778,7 +855,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Với tệp môi trường:**
+**With environment file:**
```bash
# Copy and edit .env first
@@ -793,7 +870,7 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**Sử dụng Docker Compose:**
+**Using Docker Compose:**
```bash
# Base profile (no CLI tools)
@@ -803,257 +880,552 @@ docker compose --profile base up -d
docker compose --profile cli up -d
```
-| Hình ảnh | Gắn thẻ | Kích thước | Mô tả |
-| ------------------------ | -------- | ---------- | ------------------------------ |
-| `diegosouzapw/omniroute` | `latest` | ~250MB | Bản phát hành ổn định mới nhất |
-| `diegosouzapw/omniroute` | `1.0.3` | ~250MB | Phiên bản hiện tại |
+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.
+- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.
+- 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` | `1.0.3` | ~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
+### Bắt đầu nhanh
+
```bash
-npm run electron:dev # Development mode
+# 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)
+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)
---
-## 💰 Sơ lược về giá
+## 💰 Pricing at a Glance
-| Bậc | Nhà cung cấp | Chi phí | Đặt lại hạn ngạch | Tốt nhất cho |
-| --------------- | ------------------- | ---------------------------- | --------------------- | ----------------------- |
-| **💳 ĐĂNG KÝ** | Mã Claude (Pro) | $20/tháng | 5h + hàng tuần | Đã đăng ký |
-| | Codex (Plus/Pro) | $20-200/tháng | 5h + hàng tuần | Người dùng OpenAI |
-| | Song Tử CLI | **MIỄN PHÍ** | 180K/tháng + 1K/ngày | Mọi người! |
-| | Phi công phụ GitHub | $10-19/tháng | Hàng tháng | Người dùng GitHub |
-| **🔑 KHÓA API** | NVIDIA NIM | **MIỄN PHÍ** (1000 tín dụng) | Một lần | Kiểm tra bậc miễn phí |
-| | DeepSeek | Trả tiền cho mỗi lần sử dụng | Không có | Giá/chất lượng tốt nhất |
-| | Groq | Cấp miễn phí + trả phí | Tỷ lệ giới hạn | Suy luận cực nhanh |
-| | xAI (Grok) | Trả tiền cho mỗi lần sử dụng | Không có | Mô hình Grok |
-| | Mistral | Cấp miễn phí + trả phí | Tỷ lệ giới hạn | AI Châu Âu |
-| | OpenRouter | Trả tiền cho mỗi lần sử dụng | Không có | Hơn 100 mẫu |
-| **💰 RẺ** | GLM-4.7 | 0,6 USD/1 triệu USD | 10 giờ sáng hàng ngày | Dự phòng ngân sách |
-| | MiniMax M2.1 | 0,2 USD/1 triệu USD | lăn 5 giờ | Lựa chọn rẻ nhất |
-| | Kimi K2 | $9/tháng căn hộ | 10 triệu token/tháng | Chi phí dự đoán |
-| **🆓 MIỄN PHÍ** | iFlow | $0 | Không giới hạn | 8 mẫu miễn phí |
-| | Qwen | $0 | Không giới hạn | 3 mẫu miễn phí |
-| | Kiro | $0 | Không giới hạn | Claude miễn phí |
+| 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 |
+| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |
+| | 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** | iFlow | **$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 |
-**💡 Mẹo chuyên nghiệp:** Bắt đầu với Gemini CLI (180K miễn phí/tháng) + combo iFlow (miễn phí không giới hạn) = chi phí $0!
+> 🆕 **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
+iFlow (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.
---
-## 💡 Tính năng chính
+---
-### 🧠 Định tuyến lõi & thông minh
+## 🆓 Free Models — What You Actually Get
-| Tính năng | Nó làm gì |
-| --------------------------------------------- | ----------------------------------------------------------------------------------------- |
-| 🎯 **Dự phòng 4 tầng thông minh** | Tự động định tuyến: Đăng ký → Khóa API → Giá rẻ → Miễn phí |
-| 📊 **Theo dõi hạn ngạch theo thời gian thực** | Số lượng mã thông báo trực tiếp + đếm ngược đặt lại cho mỗi nhà cung cấp |
-| 🔄 **Dịch định dạng** | OpenAI ↔ Claude ↔ Gemini ↔ Con trỏ ↔ Kiro liền mạch + vệ sinh phản hồi |
-| 👥 **Hỗ trợ nhiều tài khoản** | Nhiều tài khoản cho mỗi nhà cung cấp với lựa chọn thông minh |
-| 🔄 **Tự động làm mới mã thông báo** | Mã thông báo OAuth tự động làm mới bằng thử lại |
-| 🎨 **Combo tùy chỉnh** | 6 chiến lược: điền trước, quay vòng, p2c, ngẫu nhiên, ít sử dụng nhất, tối ưu hóa chi phí |
-| 🧩 **Mẫu tùy chỉnh** | Thêm bất kỳ ID mẫu nào vào bất kỳ nhà cung cấp nào |
-| 🌐 **Bộ định tuyến ký tự đại diện** | Định tuyến động các mẫu `provider/*` tới bất kỳ nhà cung cấp nào |
-| 🧠 **Ngân sách suy nghĩ** | Các chế độ truyền qua, tự động, tùy chỉnh và thích ứng cho các mô hình lý luận |
-| 🔀 **Model Aliases** | Auto-forward deprecated model IDs to current replacements (built-in + custom) |
-| ⚡ **Background Degradation** | Auto-route background tasks (titles, summaries) to cheaper models |
-| 💬 **Tiêm nhắc nhở hệ thống** | Lời nhắc hệ thống toàn cầu được áp dụng cho tất cả các yêu cầu |
-| 📄 **API phản hồi** | Hỗ trợ đầy đủ API phản hồi OpenAI (`/v1/responses`) cho Codex |
+> 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.
-### 🎵 API đa phương thức
+### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)
-| Tính năng | Nó làm gì |
-| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 🖼️ **Tạo hình ảnh** | `/v1/images/generations` — 4 nhà cung cấp, hơn 9 mô hình |
-| 📐 **Nhúng** | `/v1/embeddings` — 6 nhà cung cấp, hơn 9 mô hình |
-| 🎤 **Phiên âm âm thanh** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |
-| 🔊 **Chuyển văn bản thành giọng nói** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) |
-| 🛡️ **Kiểm duyệt** | `/v1/moderations` — Kiểm tra an toàn nội dung |
-| 🔀 **Sắp xếp lại** | `/v1/rerank` — Sắp xếp lại mức độ liên quan của tài liệu |
+| 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 |
-### 🛡️ Khả năng phục hồi và bảo mật
+### 🟢 IFLOW MODELS (Free OAuth — No Credit Card)
-| Tính năng | Nó làm gì |
-| -------------------------------------- | -------------------------------------------------------------------------------------- |
-| 🔌 **Ngắt mạch** | Tự động mở/đóng theo từng nhà cung cấp với các ngưỡng có thể định cấu hình |
-| 🛡️ **Bầy chống sấm sét** | Mutex + giới hạn tốc độ semaphore cho nhà cung cấp khóa API |
-| 🧠 **Bộ đệm ngữ nghĩa** | Bộ đệm hai lớp (chữ ký + ngữ nghĩa) giảm chi phí và độ trễ |
-| ⚡ **Yêu cầu quyền bình đẳng** | Khoảng thời gian loại trừ 5 giây đối với các yêu cầu trùng lặp |
-| 🔒 **Giả mạo vân tay TLS** | Bỏ qua việc phát hiện bot dựa trên TLS thông qua wreq-js |
-| 🌐 **Lọc IP** | Danh sách cho phép/danh sách chặn để kiểm soát truy cập API |
-| 📊 **Giới hạn tỷ lệ có thể chỉnh sửa** | RPM có thể định cấu hình, khoảng cách tối thiểu và đồng thời tối đa ở cấp hệ thống |
-| 💾 **Rate Limit Persistence** | Learned limits survive restarts via SQLite with 60s debounce + 24h staleness |
-| 🔄 **Token Refresh Resilience** | Per-provider circuit breaker (5 fails→30min) + 30s timeout per attempt |
-| 🛡 **Bảo vệ điểm cuối API** | Kiểm soát xác thực + chặn nhà cung cấp cho điểm cuối `/models` |
-| 🔒 **Khả năng hiển thị proxy** | Huy hiệu được mã hóa màu: 🟢 toàn cầu, 🟡 nhà cung cấp, 🔵 mỗi kết nối với màn hình IP |
-| 🌐 **Cấu hình proxy 3 cấp** | Định cấu hình proxy ở cấp độ toàn cầu, theo nhà cung cấp hoặc theo từng kết nối |
+| 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 |
-### 📊 Khả năng quan sát & phân tích
+### 🟡 QWEN MODELS (Device Code Auth)
-| Tính năng | Nó làm gì |
-| ---------------------------------------- | --------------------------------------------------------------------------------------------- |
-| 📝 **Yêu cầu ghi nhật ký** | Chế độ gỡ lỗi với nhật ký yêu cầu/phản hồi đầy đủ |
-| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |
-| 💾 **Nhật ký proxy SQLite** | Nhật ký proxy liên tục vẫn tồn tại khi khởi động lại máy chủ |
-| 📊 **Bảng thông tin phân tích** | Recharts-Powered: thẻ thống kê, biểu đồ sử dụng mô hình, bảng nhà cung cấp |
-| 📈 **Theo dõi tiến độ** | Chọn tham gia các sự kiện tiến trình SSE để phát trực tuyến |
-| 🧪 **Đánh giá LLM** | Thử nghiệm set vàng với 4 chiến thuật trận đấu |
-| 🔍 **Yêu cầu đo từ xa** | tổng hợp độ trễ p50/p95/p99 + theo dõi X-Request-Id |
-| 📋 **Bảng điều khiển nhật ký** | Trang 4 tab hợp nhất: Nhật ký yêu cầu, Nhật ký proxy, Nhật ký kiểm tra, Bảng điều khiển |
-| 🖥️ **Trình xem nhật ký bảng điều khiển** | Trình xem kiểu thiết bị đầu cuối thời gian thực với bộ lọc cấp độ, tìm kiếm, tự động cuộn |
-| 📑 **Ghi nhật ký dựa trên tệp** | Trình chặn chặn của bảng điều khiển ghi lại tất cả đầu ra vào tệp nhật ký JSON bằng cách xoay |
-| 🏥 **Bảng thông tin sức khỏe** | Thời gian hoạt động của hệ thống, trạng thái ngắt mạch, khóa, số liệu thống kê bộ đệm |
-| 💰 **Theo dõi chi phí** | Quản lý ngân sách + cấu hình giá theo từng mô hình |
+| 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) |
-### ☁️ Triển khai & đồng bộ
+### 🟣 GEMINI CLI (Google OAuth)
-| Tính năng | Nó làm gì |
-| ---------------------------------- | --------------------------------------------------------------------------------------- |
-| 💾 **Đồng bộ đám mây** | Đồng bộ hóa cấu hình trên các thiết bị thông qua Cloudflare Workers |
-| 🌐 **Triển khai mọi nơi** | Localhost, VPS, Docker, Công nhân Cloudflare |
-| 🔑 **Quản lý khóa API** | Tạo, xoay vòng và phạm vi khóa API cho mỗi nhà cung cấp |
-| 🧙 **Trình hướng dẫn giới thiệu** | Thiết lập có hướng dẫn 4 bước cho người dùng lần đầu |
-| 🔧 **Bảng điều khiển công cụ CLI** | Định cấu hình bằng một cú nhấp chuột Claude, Codex, Cline, OpenClaw, Kilo, AntiGravity |
-| 🔄 **Sao lưu DB** | Tự động sao lưu, khôi phục, xuất và nhập cho tất cả cài đặt |
-| 🌐 **Quốc tế hóa** | I18n đầy đủ với hỗ trợ next-intl — Tiếng Anh + Tiếng Bồ Đào Nha (Brazil) |
-| 🌍 **Bộ chọn ngôn ngữ** | Biểu tượng quả địa cầu trong tiêu đề để chuyển đổi ngôn ngữ theo thời gian thực (🇺🇸/🇧🇷) |
-| 🧹 **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 |
-| 📂 **Thư mục dữ liệu tùy chỉnh** | `DATA_DIR` env var để ghi đè đường dẫn lưu trữ `~/.omniroute` mặc định |
+| Model | Prefix | Limit | Rate Limit |
+| ------------------------ | ------ | --------------------------- | ------------- |
+| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |
+| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |
+
+### ⚫ 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
+> iFlow (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 v2.0 is built as an operational platform, not just a relay proxy.
+
+### 🆕 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 Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |
+| 🤖 **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 (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) |
+| 🤝 **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** | 9 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 combo, apply resilience profiles, reset breakers from one control surface |
+
+### 🧠 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** | 6 balancing strategies + fallback chain control |
+| 🌐 **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) |
+| 💬 **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 |
+| ----------------------------------- | -------------------------------------------------------------------------------------- |
+| 🔌 **Circuit Breakers** | Per-model trip/recover with threshold controls |
+| 🎯 **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 |
+| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |
+| 🔑 **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 |
+
+### 📊 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 |
+| 📋 **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 |
+
+### ☁️ Deployment & Platform
+
+| Feature | What It Does |
+| ----------------------------- | --------------------------------------------------------- |
+| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |
+| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |
+| 💾 **Cloud Sync** | Configuration sync via cloud worker |
+| 🔄 **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 |
+
+### Feature Deep Dive
+
+#### Smart fallback with practical cost control
+
+```txt
+Combo: "my-coding-stack"
+ 1. cc/claude-opus-4-6
+ 2. nvidia/llama-3.3-70b
+ 3. glm/glm-4.7
+ 4. if/kimi-k2-thinking
+```
+
+When quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.
+
+#### 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)
+
+#### 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)
🚀 30. "Tôi cần gửi quy trình công việc tổng thể mà không cần sử dụng quá nhiều mã keo"
+🚀 30. "I need to ship agentic workflows without glue-code sprawl"
-Các nhóm bị mất tốc độ khi kết hợp nhiều dịch vụ và tập lệnh đặc biệt. +Teams lose velocity when stitching multiple ad-hoc services and scripts. -**Cách OmniRoute giải quyết vấn đề này:** +**How OmniRoute solves it:** -- Chiến lược điểm cuối thống nhất cho khách hàng và đại lý -- Giao diện người dùng quản lý giao thức tích hợp và đường dẫn xác thực khói -- Nền tảng sẵn sàng sản xuất (bảo mật, ghi nhật ký, khả năng phục hồi, sao lưu) +- Unified endpoint strategy for clients and agents +- Built-in protocol management UIs and smoke validation paths +- Production-ready foundations (security, logging, resilience, backup)
-` khối → `reasoning_content` cho các mô hình tư duy
-- **Đầu ra có cấu trúc** — `json_schema` → `responseMimeType`/`responseSchema` của Gemini
-
-### 👥 Hỗ trợ nhiều tài khoản
-
-- Thêm nhiều tài khoản cho mỗi nhà cung cấp
-- Tự động định tuyến vòng tròn hoặc dựa trên mức độ ưu tiên
-- Dự phòng tài khoản tiếp theo khi đạt hạn ngạch
-
-### 🔄 Tự động làm mới mã thông báo
-
-- Mã thông báo OAuth tự động làm mới trước khi hết hạn
-- Không cần xác thực lại thủ công
-- Trải nghiệm liền mạch trên tất cả các nhà cung cấp
-
-### 🎨 Combo tùy chỉnh
-
-- Tạo kết hợp mô hình không giới hạn
-- 6 chiến lược: điền trước, quay vòng, sức mạnh của hai lựa chọn, ngẫu nhiên, ít sử dụng nhất, tối ưu hóa chi phí
-- Chia sẻ combo trên các thiết bị với Cloud Sync
-
-### 🏥 Bảng thông tin sức khỏe
-
-- Trạng thái hệ thống (thời gian hoạt động, phiên bản, mức sử dụng bộ nhớ)
-- Trạng thái ngắt mạch của mỗi nhà cung cấp (Đóng/Mở/Nửa mở)
-- Trạng thái giới hạn tỷ lệ và khóa hoạt động
-- Thống kê bộ đệm chữ ký
-- Đo từ xa độ trễ (p50/p95/p99) + bộ đệm nhắc nhở
-- Đặt lại tình trạng sức khỏe chỉ bằng một cú nhấp chuột
-
-### 🔧 Sân chơi dịch thuật
-
-OmniRoute bao gồm Sân chơi dịch thuật tích hợp mạnh mẽ với **4 chế độ** để gỡ lỗi, kiểm tra và giám sát các bản dịch API:
-
-| Chế độ | Mô tả |
-| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **💻Sân chơi** | Dịch định dạng trực tiếp - dán bất kỳ nội dung yêu cầu API nào và xem ngay cách OmniRoute dịch nó giữa các định dạng nhà cung cấp (OpenAI ↔ Claude ↔ Gemini ↔ API phản hồi). Bao gồm các mẫu ví dụ và tự động phát hiện định dạng. |
-| **💬 Trình kiểm tra trò chuyện** | Gửi các yêu cầu trò chuyện thực tế thông qua OmniRoute và xem toàn bộ hành trình: thông tin đầu vào của bạn, yêu cầu được dịch, phản hồi của nhà cung cấp và phản hồi được dịch lại. Vô giá để xác nhận định tuyến kết hợp. |
-| **🧪 Ghế thử nghiệm** | Chế độ thử nghiệm hàng loạt - xác định nhiều trường hợp thử nghiệm với đầu vào và đầu ra dự kiến khác nhau, chạy tất cả chúng cùng một lúc và so sánh kết quả giữa các nhà cung cấp và mô hình. |
-| **📱 Giám sát trực tiếp** | Giám sát yêu cầu theo thời gian thực — xem các yêu cầu đến khi chúng truyền qua OmniRoute, xem các bản dịch định dạng đang diễn ra trực tiếp và xác định các vấn đề ngay lập tức. |
-
-**Truy cập:** Bảng điều khiển → Trình dịch (thanh bên)
-
-### 💾 Đồng bộ đám mây
-
-- Đồng bộ hóa nhà cung cấp, combo và cài đặt trên các thiết bị
-- Đồng bộ nền tự động
-- Lưu trữ được mã hóa an toàn
+- `GET /api/mcp/status`
+- `GET /api/mcp/tools`
+- `GET /api/mcp/audit`
+- `GET /api/mcp/audit/stats`
-## 🧪 Đánh giá (Evals)
+📖 Chi tiết tính năng
+🧩 MCP Setup (Model Context Protocol)
-### 🎯 Dự phòng 4 tầng thông minh +Start MCP transport in stdio mode: -Tạo combo với dự phòng tự động: - -``` -Combo: "my-coding-stack" - 1. cc/claude-opus-4-6 (your subscription) - 2. nvidia/llama-3.3-70b (free NVIDIA API) - 3. glm/glm-4.7 (cheap backup, $0.6/1M) - 4. if/kimi-k2-thinking (free fallback) - -→ Auto switches when quota runs out or errors occur +```bash +omniroute --mcp ``` -### 📊 Theo dõi hạn ngạch theo thời gian thực +Recommended validation flow: -- Tiêu thụ mã thông báo trên mỗi nhà cung cấp -- Đặt lại đếm ngược (5 giờ, hàng ngày, hàng tuần) -- Ước tính chi phí cho các bậc trả phí -- Báo cáo chi tiêu hàng tháng +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. -### 🔄 Dịch định dạng +Useful APIs for automation: -Dịch liền mạch giữa các định dạng: - -- **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **Phản hồi của OpenAI** -- Công cụ CLI của bạn gửi định dạng OpenAI → OmniRoute dịch → Nhà cung cấp nhận định dạng gốc -- Hoạt động với mọi công cụ hỗ trợ điểm cuối OpenAI tùy chỉnh -- **Sạch hóa phản hồi** — Loại bỏ các trường không chuẩn để tương thích nghiêm ngặt với OpenAI SDK -- **Chuẩn hóa vai trò** — `developer` → `system` đối với non-OpenAI; `system` → `user` dành cho kiểu máy GLM/ERNIE -- **Trích xuất thẻ suy nghĩ** — `
+
🤝 A2A Setup (Agent2Agent)
-OmniRoute bao gồm khung đánh giá tích hợp để kiểm tra chất lượng phản hồi LLM dựa trên bộ vàng. Truy cập thông qua **Analytics → Đánh giá** trong bảng điều khiển. +Discover the agent: -### Bộ vàng tích hợp +```bash +curl http://localhost:20128/.well-known/agent.json +``` -"Bộ vàng OmniRoute" được tải sẵn chứa 10 trường hợp thử nghiệm bao gồm: +Send a task: -- Lời chào, toán, địa lý, tạo mã -- Tuân thủ định dạng JSON, dịch thuật, đánh dấu -- Từ chối an toàn (nội dung có hại), đếm, logic boolean +```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."}]}}' +``` -### Chiến lược đánh giá +Manage lifecycle: -| Chiến lược | Mô tả | Ví dụ | -| ---------- | --------------------------------------------------------------- | -------------------------------- | -| `exact` | Đầu ra phải khớp chính xác | `"4"` | -| `contains` | Đầu ra phải chứa chuỗi con (không phân biệt chữ hoa chữ thường) | `"Paris"` | -| `regex` | Đầu ra phải khớp với mẫu biểu thức chính quy | `"1.*2.*3"` | -| `custom` | Hàm JS tùy chỉnh trả về true/false | `(output) => output.length > 10` | +- `GET /api/a2a/status` +- `GET /api/a2a/tasks` +- `GET /api/a2a/tasks/:id` +- `POST /api/a2a/tasks/:id/cancel` ---- +Operational UI: -## 📖 Hướng dẫn thiết lập +- `/dashboard/a2a` for task/state/stream observability and smoke actions + +
-
+
+💳 Nhà cung cấp đăng ký
+🧪 End-to-end protocol validation
-### Mã Claude (Pro/Max) +Validate both protocols with real clients: + +```bash +npm run test:protocols:e2e +``` + +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) ```bash Dashboard → Providers → Connect Claude Code @@ -1066,7 +1438,7 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Mẹo chuyên nghiệp:** Sử dụng Opus cho các tác vụ phức tạp, Sonnet cho tốc độ. OmniRoute theo dõi hạn ngạch cho mỗi mô hình! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! ### OpenAI Codex (Plus/Pro) @@ -1080,7 +1452,24 @@ Models: cx/gpt-5.1-codex-max ``` -### Gemini CLI (MIỄN PHÍ 180K/tháng!) +#### 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). + +### Gemini CLI (FREE 180K/month!) ```bash Dashboard → Providers → Connect Gemini CLI @@ -1092,9 +1481,9 @@ Models: gc/gemini-2.5-pro ``` -**Giá trị tốt nhất:** Cấp miễn phí rất lớn! Sử dụng điều này trước các bậc trả phí. +**Best Value:** Huge free tier! Use this before paid tiers. -### Phi công phụ GitHub +### GitHub Copilot ```bash Dashboard → Providers → Connect GitHub @@ -1110,88 +1499,88 @@ Models:
-
🔑 Nhà cung cấp khóa API
+🔑 API Key Providers
-### NVIDIA NIM (1000 tín dụng MIỄN PHÍ!) +### NVIDIA NIM (FREE developer access — 70+ models) -1. Đăng ký: [build.nvidia.com](https://build.nvidia.com) -2. Nhận khóa API miễn phí (bao gồm 1000 tín dụng suy luận) -3. Bảng điều khiển → Thêm nhà cung cấp → NVIDIA NIM: - - Khóa API: `nvapi-your-key` +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` -**Mẫu máy:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct` và hơn 50 mẫu khác +**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more -**Mẹo chuyên nghiệp:** API tương thích với OpenAI — hoạt động trơn tru với tính năng dịch định dạng của OmniRoute! +**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation! -### Tìm kiếm sâu +### DeepSeek -1. Đăng ký: [platform.deepseek.com](https://platform.deepseek.com) -2. Nhận khóa API -3. Trang tổng quan → Thêm nhà cung cấp → DeepSeek +1. Sign up: [platform.deepseek.com](https://platform.deepseek.com) +2. Get API key +3. Dashboard → Add Provider → DeepSeek -**Mẫu xe:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` +**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` -### Groq (Có sẵn bậc miễn phí!) +### Groq (Free Tier Available!) -1. Đăng ký: [console.groq.com](https://console.groq.com) -2. Nhận khóa API (bao gồm bậc miễn phí) -3. Bảng điều khiển → Thêm nhà cung cấp → Groq +1. Sign up: [console.groq.com](https://console.groq.com) +2. Get API key (free tier included) +3. Dashboard → Add Provider → Groq -**Mẫu xe:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` +**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` -**Mẹo chuyên nghiệp:** Suy luận cực nhanh — tốt nhất cho mã hóa thời gian thực! +**Pro Tip:** Ultra-fast inference — best for real-time coding! -### OpenRouter (Hơn 100 mẫu) +### OpenRouter (100+ Models) 1. Sign up: [openrouter.ai](https://openrouter.ai) -2. Nhận khóa API -3. Bảng điều khiển → Thêm nhà cung cấp → OpenRouter +2. Get API key +3. Dashboard → Add Provider → OpenRouter -**Mô hình:** Truy cập hơn 100 mô hình từ tất cả các nhà cung cấp chính thông qua một khóa API duy nhất. +**Models:** Access 100+ models from all major providers through a single API key.
-
💰 Nhà cung cấp giá rẻ (Dự phòng)
+💰 Cheap Providers (Backup)
-### GLM-4.7 (Đặt lại hàng ngày, 0,6 USD/1 triệu) +### GLM-4.7 (Daily reset, $0.6/1M) -1. Đăng ký: [Zhipu AI](https://open.bigmodel.cn/) -2. Nhận khóa API từ Gói mã hóa -3. Bảng điều khiển → Thêm khóa API: - - Nhà cung cấp: `glm` - - Khóa API: `your-key` +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` -**Sử dụng:** `glm/glm-4.7` +**Use:** `glm/glm-4.7` -**Mẹo chuyên nghiệp:** Gói mã hóa cung cấp hạn ngạch 3× với chi phí 1/7! Đặt lại vào 10:00 sáng hàng ngày. +**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -### MiniMax M2.1 (đặt lại 5 giờ, 0,20 USD/1M) +### MiniMax M2.1 (5h reset, $0.20/1M) -1. Đăng ký: [MiniMax](https://www.minimax.io/) -2. Nhận khóa API -3. Bảng điều khiển → Thêm khóa API +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key +3. Dashboard → Add API Key -**Sử dụng:** `minimax/MiniMax-M2.1` +**Use:** `minimax/MiniMax-M2.1` -**Mẹo chuyên nghiệp:** Tùy chọn rẻ nhất cho ngữ cảnh dài (1 triệu mã thông báo)! +**Pro Tip:** Cheapest option for long context (1M tokens)! -### Kimi K2 ($9/tháng cố định) +### Kimi K2 ($9/month flat) -1. Đăng ký: [Moonshot AI](https://platform.moonshot.ai/) -2. Nhận khóa API -3. Bảng điều khiển → Thêm khóa API +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key +3. Dashboard → Add API Key -**Sử dụng:** `kimi/kimi-latest` +**Use:** `kimi/kimi-latest` -**Mẹo chuyên nghiệp:** Đã sửa lỗi 9 USD/tháng cho 10 triệu mã thông báo = 0,90 USD/1 triệu chi phí hiệu quả! +**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
-
🆓 Nhà cung cấp MIỄN PHÍ (Dự phòng khẩn cấp)
+🆓 FREE Providers (Emergency Backup)
-### iFlow (8 mẫu MIỄN PHÍ) +### iFlow (5 FREE models via OAuth) ```bash Dashboard → Connect iFlow @@ -1206,7 +1595,7 @@ Models: if/deepseek-r1 ``` -### Qwen (3 mẫu MIỄN PHÍ) +### Qwen (4 FREE models via Device Code) ```bash Dashboard → Connect Qwen @@ -1218,7 +1607,7 @@ Models: qw/qwen3-coder-flash ``` -### Kiro (Claude MIỄN PHÍ) +### Kiro (Claude FREE) ```bash Dashboard → Connect Kiro @@ -1233,9 +1622,9 @@ Models:
-
🎨 Tạo Combo
+🎨 Create Combos
-### Ví dụ 1: Tối đa hóa đăng ký → Sao lưu giá rẻ +### Example 1: Maximize Subscription → Cheap Backup ``` Dashboard → Combos → Create New @@ -1264,9 +1653,9 @@ Cost: $0 forever!
-
---
-## 🐛 Khắc phục sự cố
+## Xử lý sự cố
🔧 Tích hợp CLI
+🔧 CLI Integration
-### IDE con trỏ +### Cursor IDE ``` Settings → Models → Advanced: @@ -1275,9 +1664,9 @@ Settings → Models → Advanced: Model: cc/claude-opus-4-6 ``` -### Mã Claude +### Claude Code -Sử dụng trang **Công cụ CLI** trong trang tổng quan để định cấu hình bằng một cú nhấp chuột hoặc chỉnh sửa `~/.claude/settings.json` theo cách thủ công. +Use the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually. ### Codex CLI @@ -1290,13 +1679,13 @@ codex "your prompt" ### OpenClaw -**Tùy chọn 1 — Trang tổng quan (được khuyến nghị):** +**Option 1 — Dashboard (recommended):** ``` Dashboard → CLI Tools → OpenClaw → Select Model → Apply ``` -**Tùy chọn 2 — Thủ công:** Chỉnh sửa `~/.openclaw/openclaw.json`: +**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`: ```json { @@ -1312,9 +1701,9 @@ Dashboard → CLI Tools → OpenClaw → Select Model → Apply } ``` -> **Lưu ý:** OpenClaw chỉ hoạt động với OmniRoute cục bộ. Sử dụng `127.0.0.1` thay vì `localhost` để tránh các vấn đề về độ phân giải IPv6. +> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues. -### Cline / Tiếp tục / RooCode +### Cline / Continue / RooCode ``` Settings → API Configuration: @@ -1324,110 +1713,245 @@ Settings → API Configuration: 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. +
-
-- **Thời gian chạy**: Node.js 18–22 LTS (⚠️ Node.js 24+ **không được hỗ trợ** — `better-sqlite3` các tệp nhị phân gốc không tương thích)
-- **Ngôn ngữ**: TypeScript 5.9 — **100% TypeScript** trên `src/` và `open-sse/` (v1.0.6)
-- **Khung**: Next.js 16 + React 19 + Tailwind CSS 4
-- **Cơ sở dữ liệu**: LowDB (JSON) + SQLite (trạng thái miền + nhật ký proxy)
-- **Truyền phát**: Sự kiện do máy chủ gửi (SSE)
-- **Xác thực**: OAuth 2.0 (PKCE) + JWT + Khóa API
-- **Thử nghiệm**: Trình chạy thử nghiệm Node.js (hơn 368 bài kiểm tra đơn vị)
-- **CI/CD**: GitHub Actions (tự động xuất bản npm + Docker Hub khi phát hành)
-- **Trang web**: [omniroute.online](https://omniroute.online)
-- **Gói**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
-- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
-- **Khả năng phục hồi**: Ngắt mạch, lùi theo cấp số nhân, chống sét bầy đàn, giả mạo TLS
-
----
-
-## 📖 Tài liệu
-
-| Tài liệu | Mô tả |
-| -------------------------------------------- | --------------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Nhà cung cấp, combo, tích hợp CLI, triển khai |
-| [API Reference](docs/API_REFERENCE.md) | Tất cả các điểm cuối có ví dụ |
-| [Troubleshooting](docs/TROUBLESHOOTING.md) | Các vấn đề thường gặp và giải pháp |
-| [Architecture](docs/ARCHITECTURE.md) | Kiến trúc hệ thống và nội bộ |
-| [Contributing](CONTRIBUTING.md) | Thiết lập và hướng dẫn phát triển |
-| [OpenAPI Spec](docs/openapi.yaml) | Đặc tả OpenAPI 3.0 |
-| [Security Policy](SECURITY.md) | Báo cáo lỗ hổng bảo mật và thực hành bảo mật |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Hướng dẫn đầy đủ: Thiết lập VM + nginx + Cloudflare |
-| [Features Gallery](docs/FEATURES.md) | Tham quan bảng điều khiển trực quan với ảnh chụp màn hình |
-
-### 📸 Xem trước bảng điều khiển
+## 🛠️ Tech Stack
Nhấp để mở rộng hướng dẫn khắc phục sự cố
+Click to expand troubleshooting guide
-**"Mô hình ngôn ngữ không cung cấp tin nhắn"** +**"Language model did not provide messages"** -- Đã hết hạn ngạch nhà cung cấp → Kiểm tra trình theo dõi hạn ngạch bảng điều khiển -- Giải pháp: Sử dụng combo dự phòng hoặc chuyển sang tầng rẻ hơn +- Provider quota exhausted → Check dashboard quota tracker +- Solution: Use combo fallback or switch to cheaper tier -**Giới hạn tỷ lệ** +**Rate limiting** -- Hết hạn ngạch đăng ký → Dự phòng sang GLM/MiniMax -- Thêm tổ hợp: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Subscription quota out → Fallback to GLM/MiniMax +- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -**Mã thông báo OAuth đã hết hạn** +**OAuth token expired** -- Tự động làm mới bởi OmniRoute -- Nếu sự cố vẫn tiếp diễn: Bảng điều khiển → Nhà cung cấp → Kết nối lại +- Auto-refreshed by OmniRoute +- If issues persist: Dashboard → Provider → Reconnect -**Chi phí cao** +**High costs** -- Kiểm tra số liệu thống kê sử dụng trong Bảng điều khiển → Chi phí -- Chuyển mô hình chính sang GLM/MiniMax -- Sử dụng bậc miễn phí (Gemini CLI, iFlow) cho các tác vụ không quan trọng +- Check usage stats in Dashboard → Costs +- Switch primary model to GLM/MiniMax +- Use free tier (Gemini CLI, iFlow) for non-critical tasks -**Bảng điều khiển mở sai cổng** +**Dashboard/API ports are wrong** -- Đặt `PORT=20128` và `NEXT_PUBLIC_BASE_URL=http://localhost:20128` +- `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) -**Lỗi đồng bộ hóa đám mây** +**Cloud sync errors** -- Xác minh `BASE_URL` trỏ tới phiên bản đang chạy của bạn -- Xác minh `CLOUD_URL` điểm tới điểm cuối đám mây dự kiến của bạn -- Giữ các giá trị `NEXT_PUBLIC_*` được căn chỉnh với các giá trị phía máy chủ +- 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 -**Đăng nhập lần đầu không hoạt động** +**First login not working** -- Kiểm tra `INITIAL_PASSWORD` trong `.env` -- Nếu không được đặt, mật khẩu dự phòng là `123456` +- Check `INITIAL_PASSWORD` in `.env` +- If unset, fallback password is `123456` -**Không có nhật ký yêu cầu** +**No request logs** -- Đặt `ENABLE_REQUEST_LOGS=true` trong `.env` +- Set `ENABLE_REQUEST_LOGS=true` in `.env` -**Kiểm tra kết nối cho thấy "Không hợp lệ" đối với các nhà cung cấp tương thích với OpenAI** +**Connection test shows "Invalid" for OpenAI-compatible providers** -- Nhiều nhà cung cấp không hiển thị điểm cuối `/models` -- OmniRoute v1.0.6+ bao gồm xác thực dự phòng thông qua hoàn thành trò chuyện -- Đảm bảo URL cơ sở bao gồm hậu tố `/v1` +- 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 +### 🔐 OAuth on a Remote Server + -> **⚠️ QUAN TRỌNG đối với người sử dụng OmniRoute trên VPS/Docker/servidor remoto** +> **⚠️ Important for users running OmniRoute on a VPS, Docker, or any remote server** -### OAuth +#### Why does Antigravity / Gemini CLI OAuth fail on remote servers? -Os đã được chứng minh **AntiGravity** e **Gemini CLI** sử dụng **Google OAuth 2.0** để xác thực. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** một trong các URI trước khi lập danh sách trên Google Cloud Console để ứng dụng. +The **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console. -Vì các thông tin xác thực OAuth không có OmniRoute estão cadastradas **apenas para `localhost`**. Bạn có thể truy cập OmniRoute bằng cách điều khiển lại máy chủ (ví dụ: `https://omniroute.meuservidor.com`), hoặc Google sẽ cung cấp thông tin xác thực với: +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 ``` -### Giải pháp: Định cấu hình thông tin đăng nhập OAuth +#### Solution: Configure your own OAuth credentials -Bạn nên chú ý **OAuth 2.0 Client ID** không có Google Cloud Console vì URI làm dịch vụ của bạn. +You need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI. -#### Vượt qua một lần nữa +#### Step-by-step -**1. Truy cập vào Google Cloud Console** +**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 + +# For Gemini CLI: +GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com +GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +``` + +**6. Restart OmniRoute** + +```bash +# npm: +npm run dev + +# Docker: +docker restart omniroute +``` + +**7. Try connecting again** + +Dashboard → Providers → Antigravity (or Gemini CLI) → OAuth + +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. + +--- + +
+
---
-## 🛠️
+🇧🇷 Versão em Português
+ +#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos? + +Os provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo. + +As credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticação com: + +``` +Error 400: redirect_uri_mismatch +``` + +#### Solução: Configure suas próprias credenciais OAuth + +Você precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor. + +#### Passo a passo + +**1. Acesse o Google Cloud Console** Abra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) -**2. Hãy yêu cầu ID khách hàng OAuth 2.0 mới** +**2. Crie um novo OAuth 2.0 Client ID** -- Nhấn vào **"+ Tạo thông tin xác thực"** → **"ID khách hàng OAuth"** -- Mẹo ứng dụng: **"Ứng dụng web"** -- Tên: escolha qualquer nome (ví dụ: `OmniRoute Remote`) +- Clique em **"+ Create Credentials"** → **"OAuth client ID"** +- Tipo de aplicativo: **"Web application"** +- Nome: escolha qualquer nome (ex: `OmniRoute Remote`) -**3. Adicione dưới dạng URI chuyển hướng được ủy quyền** +**3. Adicione as Authorized Redirect URIs** -Không có quảng cáo **"URI chuyển hướng được ủy quyền"**, khuyến cáo: +No campo **"Authorized redirect URIs"**, adicione: ``` https://seu-servidor.com/callback ``` -> Thay thế `seu-servidor.com` từ địa chỉ IP hoặc dịch vụ IP của bạn (bao gồm một cổng cần thiết, ví dụ: `http://45.33.32.156:20128/callback`). +> Substitua `seu-servidor.com` pelo domínio ou IP do seu servidor (inclua a porta se necessário, ex: `http://45.33.32.156:20128/callback`). -**4. Lưu và sao chép dưới dạng uy tín** +**4. Salve e copie as credenciais** -Sau đó, Google đã đăng trên **ID khách hàng** và **Bí mật khách hàng**. +Após criar, o Google mostrará o **Client ID** e o **Client Secret**. -**5. Định cấu hình theo các biến thể của môi trường** +**5. Configure as variáveis de ambiente** -Không có `.env` (hoặc có nhiều biến thể môi trường xung quanh Docker): +No seu `.env` (ou nas variáveis de ambiente do Docker): ```bash # Para Antigravity: @@ -1440,7 +1964,7 @@ GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret ``` -**6. Reinicie hoặc OmniRoute** +**6. Reinicie o OmniRoute** ```bash # Se usando npm: @@ -1450,152 +1974,147 @@ npm run dev docker restart omniroute ``` -**7. Lều kết nối mới lạ** +**7. Tente conectar novamente** -Bảng điều khiển → Nhà cung cấp → Anti Gravity (hoặc Gemini CLI) → OAuth +Dashboard → Providers → Antigravity (ou Gemini CLI) → OAuth -Google đã chuyển hướng điều chỉnh cho `https://seu-servidor.com/callback` và một chức năng xác thực. +Agora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará. --- -### Thời gian giải quyết (sem configurar credenciais próprias) +#### Workaround temporário (sem configurar credenciais próprias) -Nếu không có câu hỏi nào về thông tin xác thực trước đây, bạn có thể sử dụng thông tin **hướng dẫn sử dụng URL**: +Se não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**: -1. O OmniRoute tìm kiếm URL tự động của Google -2. Sau khi bạn tự động đăng ký, hoặc chuyển hướng Google sang `localhost` (bạn không thể điều chỉnh lại dịch vụ) -3. **Sao chép một URL hoàn chỉnh** da cuối cùng của trình duyệt của bạn (mesmo que a página not carregue) -4. URL này không có khả năng xuất hiện không có phương thức kết nối nào với OmniRoute -5. Kết nối với nhau **"Kết nối"** +1. O OmniRoute abrirá a URL de autorização do Google +2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto) +3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue) +4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute +5. Clique em **"Connect"** -> Chức năng giải pháp này có thể giúp tự động cấp quyền cho URL và có thể chuyển hướng độc lập đến mục tiêu hoặc không. +> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.
-
---
-## 🗺️
+## Tài liệu
-OmniRoute có **210+ tính năng được lên kế hoạch** qua nhiều giai đoạn phát triển. Dưới đây là các lĩnh vực chính:
-
-| Danh mục | Tính năng dự kiến | Điểm nổi bật |
-| ------------------------------ | -------------------- | -------------------------------------------------------------------------------------------------------------- |
-| 🧠 **Định tuyến & thông minh** | 25+ | Định tuyến có độ trễ thấp nhất, định tuyến dựa trên thẻ, ưu tiên hạn ngạch, chọn tài khoản P2C |
-| 🔒 **Bảo mật & Tuân thủ** | 20+ | Tăng cường SSRF, che giấu thông tin xác thực, giới hạn tốc độ cho mỗi điểm cuối, phạm vi khóa quản lý |
-| 📊 **Khả năng quan sát** | 15+ | Tích hợp OpenTelemetry, giám sát hạn ngạch thời gian thực, theo dõi chi phí trên mỗi mô hình |
-| 🔄 **Tích hợp nhà cung cấp** | 20+ | Đăng ký mô hình động, thời gian hồi chiêu của nhà cung cấp, Codex nhiều tài khoản, phân tích hạn ngạch Copilot |
-| ⚡ **Hiệu suất** | 15+ | Lớp bộ đệm kép, bộ đệm nhắc nhở, bộ đệm phản hồi, lưu giữ luồng, API hàng loạt |
-| 🌐 **Hệ sinh thái** | 10+ | API WebSocket, cấu hình tải lại nóng, kho cấu hình phân tán, chế độ thương mại |
-
-### 🔜 Sắp ra mắt
-
-- 🔗 **Tích hợp OpenCode** — Hỗ trợ của nhà cung cấp gốc cho IDE mã hóa OpenCode AI
-- 🔗 **Tích hợp TRAE** — Hỗ trợ đầy đủ cho khung phát triển TRAE AI
-- 📦 **Batch API** — Xử lý hàng loạt không đồng bộ cho các yêu cầu hàng loạt
-- 🎯 **Định tuyến dựa trên thẻ** — Định tuyến các yêu cầu dựa trên thẻ và siêu dữ liệu tùy chỉnh
-- 💰 **Chiến lược chi phí thấp nhất** — Tự động chọn nhà cung cấp có sẵn rẻ nhất
-
-> 📝 Thông số kỹ thuật đầy đủ tính năng có sẵn trong [link](docs/new-features/) (217 thông số kỹ thuật chi tiết)
+| Document | Description |
+| ---------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 16 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/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
+| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
-## 👥 Người đóng góp
+## 🗺️ Roadmap
+
+OmniRoute has **210+ 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, P2C account selection |
+| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |
+| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |
+| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider 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
[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
-### Cách đóng góp
+### How to Contribute
-1. Phân nhánh kho lưu trữ
-2. Tạo nhánh tính năng của bạn (`git checkout -b feature/amazing-feature`)
-3. Cam kết thay đổi của bạn (`git commit -m 'Add amazing feature'`)
-4. Đẩy vào nhánh (`git push origin feature/amazing-feature`)
-5. Mở yêu cầu kéo
+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
-Xem [CONTRIBUTING.md](CONTRIBUTING.md) để biết hướng dẫn chi tiết.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
-### Phát hành phiên bản mới
+### Releasing a New Version
```bash
# Create a release — npm publish happens automatically
-gh release create v1.0.6 --title "v1.0.6" --generate-notes
+gh release create v2.0.0 --title "v2.0.0" --generate-notes
```
---
-## 📊 Lịch sử ngôi sao
+## 📊 Star History
## Stargazers over time
## [](https://starchart.cc/diegosouzapw/OmniRoute)
-## 🙏 Lời cảm ơn
+## 🙏 Acknowledgments
-Đặc biệt cảm ơn **[9router](https://github.com/decolua/9router)** của **[decolua](https://github.com/decolua)** — dự án ban đầu đã truyền cảm hứng cho đợt phân nhánh này. OmniRoute được xây dựng dựa trên nền tảng đáng kinh ngạc đó với các tính năng bổ sung, API đa phương thức và viết lại TypeScript đầy đủ.
+Special thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.
-Đặc biệt cảm ơn **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — cách triển khai Go ban đầu đã truyền cảm hứng cho cổng JavaScript này.
+Special thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.
---
-## 📄 Giấy phép
+## Giấy phép
-Giấy phép MIT - xem [LICENSE](LICENSE) để biết chi tiết.
+MIT License - see [LICENSE](LICENSE) for details.
---
Nhấp để xem ảnh chụp màn hình trang tổng quan
+Click to expand tech stack details
-| Trang | Ảnh chụp màn hình | -| ------------------- | ------------------------------------------------- | -| **Nhà cung cấp** |  | -| **Combo** |  | -| **Phân tích** |  | -| **Sức khỏe** |  | -| **Người dịch** |  | -| **Cài đặt** |  | -| **Công cụ CLI** |  | -| **Nhật ký sử dụng** |  | -| **Điểm cuối** |  | +- **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**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions) +- **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
- Được xây dựng với ❤️ dành cho nhà phát triển viết mã 24/7
+ Built with ❤️ for developers who code 24/7
omniroute.online
+
diff --git a/docs/i18n/vi/docs/FEATURES.md b/docs/i18n/vi/docs/FEATURES.md
new file mode 100644
index 0000000000..3488ce2edc
--- /dev/null
+++ b/docs/i18n/vi/docs/FEATURES.md
@@ -0,0 +1,145 @@
+# OmniRoute — Dashboard Features Gallery (Tiếng Việt)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/FEATURES.md) · 🇪🇸 [es](../../es/docs/FEATURES.md) · 🇫🇷 [fr](../../fr/docs/FEATURES.md) · 🇩🇪 [de](../../de/docs/FEATURES.md) · 🇮🇹 [it](../../it/docs/FEATURES.md) · 🇷🇺 [ru](../../ru/docs/FEATURES.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FEATURES.md) · 🇯🇵 [ja](../../ja/docs/FEATURES.md) · 🇰🇷 [ko](../../ko/docs/FEATURES.md) · 🇸🇦 [ar](../../ar/docs/FEATURES.md) · 🇮🇳 [in](../../in/docs/FEATURES.md) · 🇹🇭 [th](../../th/docs/FEATURES.md) · 🇻🇳 [vi](../../vi/docs/FEATURES.md) · 🇮🇩 [id](../../id/docs/FEATURES.md) · 🇲🇾 [ms](../../ms/docs/FEATURES.md) · 🇳🇱 [nl](../../nl/docs/FEATURES.md) · 🇵🇱 [pl](../../pl/docs/FEATURES.md) · 🇸🇪 [sv](../../sv/docs/FEATURES.md) · 🇳🇴 [no](../../no/docs/FEATURES.md) · 🇩🇰 [da](../../da/docs/FEATURES.md) · 🇫🇮 [fi](../../fi/docs/FEATURES.md) · 🇵🇹 [pt](../../pt/docs/FEATURES.md) · 🇷🇴 [ro](../../ro/docs/FEATURES.md) · 🇭🇺 [hu](../../hu/docs/FEATURES.md) · 🇧🇬 [bg](../../bg/docs/FEATURES.md) · 🇸🇰 [sk](../../sk/docs/FEATURES.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FEATURES.md) · 🇮🇱 [he](../../he/docs/FEATURES.md) · 🇵🇭 [phi](../../phi/docs/FEATURES.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FEATURES.md)
+
+---
+
+Visual guide to every section of the OmniRoute dashboard.
+
+---
+
+## 🔌 Providers
+
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
+
+
+
+---
+
+## 🎨 Combos
+
+Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
+
+
+
+---
+
+## 📊 Analytics
+
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
+
+
+
+---
+
+## 🏥 System Health
+
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+
+
+
+---
+
+## 🔧 Translator Playground
+
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
+
+
+
+---
+
+## 🎮 Model Playground _(v2.0.9+)_
+
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
+
+---
+
+## 🎨 Themes _(v2.0.5+)_
+
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
+
+## ⚙️ Settings
+
+Comprehensive settings panel with tabs:
+
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning
+- **Advanced** — Configuration overrides
+
+
+
+---
+
+## 🔧 CLI Tools
+
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
+
+
+
+---
+
+## 🤖 CLI Agents _(v2.0.11+)_
+
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
+
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
+
+---
+
+## 🖼️ Media _(v2.0.3+)_
+
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
+
+## 📝 Request Logs
+
+Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
+
+
+
+---
+
+## 🌐 API Endpoint
+
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
+
+
+
+---
+
+## 🔑 API Key Management
+
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
+
+---
+
+## 📋 Audit Log
+
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
+
+---
+
+## 🖥️ Desktop Application
+
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
+
+Key features:
+
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
+
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.
diff --git a/docs/i18n/zh-CN/README.md b/docs/i18n/zh-CN/README.md
index 4426c20907..8c945feee4 100644
--- a/docs/i18n/zh-CN/README.md
+++ b/docs/i18n/zh-CN/README.md
@@ -1,24 +1,94 @@
-omniroute.online
-
-
- # 🚀 OmniRoute — 免费 AI 网关
+# 🚀 OmniRoute — The Free AI Gateway (中文（简体）)
-### 永不停止编程。智能路由至**免费和低成本 AI 模型**，自动故障转移。
-
-_您的通用 API 代理 — 一个端点，36+ 提供商，零停机时间。_
-
-**Chat Completions • Embeddings • 图像生成 • 音频 • Reranking • 100% TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 为您最爱的编程代理提供免费 AI
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_通过 OmniRoute 连接任何 AI 驱动的 IDE 或 CLI 工具 — 免费 API 网关，无限编程。_
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+` tags no longer leak to clients in SSE streaming responses (#585) |
+| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with per-provider/account quota enforcement, idempotency, SHA-256 storage, and optional GitHub issue reporting |
+| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG → generic fallback chain |
+| 🔄 **Model Auto-Sync** | 24h scheduler and manual UI toggle to sync model lists for built-in and custom OpenAI-compatible providers |
+| 🌐 **OpenCode Zen/Go** | Two new providers from @kang-heewon via PR #530: free tier + subscription tier via `OpencodeExecutor` |
+| 🐛 **Gemini CLI OAuth** | Actionable error when `GEMINI_OAUTH_CLIENT_SECRET` is missing in Docker (was cryptic Google error) |
+| 🐛 **OpenCode config** | `saveOpenCodeConfig()` now correctly writes TOML to `XDG_CONFIG_HOME` |
+| 🐛 **Pinned model override** | `body.model` correctly set to `pinnedModel` on context-cache protection |
+| 🐛 **Codex/Claude loop** | `tool_result` blocks now converted to text to stop infinite loops |
+| 🐛 **Login redirect** | Login no longer freezes after skipping password setup |
+| 🐛 **Windows paths** | MSYS2/Git-Bash paths (`/c/...`) normalized to `C:\...` automatically |
+
+---
+
+## 🖼️ Main Dashboard
+
+
-📡 所有代理通过 ` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**Stop wasting money and hitting limits:**
-### 🆕 What's New in v3.0.0
+- Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) |
-| 🔑 **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement |
-| 🎨 **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback |
-| 🔄 **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers |
-| 🌐 **OpenCode Zen/Go** | Two new providers: free tier + subscription tier |
-| 🔧 **926 Tests** | Full test suite passes with 0 failures |
+**OmniRoute solves this:**
+
+- ✅ **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
+- ✅ **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool
---
-[](https://www.npmjs.com/package/omniroute)
-[](https://hub.docker.com/r/diegosouzapw/omniroute)
-[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
-[](https://omniroute.online)
-[](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
+## 📧 Support
-[🌐 网站](https://omniroute.online) • [🚀 快速开始](#-快速开始) • [💡 功能特性](#-核心功能) • [📖 文档](#-文档) • [💰 定价](#-定价概览)
+> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.
-🌐 **Available in:** 🇺🇸 [English](../../README.md) | 🇧🇷 [Português (Brasil)](../pt-BR/README.md) | 🇪🇸 [Español](../es/README.md) | 🇫🇷 [Français](../fr/README.md) | 🇮🇹 [Italiano](../it/README.md) | 🇷🇺 [Русский](../ru/README.md) | 🇨🇳 [中文 (简体)](../zh-CN/README.md) | 🇩🇪 [Deutsch](../de/README.md) | 🇮🇳 [हिन्दी](../in/README.md) | 🇹🇭 [ไทย](../th/README.md) | 🇺🇦 [Українська](../uk-UA/README.md) | 🇸🇦 [العربية](../ar/README.md) | 🇯🇵 [日本語](../ja/README.md) | 🇻🇳 [Tiếng Việt](../vi/README.md) | 🇧🇬 [Български](../bg/README.md) | 🇩🇰 [Dansk](../da/README.md) | 🇫🇮 [Suomi](../fi/README.md) | 🇮🇱 [עברית](../he/README.md) | 🇭🇺 [Magyar](../hu/README.md) | 🇮🇩 [Bahasa Indonesia](../id/README.md) | 🇰🇷 [한국어](../ko/README.md) | 🇲🇾 [Bahasa Melayu](../ms/README.md) | 🇳🇱 [Nederlands](../nl/README.md) | 🇳🇴 [Norsk](../no/README.md) | 🇵🇹 [Português (Portugal)](../pt/README.md) | 🇷🇴 [Română](../ro/README.md) | 🇵🇱 [Polski](../pl/README.md) | 🇸🇰 [Slovenčina](../sk/README.md) | 🇸🇪 [Svenska](../sv/README.md) | 🇵🇭 [Filipino](../phi/README.md)
-
-
-
----
-
-## 🖼️
-
-
-
- # 🚀 OmniRoute — 免费 AI 网关
+# 🚀 OmniRoute — The Free AI Gateway (中文（简体）)
-### 永不停止编程。智能路由至**免费和低成本 AI 模型**，自动故障转移。
-
-_您的通用 API 代理 — 一个端点，36+ 提供商，零停机时间。_
-
-**Chat Completions • Embeddings • 图像生成 • 音频 • Reranking • 100% TypeScript**
+🌐 **Languages:** 🇺🇸 [English](../../../README.md) · 🇪🇸 [es](../es/README.md) · 🇫🇷 [fr](../fr/README.md) · 🇩🇪 [de](../de/README.md) · 🇮🇹 [it](../it/README.md) · 🇷🇺 [ru](../ru/README.md) · 🇨🇳 [zh-CN](../zh-CN/README.md) · 🇯🇵 [ja](../ja/README.md) · 🇰🇷 [ko](../ko/README.md) · 🇸🇦 [ar](../ar/README.md) · 🇮🇳 [in](../in/README.md) · 🇹🇭 [th](../th/README.md) · 🇻🇳 [vi](../vi/README.md) · 🇮🇩 [id](../id/README.md) · 🇲🇾 [ms](../ms/README.md) · 🇳🇱 [nl](../nl/README.md) · 🇵🇱 [pl](../pl/README.md) · 🇸🇪 [sv](../sv/README.md) · 🇳🇴 [no](../no/README.md) · 🇩🇰 [da](../da/README.md) · 🇫🇮 [fi](../fi/README.md) · 🇵🇹 [pt](../pt/README.md) · 🇷🇴 [ro](../ro/README.md) · 🇭🇺 [hu](../hu/README.md) · 🇧🇬 [bg](../bg/README.md) · 🇸🇰 [sk](../sk/README.md) · 🇺🇦 [uk-UA](../uk-UA/README.md) · 🇮🇱 [he](../he/README.md) · 🇵🇭 [phi](../phi/README.md) · 🇧🇷 [pt-BR](../pt-BR/README.md)
---
-### 🤖 为您最爱的编程代理提供免费 AI
+### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback.
-_通过 OmniRoute 连接任何 AI 驱动的 IDE 或 CLI 工具 — 免费 API 网关，无限编程。_
+_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._
+
+**Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript**
+
+---
+
+
+
+[](https://www.npmjs.com/package/omniroute)
+[](https://www.npmjs.com/package/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://hub.docker.com/r/diegosouzapw/omniroute)
+[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
+[](https://omniroute.online)
+[](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)
+
+
+
+🌐 **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)
+
+---
+
+## 🆕 What's New in v3.0.0
+
+> **Upgrading from v2.9.5?** — See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes.
+
+| Area | Change |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection remediation |
+| ✅ **Route Validation** | All 176 API routes now validated with Zod schemas + `validateBody()` — CI `check:route-validation:t06` passes |
+| 🐛 **omniModel Tag Leak** | Internal `
+
+
+
+---
+
+## 📸 Dashboard Preview
+
+
+
+
+
+---
+
+### 🤖 Free AI Provider for your favorite coding agents
+
+_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._
Click to see dashboard screenshots
+ +| Page | Screenshot | +| -------------- | ------------------------------------------------- | +| **Providers** |  | +| **Combos** |  | +| **Analytics** |  | +| **Health** |  | +| **Translator** |  | +| **Settings** |  | +| **CLI Tools** |  | +| **Usage Logs** |  | +| **Endpoints** |  | + +|
-
+
OpenClaw @@ -92,586 +162,527 @@ _通过 OmniRoute 连接任何 AI 驱动的 IDE 或 CLI 工具 — 免费 API |
http://localhost:20128/v1 或 http://cloud.omniroute.online/v1 连接 — 一个配置，无限模型和配额
+📡 All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 — one config, unlimited models and quota
---
-### 🆕 What's New in v3.0.0
+## 🤔 Why OmniRoute?
-| Area | Change |
-| ------------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal ` Subscription quota expires unused every month
+- Rate limits stop you mid-coding
+- Expensive APIs ($20-50/month per provider)
+- Manual switching between providers
-| Area | Change |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| 🔒 **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection |
-| ✅ **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` |
-| 🐛 **omniModel Tag Leak** | Internal `
-
-
-
----
-
-## 📸
-
-
-
-
-
----
-
-## 🤔 为什么选择 OmniRoute？
-
-**停止浪费金钱和遭遇限制：**
-
-- ...
- -| # | # | -| ----- | ---------------------------------------- | -| **1** |  | -| **2** |  | -| **3** |  | -| **4** |  | -| **5** |  | -| **6** |  | -| **7** |  | -| **8** |  | -| **9** |  | - - 订阅配额每月未使用就过期
-- 速率限制在编程中途停止你
-- 昂贵的 API（每个提供商 $20-50/月）
-- 手动在提供商间切换
-
-**OmniRoute 解决这些问题：**
-
-- ✅ **最大化订阅** — 追踪配额，在重置前用完每一点
-- ✅ **自动故障转移** — 订阅 → API Key → 低价 → 免费，零停机
-- ✅ **多账号** — 每个提供商的账号轮询
-- ✅ **通用** — 适用于 Claude Code、Codex、Gemini CLI、Cursor、Cline、OpenClaw、任何 CLI 工具
-
----
-
-## 📧 支持
-
-> 💬 **加入我们的社区！** [WhatsApp 群组](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — 获取帮助、分享技巧、了解最新动态。
-
-- **网站**: [omniroute.online](https://omniroute.online)
+- **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**: [社区群组](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-- **原始项目**: [decolua 的 9router](https://github.com/decolua/9router)
+- **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`
+- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
+
+### 🐛 Reporting a Bug?
+
+When opening an issue, please run the system-info command and attach the generated file:
+
+```bash
+npm run system-info
+```
+
+This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (iflow, 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.
---
-## 🔄 工作原理
+## 🔄 How It Works
```
┌─────────────┐
-│ 您的 CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
-│ 工具 │
+│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
+│ Tool │
└──────┬──────┘
│ http://localhost:20128/v1
↓
┌─────────────────────────────────────────┐
-│ OmniRoute（智能路由器） │
-│ • 格式转换（OpenAI ↔ Claude） │
-│ • 配额追踪 + Embeddings + 图像 │
-│ • 自动令牌刷新 │
+│ OmniRoute (Smart Router) │
+│ • Format translation (OpenAI ↔ Claude) │
+│ • Quota tracking + Embeddings + Images │
+│ • Auto token refresh │
└──────┬──────────────────────────────────┘
│
- ├─→ [第1层: 订阅] Claude Code, Codex, Gemini CLI
- │ ↓ 配额用完
- ├─→ [第2层: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM 等
- │ ↓ 预算限制
- ├─→ [第3层: 低价] GLM ($0.6/1M), MiniMax ($0.2/1M)
- │ ↓ 预算限制
- └─→ [第4层: 免费] iFlow, Qwen, Kiro（无限制）
+ ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI
+ │ ↓ 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] iFlow, Qwen, Kiro (unlimited)
-结果：永不停止编程，成本最低
+Result: Never stop coding, minimal cost
```
---
-## 🎯 OmniRoute 解决了什么 — 30 个真正的痛点和用例
+## 🎯 What OmniRoute Solves — 30 Real Pain Points & Use Cases
-> **每个使用 AI 工具的开发人员每天都会面临这些问题。** OmniRoute 的构建是为了解决所有这些问题 - 从成本超支到区域封锁，从损坏的 OAuth 流程到协议操作和企业可观察性。
+> **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.
-
💸 1.“我支付了昂贵的订阅费用，但仍然受到限制的干扰”
+💸 1. "I pay for an expensive subscription but still get interrupted by limits"
-开发人员每月为 Claude Pro、Codex Pro 或 GitHub Copilot 支付 20-200 美元。即使付费，配额也有上限——5 小时的使用时间、每周限制或每分钟的费率限制。在编码会话中，提供商停止响应，开发人员失去流量和生产力。 +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. -**OmniRoute 如何解决：** +**How OmniRoute solves it:** -- **智能 4 层回退** — 如果订阅配额用完，自动重定向到 API 密钥 → 便宜 → 免费，零手动干预 -- **实时配额跟踪** — 实时显示代币消耗情况并重置倒计时（5 小时、每日、每周） -- **多帐户支持** — 每个提供商有多个帐户，具有自动循环 — 当一个帐户用完时，切换到下一个帐户 -- **自定义组合** — 可定制的后备链，具有 6 种平衡策略（先填充、循环、P2C、随机、最少使用、成本优化） -- **Codex Business Quotas** — 直接在仪表板中监控业务/团队工作空间配额 +- **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention +- **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly) +- **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 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard
-` 块提取为标准化 `reasoning_content`
-- **Gemini 的结构化输出** — `json_schema` → `responseMimeType`/`responseSchema` 自动转换
-- **`stream` 默认为 `false`** — 与 OpenAI 规范保持一致，避免 Python/Rust/Go SDK 中出现意外的 SSE
+- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 67+ 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
🔌 2.“我需要使用多个提供程序，但每个提供程序都有不同的 API”
+🔌 2. "I need to use multiple providers but each has a different API"
-OpenAI 使用一种格式，Claude（Anthropic）使用另一种格式，Gemini 使用另一种格式。如果开发人员想要测试来自不同提供商的模型或在它们之间进行回退，他们需要重新配置 SDK、更改端点、处理不兼容的格式。自定义提供程序（FriendLI、NIM）具有非标准模型端点。 +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. -**OmniRoute 如何解决：** +**How OmniRoute solves it:** -- **统一端点** — 单个 `http://localhost:20128/v1` 充当所有 36 个以上提供商的代理 -- **格式翻译** — 自动且透明：OpenAI ↔ Claude ↔ Gemini ↔ Responses API -- **响应清理** — 删除破坏 OpenAI SDK v1.83+ 的非标准字段（`x_groq`、`usage_breakdown`、`service_tier`） -- **角色标准化** — 对于非 OpenAI 提供商，将 `developer` → `system` 转换； `system` → `user` 适用于 GLM/ERNIE -- **Think Tag Extraction** — 将 DeepSeek R1 等模型中的 `
-
🌐 3.“我的人工智能提供商封锁了我的地区/国家”
+🌐 3. "My AI provider blocks my region/country"
-OpenAI/Codex 等提供商会阻止来自某些地理区域的访问。用户在 OAuth 和 API 连接期间收到类似 `unsupported_country_region_territory` 的错误。这对于发展中国家的开发商来说尤其令人沮丧。 +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. -**OmniRoute 如何解决：** +**How OmniRoute solves it:** -- **3 级代理配置** — 3 级可配置代理：全局（所有流量）、每个提供商（仅一个提供商）和每个连接/密钥 -- **颜色编码的代理徽章** — 视觉指示器：🟢 全局代理、🟡 提供商代理、🔵 连接代理，始终显示 IP -- **通过代理进行 OAuth 令牌交换** — OAuth 流程也通过代理，解决了 `unsupported_country_region_territory` -- **通过代理进行连接测试** — 连接测试使用配置的代理（不再直接绕过） -- **SOCKS5 支持** — 对出站路由的完整 SOCKS5 代理支持 -- **TLS 指纹欺骗** — 通过 `wreq-js` 的类似浏览器的 TLS 指纹来绕过机器人检测 +- **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
-` prefix
-- **仅限免费组合** — 链 `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = 0 美元/月，零停机时间
-- **NVIDIA NIM 免费积分** — 集成 1000 个免费积分
-- **成本优化策略** — 自动选择最便宜的可用提供商的路由策略
+- **Free-Only Combos** — Chain `gc/gemini-3-flash → 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
🆓 4.“我想用AI编码，但我没有钱”
+🆓 4. "I want to use AI for coding but I have no money"
-并不是每个人都能每月支付 20-200 美元来订阅 AI。来自新兴国家的学生、开发人员、业余爱好者和自由职业者需要以零成本获得优质模型。 +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. -**OmniRoute 如何解决：** +**How OmniRoute solves it:** -- **内置免费层级提供商** — 对 100% 免费提供商的本机支持：iFlow（8 个无限型号）、Qwen（3 个无限型号）、Kiro（Claude 免费）、Gemini CLI（180K/月免费） +- **Free Tier Providers Built-in** — Native support for 100% free providers: iFlow (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free) - **Ollama Cloud** — Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/
-
🔒 5.“我需要保护我的AI网关免遭未经授权的访问”
+🔒 5. "I need to protect my AI gateway from unauthorized access"
-当将人工智能网关暴露到网络（LAN、VPS、Docker）时，任何拥有该地址的人都可以消耗开发者的代币/配额。如果没有保护，API 很容易被误用、提示注入和滥用。 +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. -**OmniRoute 如何解决：** +**How OmniRoute solves it:** -- **API 密钥管理** — 使用专用的 `/dashboard/api-manager` 页面为每个提供商生成、轮换和范围界定 -- **模型级权限** — 将 API 密钥限制为特定模型（`openai/*`、通配符模式），并具有“允许全部”/“限制”切换功能 -- **API 端点保护** — 需要 `/v1/models` 的密钥并阻止列表中的特定提供商 -- **Auth Guard + CSRF 保护** — 所有仪表板路由均受 `withAuth` 中间件 + CSRF 令牌保护 -- **速率限制器** — 通过可配置窗口限制每个 IP 的速率 -- **IP 过滤** — 用于访问控制的允许列表/阻止列表 -- **Prompt Injection Guard** — 针对恶意提示模式的清理 -- **AES-256-GCM 加密** — 静态加密的凭证 +- **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.“我的提供商宕机了，我失去了编码流程”
+🛑 6. "My provider went down and I lost my coding flow"
-AI 提供商可能会变得不稳定、返回 5xx 错误或达到临时速率限制。如果开发人员依赖于单一提供商，他们就会受到干扰。如果没有断路器，重复重试可能会使应用程序崩溃。 +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. -**OmniRoute 如何解决：** +**How OmniRoute solves it:** -- **每个提供商的断路器** — 自动打开/关闭，具有可配置的阈值和冷却时间（关闭/打开/半打开） -- **指数退避** — 渐进式重试延迟 -- **Anti-Thundering Herd** — 互斥锁 + 信号量保护，防止并发重试风暴 -- **组合后备链** — 如果主要提供商发生故障，则自动从该链中掉下来，无需干预 -- **组合断路器** — 自动禁用组合链中出现故障的提供商 -- **运行状况仪表板** — 正常运行时间监控、断路器状态、锁定、缓存统计、p50/p95/p99 延迟 +- **Circuit Breaker per-model** — Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks +- **Exponential Backoff** — Progressive retry delays +- **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 +- **Combo Circuit Breaker** — Auto-disables failing providers within a combo chain +- **Health Dashboard** — Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
-
🔧 7. “配置每个AI工具都是繁琐且重复的”
+🔧 7. "Configuring each AI tool is tedious and repetitive"
-开发人员使用 Cursor、Claude Code、Codex CLI、OpenClaw、Gemini CLI、Kilo Code...每个工具都需要不同的配置（API 端点、密钥、模型）。切换提供商或模型时重新配置是浪费时间。 +Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time. -**OmniRoute 如何解决：** +**How OmniRoute solves it:** -- **CLI 工具仪表板** — 专用页面，可一键设置 Claude Code、Codex CLI、OpenClaw、Kilo Code、Antigravity、Cline -- **GitHub Copilot 配置生成器** — 通过批量模型选择为 VS Code 生成 `chatLanguageModels.json` -- **入门向导** — 为首次使用的用户提供 4 步设置指导 -- **一个端点，所有型号** — 配置 `http://localhost:20128/v1` 一次，访问 36 个以上提供商 +- **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 67+ providers
-
🔑 8.“管理来自多个提供商的 OAuth 令牌简直就是地狱”
+🔑 8. "Managing OAuth tokens from multiple providers is hell"
-Claude Code、Codex、Gemini CLI、Copilot — 全部使用带有过期令牌的 OAuth 2.0。开发人员需要不断地重新进行身份验证，处理`client_secret is missing`、`redirect_uri_mismatch`以及远程服务器上的故障。 LAN/VPS 上的 OAuth 问题尤其严重。 +Claude Code, Codex, Gemini CLI, 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. -**OmniRoute 如何解决：** +**How OmniRoute solves it:** -- **自动令牌刷新** — OAuth 令牌在过期前在后台刷新 -- **OAuth 2.0 (PKCE) 内置** — Claude Code、Codex、Gemini CLI、Copilot、Kiro、Qwen、iFlow 的自动流程 -- **多帐户 OAuth** — 每个提供商通过 JWT/ID 令牌提取多个帐户 -- **OAuth LAN/远程修复** — `redirect_uri` 的私有 IP 检测 + 远程服务器的手动 URL 模式 -- **Nginx 背后的 OAuth** — 使用 `window.location.origin` 实现反向代理兼容性 -- **远程 OAuth 指南** — VPS/Docker 上的 Google Cloud 凭据分步指南 +- **Auto Token Refresh** — OAuth tokens refresh in background before expiration +- **OAuth 2.0 (PKCE) Built-in** — Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow +- **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.“我不知道我花了多少钱或在哪里”
+📊 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. -**OmniRoute 如何解决：** +**How OmniRoute solves it:** -- **成本分析仪表板** — 每个提供商的每个代币成本跟踪和预算管理 -- **每层预算限制** — 触发自动回退的每层支出上限 -- **按型号定价配置** — 每个型号的可配置价格 -- **每个 API 密钥的使用统计信息** — 每个密钥的请求计数和上次使用的时间戳 -- **分析仪表板** — 统计卡、模型使用图表、包含成功率和延迟的提供商表 +- **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.“我无法诊断人工智能调用中的错误和问题”
+🐛 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. -**OmniRoute 如何解决：** +**How OmniRoute solves it:** -- **统一日志仪表板** — 4 个选项卡：请求日志、代理日志、审核日志、控制台 -- **控制台日志查看器** — 实时终端式查看器，具有颜色编码级别、自动滚动、搜索、过滤功能 -- **SQLite 代理日志** — 服务器重新启动后仍保留的持久日志 -- **Translator Playground** — 4 种调试模式：Playground（格式翻译）、Chat Tester（往返）、Test Bench（批量）、Live Monitor（实时） -- **请求遥测** — p50/p95/p99 延迟 + X-Request-Id 跟踪 -- **基于文件的日志记录与旋转** — 控制台拦截器通过基于大小的旋转将所有内容捕获到 JSON 日志 +- **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 Proxy Logs** — Persistent logs that survive server restarts +- **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 Logging with Rotation** — Console interceptor captures everything to JSON log with size-based rotation +- **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.“部署和维护网关很复杂”
+🏗️ 11. "Deploying and maintaining the gateway is complex"
-跨不同环境（本地、VPS、Docker、云）安装、配置和维护 AI 代理是一项劳动密集型工作。硬编码路径、目录上的 `EACCES`、端口冲突和跨平台构建等问题会增加摩擦。 +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. -**OmniRoute 如何解决：** +**How OmniRoute solves it:** -- **npm 全局安装** — `npm install -g omniroute && omniroute` — 完成 -- **Docker 多平台** — AMD64 + ARM64 本机（Apple Silicon、AWS Graviton、Raspberry Pi） -- **Docker Compose Profiles** — `base`（无 CLI 工具）和 `cli`（带有 Claude Code、Codex、OpenClaw） -- **Electron 桌面应用程序** — 适用于 Windows/macOS/Linux 的本机应用程序，带系统托盘、自动启动、离线模式 -- **分割端口模式** — API 和仪表板位于单独的端口上，适用于高级场景（反向代理、容器网络） -- **云同步** — 通过 Cloudflare Workers 跨设备配置同步 -- **数据库备份** — 自动备份、恢复、导出和导入所有设置 +- **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
-
🌍 12.“界面只有英文，我的团队不会说英语”
+🌍 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. -**OmniRoute 如何解决：** +**How OmniRoute solves it:** -- **仪表板 i18n — 30 种语言** — 所有 500 多个按键已翻译，包括阿拉伯语、保加利亚语、丹麦语、德语、西班牙语、芬兰语、法语、希伯来语、印地语、匈牙利语、印度尼西亚语、意大利语、日语、韩语、马来语、荷兰语、挪威语、波兰语、葡萄牙语（PT/BR）、罗马尼亚语、俄语、斯洛伐克语、瑞典语、泰语、乌克兰语、越南语、中文、菲律宾语、英语 -- **RTL 支持** — 从右到左支持阿拉伯语和希伯来语 -- **多语言自述文件** — 30 个完整的文档翻译 -- **语言选择器** — 标题中的地球图标用于实时切换 +- **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.“我需要的不仅仅是聊天 - 我需要嵌入、图像、音频”
+🔄 13. "I need more than chat — I need embeddings, images, audio"
-人工智能不仅仅是完成聊天。开发人员需要生成图像、转录音频、为 RAG 创建嵌入、重新排列文档以及审核内容。每个 API 都有不同的端点和格式。 +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. -**OmniRoute 如何解决：** +**How OmniRoute solves it:** -- **嵌入** — `/v1/embeddings` 具有 6 个提供商和 9 个以上模型 -- **图像生成** — `/v1/images/generations` 具有 10 个提供商和 20 多个模型（OpenAI、xAI、Together、Fireworks、Nebius、Hyperbolic、NanoBanana、Antigravity、SD WebUI、ComfyUI） -- **文本到视频** — `/v1/videos/generations` — ComfyUI（AnimateDiff、SVD）和 SD WebUI -- **文本转音乐** — `/v1/music/generations` — ComfyUI（稳定音频打开，MusicGen） -- **音频转录** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM、HuggingFace、Qwen3 -- **文本转语音** — `/v1/audio/speech` — ElevenLabs、Nvidia NIM、HuggingFace、Coqui、Tortoise、Qwen3 以及现有提供商 -- **审核** — `/v1/moderations` — 内容安全检查 -- **重新排名** — `/v1/rerank` — 文档相关性重新排名 -- **响应 API** — 对 Codex 的完整 `/v1/responses` 支持 +- **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.“我无法测试和比较不同型号的质量”
+🧪 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. -**OmniRoute 如何解决：** +**How OmniRoute solves it:** -- **LLM 评估** — 黄金套装测试，包含 10 个预加载案例，涵盖问候语、数学、地理、代码生成、JSON 合规性、翻译、降价、安全拒绝 -- **4种匹配策略** — `exact`、`contains`、`regex`、`custom`（JS函数） -- **Translator Playground 测试台** — 使用多个输入和预期输出进行批量测试、跨提供商比较 -- **聊天测试器** — 带有视觉响应渲染的完整往返 -- **实时监控** — 流经代理的所有请求的实时流 +- **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.“我需要在不损失性能的情况下进行扩展”
+📈 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. -**OmniRoute 如何解决：** +**How OmniRoute solves it:** -- **语义缓存** - 两层缓存（签名+语义）降低成本和延迟 -- **请求幂等性** — 相同请求的 5 秒重复数据删除窗口 -- **速率限制检测** — 每个提供商的 RPM、最小间隙和最大并发跟踪 -- **可编辑的速率限制** — 可在“设置”→“持久弹性”中配置默认值 -- **API 密钥验证缓存** — 用于提高生产性能的 3 层缓存 -- **带有遥测功能的运行状况仪表板** — p50/p95/p99 延迟、缓存统计数据、正常运行时间 +- **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 +- **Editable Rate Limits** — Configurable defaults in Settings → Resilience with persistence +- **API Key Validation Cache** — 3-tier cache for production performance +- **Health Dashboard with Telemetry** — p50/p95/p99 latency, cache stats, uptime
-
🤖 16.“我想全局控制模型行为”
+🤖 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. -**OmniRoute 如何解决：** +**How OmniRoute solves it:** -- **系统提示注入** — 全局提示应用于所有请求 -- **思考预算验证** - 每个请求的推理令牌分配控制（直通、自动、自定义、自适应） -- **6 种路由策略** — 确定如何分发请求的全局策略 -- **通配符路由器** — `provider/*` 模式动态路由到任何提供商 -- **组合启用/禁用切换** — 直接从仪表板切换组合 -- **提供商切换** — 一键启用/禁用提供商的所有连接 -- **阻止的提供商** — 从 `/v1/models` 列表中排除特定提供商 +- **System Prompt Injection** — Global prompt applied to all requests +- **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive) +- **6 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 +- **Provider Toggle** — Enable/disable all connections for a provider with one click +- **Blocked Providers** — Exclude specific providers from `/v1/models` listing
-
🧰 17.“我需要MCP工具作为一流的产品能力”
+🧰 17. "I need MCP tools as first-class product capabilities"
-许多 AI 网关仅将 MCP 作为隐藏的实现细节公开。团队需要一个可见的、可管理的操作层。 +Many AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer. -**OmniRoute 如何解决：** +**How OmniRoute solves it:** -- MCP 显示在仪表板导航和端点协议选项卡中 -- 专用 MCP 管理页面，包含流程、工具、范围和审计 -- `omniroute --mcp` 和客户入门的内置快速启动 +- 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.“我需要具有同步+流任务路径的 A2A 编排”
+🧠 18. "I need A2A orchestration with sync + stream task paths"
-代理工作流程需要直接回复和具有生命周期控制的长时间运行的流式执行。 +Agent workflows need both direct replies and long-running streamed execution with lifecycle control. -**OmniRoute 如何解决：** +**How OmniRoute solves it:** -- A2A JSON-RPC 端点 (`POST /a2a`) 与 `message/send` 和 `message/stream` -- 具有终端状态传播的 SSE 流式传输 -- `tasks/get` 和 `tasks/cancel` 的任务生命周期 API +- 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.“我需要真实的 MCP 进程运行状况，而不是猜测的状态”
+🛰️ 19. "I need real MCP process health, not guessed status"
-运营团队需要知道 MCP 是否确实存在，而不仅仅是 API 是否可访问。 +Operational teams need to know if MCP is actually alive, not just whether an API is reachable. -**OmniRoute 如何解决：** +**How OmniRoute solves it:** -- 带有 PID、时间戳、传输、工具计数和范围模式的运行时心跳文件 -- MCP状态API结合心跳+最近的活动 -- 用于流程/正常运行时间/心跳新鲜度的 UI 状态卡 +- 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.“我需要可审核的 MCP 工具执行”
+📋 20. "I need auditable MCP tool execution"
-当工具改变配置或触发操作操作时，团队需要取证可追溯性。 +When tools mutate config or trigger ops actions, teams need forensic traceability. -**OmniRoute 如何解决：** +**How OmniRoute solves it:** -- SQLite 支持的 MCP 工具调用审核日志记录 -- 按工具、成功/失败、API 密钥和分页过滤 -- 仪表板审核表+自动化统计端点 +- 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.“每次集成我都需要范围内的 MCP 权限”
+🔐 21. "I need scoped MCP permissions per integration"
-不同的客户端应该具有对工具类别的最低权限访问权限。 +Different clients should have least-privilege access to tool categories. -**OmniRoute 如何解决：** +**How OmniRoute solves it:** -- 9 个粒度 MCP 范围，用于受控工具访问 -- MCP 管理 UI 中的范围执行和可见性 -- 操作工具的安全默认姿势 +- 9 granular MCP scopes for controlled tool access +- Scope enforcement and visibility in MCP management UI +- Safe default posture for operational tooling
-
⚙️ 22.“我需要操作控制而不重新部署”
+⚙️ 22. "I need operational controls without redeploying"
-团队需要在事件或成本事件期间快速更改运行时。 +Teams need quick runtime changes during incidents or cost events. -**OmniRoute 如何解决：** +**How OmniRoute solves it:** -- 直接从 MCP 仪表板切换组合激活 -- 应用预定义策略包中的弹性配置文件 -- 从同一操作面板重置断路器状态 +- Switch combo activation directly from MCP dashboard +- Apply resilience profiles from pre-defined policy packs +- Reset circuit breaker state from the same operations panel
-
🔄 23.“我需要实时 A2A 任务生命周期可见性和取消”
+🔄 23. "I need live A2A task lifecycle visibility and cancellation"
-如果没有生命周期可见性，任务事件就很难分类。 +Without lifecycle visibility, task incidents become hard to triage. -**OmniRoute 如何解决：** +**How OmniRoute solves it:** -- 任务列表/按状态/技能过滤并分页 -- 深入了解任务元数据、事件和工件 -- 任务取消端点和带有确认的 UI 操作 +- 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.“我需要 A2A 负载的活动流指标”
+🌊 24. "I need active stream metrics for A2A load"
-流媒体工作流程需要对并发和实时连接的操作洞察。 +Streaming workflows require operational insight into concurrency and live connections. -**OmniRoute 如何解决：** +**How OmniRoute solves it:** -- 活动流计数器集成到 A2A 状态中 -- 最后任务时间戳和每个状态计数 -- 用于实时操作监控的 A2A 仪表板卡 +- Active stream counters integrated into A2A status +- Last task timestamp and per-state counts +- A2A dashboard cards for real-time ops monitoring
-
🪪 25.“我需要为客户发现标准代理”
+🪪 25. "I need standard agent discovery for clients"
-外部客户端和协调器需要机器可读的元数据来进行引导。 +External clients and orchestrators need machine-readable metadata for onboarding. -**OmniRoute 如何解决：** +**How OmniRoute solves it:** -- 特工卡暴露在`/.well-known/agent.json` -- 管理 UI 中显示的能力和技能 -- A2A 状态 API 包括用于自动化的发现元数据 +- Agent Card exposed at `/.well-known/agent.json` +- Capabilities and skills shown in management UI +- A2A status API includes discovery metadata for automation
-
🧭 26.“我需要产品 UX 中的协议可发现性”
+🧭 26. "I need protocol discoverability in the product UX"
-如果用户无法发现协议表面，采用和支持质量就会下降。 +If users cannot discover protocol surfaces, adoption and support quality drop. -**OmniRoute 如何解决：** +**How OmniRoute solves it:** -- MCP 和 A2A 的侧边栏条目 -- 端点页面“协议”选项卡包含快速启动和状态 -- 从概述到专用管理仪表板的链接 +- 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.“我需要与真实客户端进行端到端协议验证”
+🧪 27. "I need end-to-end protocol validation with real clients"
-模拟测试不足以在发布前验证协议兼容性。 +Mock tests are not enough to validate protocol compatibility before release. -**OmniRoute 如何解决：** +**How OmniRoute solves it:** -- E2E 套件，可启动应用程序并使用真正的 MCP SDK 客户端传输 -- A2A 客户端测试发现、发送、流式传输、获取和取消流程 -- 针对 MCP 审计和 A2A 任务 API 交叉检查断言 +- 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.“我需要跨所有接口的统一可观察性”
+📡 28. "I need unified observability across all interfaces"
-按协议分割可观察性会产生盲点和更长的 MTTR。 +Splitting observability by protocol creates blind spots and longer MTTR. -**OmniRoute 如何解决：** +**How OmniRoute solves it:** -- 一个产品中的统一仪表板/日志/分析 -- 跨 OpenAI、MCP 和 A2A 层的运行状况 + 审计 + 请求遥测 -- 用于状态和自动化的操作 API +- Unified dashboards/logs/analytics in one product +- Health + audit + request telemetry across OpenAI, MCP, and A2A layers +- Operational APIs for status and automation
-
💼 29.“我需要一个用于代理+工具+代理编排的运行时”
+💼 29. "I need one runtime for proxy + tools + agent orchestration"
-运行许多单独的服务会增加运营成本和故障模式。 +Running many separate services increases operational cost and failure modes. -**OmniRoute 如何解决：** +**How OmniRoute solves it:** -- 兼容 OpenAI 的代理、MCP 服务器和 A2A 服务器位于一个堆栈中 -- 共享身份验证、弹性、数据存储和可观察性 -- 所有交互界面上一致的策略模型 +- 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
-
-### 示例手册（集成用例）
+### Example Playbooks (Integrated Use Cases)
-**剧本 A：最大化付费订阅 + 廉价备份**
+**Playbook A: Maximize paid subscription + cheap backup**
```txt
Combo: "maximize-claude"
@@ -683,7 +694,7 @@ Monthly cost: $20 + small backup spend
Outcome: higher quality, near-zero interruption
```
-**剧本 B：零成本编码堆栈**
+**Playbook B: Zero-cost coding stack**
```txt
Combo: "free-forever"
@@ -695,7 +706,7 @@ Monthly cost: $0
Outcome: stable free coding workflow
```
-**剧本 C：24/7 始终在线的后备链**
+**Playbook C: 24/7 always-on fallback chain**
```txt
Combo: "always-on"
@@ -708,65 +719,132 @@ Combo: "always-on"
Outcome: deep fallback depth for deadline-critical workloads
```
-**剧本 D：使用 MCP + A2A 的特工操作**
+**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/mcp and /dashboard/a2a
-4) Control incidents with resilience profile + task cancellation
+3) Observe via /dashboard/endpoint (MCP and A2A tabs)
+4) Toggle services via inline status controls
```
---
-## ⚡ 快速开始
+## 🆓 Start Free — Zero Configuration Cost
-**1. 全局安装：**
+> 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 **iFlow** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |
+| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |
+| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |
+| 5 | `/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).
+
+## 快速开始
+
+### 1) Install and run
```bash
npm install -g omniroute
omniroute
```
-🎉 仪表板在 `http://localhost:20128` 打开
+> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`:
+>
+> ```bash
+> pnpm install -g omniroute
+> pnpm approve-builds -g # Select all packages → approve
+> omniroute
+> ```
-| 命令 | 描述 |
-| ----------------------- | ---------------------------- |
-| `omniroute` | 启动服务器（默认端口 20128） |
-| `omniroute --port 3000` | 使用自定义端口 |
-| `omniroute --no-open` | 不自动打开浏览器 |
-| `omniroute --help` | 显示帮助 |
+Dashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.
-**2. 连接免费提供商：**
+| 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 |
-仪表板 → 提供商 → 连接 **Claude Code** 或 **Antigravity** → OAuth 登录 → 完成！
+Optional split-port mode:
-**3. 在 CLI 工具中使用：**
-
-```
-Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline 设置：
- Endpoint: http://localhost:20128/v1
- API Key: [从仪表板复制]
- Model: if/kimi-k2-thinking
+```bash
+PORT=20128 DASHBOARD_PORT=20129 omniroute
+# API: http://localhost:20128/v1
+# Dashboard: http://localhost:20129
```
-**完成！** 开始使用免费 AI 模型编程。
+### 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
+
+```txt
+Base URL: http://localhost:20128/v1
+API Key: [copy from Endpoint page]
+Model: if/kimi-k2-thinking (or any provider/model prefix)
+```
+
+Works with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.
+
+### 4) Enable and validate protocols (v2.0)
+
+**MCP (for tool-driven operations):**
+
+```bash
+omniroute --mcp
+```
+
+Then connect your MCP client over `stdio` and test tools like:
+
+- `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 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
+PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev
```
---
## 🐳 Docker
-OmniRoute 作为公共 Docker 镜像在 [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute) 上可用。
+OmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
-**快速运行：**
+**Quick run:**
```bash
docker run -d \
@@ -777,10 +855,10 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**使用环境文件：**
+**With environment file:**
```bash
-# 先复制并编辑 .env
+# Copy and edit .env first
cp .env.example .env
docker run -d \
@@ -792,293 +870,627 @@ docker run -d \
diegosouzapw/omniroute:latest
```
-**使用 Docker Compose：**
+**Using Docker Compose:**
```bash
-# 基础配置（无 CLI 工具）
+# Base profile (no CLI tools)
docker compose --profile base up -d
-# CLI 配置（内置 Claude Code、Codex、OpenClaw）
+# CLI profile (Claude Code, Codex, OpenClaw built-in)
docker compose --profile cli up -d
```
-| 镜像 | 标签 | 大小 | 描述 |
-| ------------------------ | -------- | ------ | ---------- |
-| `diegosouzapw/omniroute` | `latest` | ~250MB | 最新稳定版 |
-| `diegosouzapw/omniroute` | `1.0.6` | ~250MB | 当前版本 |
+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.
+- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.
+- 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` | `1.0.3` | ~250MB | Current version |
---
----
+## 🖥️ Desktop App — Offline & Always-On
-## 🖥️
+> 🆕 **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux.
-> 🆕 **全新！** OmniRoute 现已提供适用于 Windows、macOS 和 Linux 的**原生桌面应用程序**。
+Run OmniRoute as a standalone desktop app — no terminal, no browser, no internet required for local models. The Electron-based app includes:
-- 🖥️ **原生窗口** — 专属应用窗口，集成系统托盘
-- 🔄 **自动启动** — 系统登录时启动 OmniRoute
-- 🔔 **原生通知** — 配额耗尽或提供商问题时收到提醒
-- ⚡ **一键安装** — NSIS (Windows)、DMG (macOS)、AppImage (Linux)
-- 🌐 **离线模式** — 内置服务器，完全离线工作
+- 🖥️ **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
+
+### 快速开始
```bash
-npm run electron:dev # 开发模式
-npm run electron:build # 当前平台
+# 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)
+npm run electron:build:mac # macOS (.dmg) — x64 & arm64
npm run electron:build:linux # Linux (.AppImage)
```
-📖 完整文档：[`electron/README.md`](electron/README.md)
+### 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
-| 层级 | 提供商 | 费用 | 配额重置 | 最适合 |
-| -------------- | ----------------- | --------------------- | --------------- | ------------ |
-| **💳 订阅** | Claude Code (Pro) | $20/月 | 5小时 + 每周 | 已订阅用户 |
-| | Codex (Plus/Pro) | $20-200/月 | 5小时 + 每周 | OpenAI 用户 |
-| | Gemini CLI | **免费** | 180K/月 + 1K/天 | 所有人！ |
-| | GitHub Copilot | $10-19/月 | 每月 | GitHub 用户 |
-| **🔑 API KEY** | NVIDIA NIM | **免费**（1000 积分） | 一次性 | 免费测试 |
-| | DeepSeek | 按使用量 | 无 | 最佳性价比 |
-| | Groq | 免费层 + 付费 | 限速 | 超快推理 |
-| | xAI (Grok) | 按使用量 | 无 | Grok 模型 |
-| | Mistral | 免费层 + 付费 | 限速 | 欧洲 AI |
-| | OpenRouter | 按使用量 | 无 | 100+ 模型 |
-| **💰 低价** | GLM-4.7 | $0.6/1M | 每日 10时 | 经济备用 |
-| | MiniMax M2.1 | $0.2/1M | 5小时滚动 | 最便宜选项 |
-| | Kimi K2 | $9/月固定 | 每月 10M Token | 可预测成本 |
-| **🆓 免费** | iFlow | $0 | 无限制 | 8 个免费模型 |
-| | Qwen | $0 | 无限制 | 3 个免费模型 |
-| | Kiro | $0 | 无限制 | 免费 Claude |
+| 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 |
+| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |
+| | 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** | iFlow | **$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 |
-**💡 专业建议：** 从 Gemini CLI（每月 180K 免费）+ iFlow（无限免费）开始 = $0 成本！
+> 🆕 **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
+iFlow (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
-| 功能 | 功能描述 |
-| ----------------------------- | ----------------------------------------------------------------------------- |
-| 🎯 **智能 4 层故障转移** | 自动路由：订阅 → API Key → 低价 → 免费 |
-| 📊 **实时配额追踪** | 实时 Token 计数 + 每个提供商的重置倒计时 |
-| 🔄 **格式转换** | OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro 无缝切换 |
-| 👥 **多账号支持** | 每个提供商多个账号，智能选择 |
-| 🔄 **自动令牌刷新** | OAuth 令牌自动刷新并重试 |
-| 🎨 **自定义组合** | 6 种策略：fill-first、round-robin、p2c、random、least-used、cost-optimized |
-| 🧩 **自定义模型** | 为任何提供商添加任何模型 ID |
-| 🌐 **通配符路由** | 动态路由 `provider/*` 模式到任何提供商 |
-| 🧠 **推理预算** | passthrough、auto、custom 和 adaptive 模式用于推理模型 |
-| 🔀 **Model Aliases** | Auto-forward deprecated model IDs to current replacements (built-in + custom) |
-| ⚡ **Background Degradation** | Auto-route background tasks (titles, summaries) to cheaper models |
-| 💬 **System Prompt 注入** | 全局 System Prompt 应用于所有请求 |
-| 📄 **Responses API** | 完整支持 OpenAI Responses API (`/v1/responses`) 用于 Codex |
+> 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.
-### 🎵 多模态 API
+### 🔵 CLAUDE MODELS (via Kiro — AWS Builder ID)
-| 功能 | 功能描述 |
-| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 🖼️ **图像生成** | `/v1/images/generations` — 4 个提供商，9+ 模型 |
-| 📐 **Embeddings** | `/v1/embeddings` — 6 个提供商，9+ 模型 |
-| 🎤 **音频转录** | `/v1/audio/transcriptions` — 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support |
-| 🔊 **文字转语音** | `/v1/audio/speech` — 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) |
-| 🛡️ **内容审核** | `/v1/moderations` — 内容安全检查 |
-| 🔀 **重排序** | `/v1/rerank` — 文档相关性重排序 |
+| 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 |
-### 🛡️ 弹性与安全
+### 🟢 IFLOW MODELS (Free OAuth — No Credit Card)
-| 功能 | 功能描述 |
-| ------------------------------- | ---------------------------------------------------------------------------- |
-| 🔌 **断路器** | 每个提供商自动打开/关闭，可配置阈值 |
-| 🛡️ **反惊群** | Mutex + 信号量限速用于 API Key 提供商 |
-| 🧠 **语义缓存** | 两层缓存（签名 + 语义）降低成本和延迟 |
-| ⚡ **请求幂等性** | 5 秒去重窗口防止重复请求 |
-| 🔒 **TLS 指纹伪装** | 通过 wreq-js 绕过基于 TLS 的机器人检测 |
-| 🌐 **IP 过滤** | 白名单/黑名单用于 API 访问控制 |
-| 📊 **可编辑速率限制** | 可配置的 RPM、最小间隔和最大并发 |
-| 💾 **Rate Limit Persistence** | Learned limits survive restarts via SQLite with 60s debounce + 24h staleness |
-| 🔄 **Token Refresh Resilience** | Per-provider circuit breaker (5 fails→30min) + 30s timeout per attempt |
+| 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 |
-### 📊 可观察性与分析
+### 🟡 QWEN MODELS (Device Code Auth)
-| 功能 | 功能描述 |
-| -------------------------------- | ---------------------------------------------------- |
-| 📝 **请求日志** | 调试模式，完整的请求/响应日志 |
-| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI |
-| 💾 **SQLite 日志** | 持久化代理日志，服务器重启后仍然保留 |
-| 📊 **分析仪表板** | Recharts：统计卡片、使用量图表、提供商表格 |
-| 📈 **进度追踪** | 流式传输的 SSE 进度事件（可选） |
-| 🧪 **LLM 评估** | 黄金集测试，4 种匹配策略 |
-| 🔍 **请求遥测** | p50/p95/p99 延迟聚合 + X-Request-Id 追踪 |
-| 📋 **日志 + 配额** | 专用页面用于日志浏览和配额追踪 |
-| 🏥 **健康仪表板** | 运行时间、断路器状态、锁定、缓存统计 |
-| 💰 **成本追踪** | 预算管理 + 每模型定价配置 |
+| 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) |
-### ☁️ 部署与同步
+### 🟣 GEMINI CLI (Google OAuth)
-| 功能 | 功能描述 |
-| --------------------- | ---------------------------------------------------------- |
-| 💾 **Cloud Sync** | 通过 Cloudflare Workers 在设备间同步配置 |
-| 🌐 **随处部署** | Localhost、VPS、Docker、Cloudflare Workers |
-| 🔑 **API Key 管理** | 按提供商生成、轮换和设定 API Key 范围 |
-| 🧙 **配置向导** | 4 步引导式设置，面向新用户 |
-| 🔧 **CLI 工具仪表板** | 一键配置 Claude、Codex、Cline、OpenClaw、Kilo、Antigravity |
-| 🔄 **数据库备份** | 自动备份和恢复所有设置 |
+| Model | Prefix | Limit | Rate Limit |
+| ------------------------ | ------ | --------------------------- | ------------- |
+| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset |
+| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality |
+
+### ⚫ 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
+> iFlow (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 v2.0 is built as an operational platform, not just a relay proxy.
+
+### 🆕 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 Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint |
+| 🤖 **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 (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) |
+| 🤝 **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** | 9 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 combo, apply resilience profiles, reset breakers from one control surface |
+
+### 🧠 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** | 6 balancing strategies + fallback chain control |
+| 🌐 **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) |
+| 💬 **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 |
+| ----------------------------------- | -------------------------------------------------------------------------------------- |
+| 🔌 **Circuit Breakers** | Per-model trip/recover with threshold controls |
+| 🎯 **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 |
+| 📊 **Editable Rate Limits** | Configurable global/provider-level limits with persistence |
+| 🔑 **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 |
+
+### 📊 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 |
+| 📋 **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 |
+
+### ☁️ Deployment & Platform
+
+| Feature | What It Does |
+| ----------------------------- | --------------------------------------------------------- |
+| 🌐 **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |
+| 🚇 **Cloudflare Tunnel** 🆕 | One-click Quick Tunnel integration from the dashboard |
+| 💾 **Cloud Sync** | Configuration sync via cloud worker |
+| 🔄 **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 |
+
+### Feature Deep Dive
+
+#### Smart fallback with practical cost control
+
+```txt
+Combo: "my-coding-stack"
+ 1. cc/claude-opus-4-6
+ 2. nvidia/llama-3.3-70b
+ 3. glm/glm-4.7
+ 4. if/kimi-k2-thinking
+```
+
+When quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.
+
+#### 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)
+
+#### 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)
🚀 30.“我需要在没有胶水代码蔓延的情况下交付代理工作流程”
+🚀 30. "I need to ship agentic workflows without glue-code sprawl"
-拼接多个临时服务和脚本时，团队会失去速度。 +Teams lose velocity when stitching multiple ad-hoc services and scripts. -**OmniRoute 如何解决：** +**How OmniRoute solves it:** -- 客户端和代理的统一端点策略 -- 内置协议管理 UI 和烟雾验证路径 -- 生产就绪的基础（安全性、日志记录、弹性、备份） +- Unified endpoint strategy for clients and agents +- Built-in protocol management UIs and smoke validation paths +- Production-ready foundations (security, logging, resilience, backup)
-
-## 🧪 评估 (Evals)
+📖 功能详情
+🧩 MCP Setup (Model Context Protocol)
-### 🎯 智能 4 层故障转移 +Start MCP transport in stdio mode: -创建带自动故障转移的组合： - -``` -Combo: "my-coding-stack" - 1. cc/claude-opus-4-6 （您的订阅） - 2. nvidia/llama-3.3-70b （免费 NVIDIA API） - 3. glm/glm-4.7 （便宜备用，$0.6/1M） - 4. if/kimi-k2-thinking （免费后备） - -→ 配额用完或出错时自动切换 +```bash +omniroute --mcp ``` -### 📊 实时配额追踪 +Recommended validation flow: -- 每个提供商的 Token 消耗 -- 重置倒计时（5 小时、每日、每周） -- 付费层级的成本估算 -- 月度支出报告 +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: -格式间的无缝转换： - -- **OpenAI** ↔ **Claude** ↔ **Gemini** ↔ **OpenAI Responses** -- 您的 CLI 发送 OpenAI 格式 → OmniRoute 转换 → 提供商接收原生格式 -- 适用于任何支持自定义 OpenAI 端点的工具 - -### 👥 多账号支持 - -- 每个提供商添加多个账号 -- 自动轮询或基于优先级的路由 -- 当一个账号达到配额时自动切换到下一个 - -### 🔄 自动令牌刷新 - -- OAuth 令牌在过期前自动刷新 -- 无需手动重新认证 -- 所有提供商的无缝体验 - -### 🎨 自定义组合 - -- 创建无限模型组合 -- 6 种策略：fill-first、round-robin、power-of-two-choices、random、least-used、cost-optimized -- 通过 Cloud Sync 在设备间共享组合 - -### 🏥 健康仪表板 - -- 系统状态（运行时间、版本、内存使用） -- 每个提供商的断路器状态（Closed/Open/Half-Open） -- 速率限制状态和活动锁定 -- 签名缓存统计 -- 延迟遥测（p50/p95/p99）+ 提示缓存 -- 一键重置健康状态 - -### 🔧 翻译器 Playground - -- 调试、测试和可视化 API 格式转换 -- 发送请求并查看 OmniRoute 如何在提供商格式间转换 -- 对排查集成问题非常有价值 - -### 💾 Cloud Sync - -- 在设备间同步提供商、组合和设置 -- 自动后台同步 -- 安全加密存储 +- `GET /api/mcp/status` +- `GET /api/mcp/tools` +- `GET /api/mcp/audit` +- `GET /api/mcp/audit/stats`
+
🤝 A2A Setup (Agent2Agent)
-OmniRoute 包含内置评估框架，用于针对黄金集测试 LLM 响应质量。通过仪表板中的 **Analytics → Evals** 访问。 +Discover the agent: -### 内置黄金集 +```bash +curl http://localhost:20128/.well-known/agent.json +``` -预加载的「OmniRoute Golden Set」包含 10 个测试用例： +Send a task: -- 问候、数学、地理、代码生成 -- JSON 格式合规性、翻译、markdown -- 安全拒绝（有害内容）、计数、布尔逻辑 +```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."}]}}' +``` -### 评估策略 +Manage lifecycle: -| 策略 | 描述 | 示例 | -| ---------- | -------------------------------- | -------------------------------- | -| `exact` | 输出必须完全匹配 | `"4"` | -| `contains` | 输出必须包含子串（不区分大小写） | `"Paris"` | -| `regex` | 输出必须匹配正则表达式模式 | `"1.*2.*3"` | -| `custom` | 自定义 JS 函数返回 true/false | `(output) => output.length > 10` | +- `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: + +```bash +npm run test:protocols:e2e +``` + +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) ```bash -仪表板 → 提供商 → 连接 Claude Code -→ OAuth 登录 → 自动令牌刷新 -→ 5 小时 + 每周配额追踪 +Dashboard → Providers → Connect Claude Code +→ OAuth login → Auto token refresh +→ 5-hour + weekly quota tracking -模型： +Models: cc/claude-opus-4-6 cc/claude-sonnet-4-5-20250929 cc/claude-haiku-4-5-20251001 ``` -**专业建议：** 复杂任务用 Opus，追求速度用 Sonnet。OmniRoute 按模型追踪配额！ +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! ### OpenAI Codex (Plus/Pro) ```bash -仪表板 → 提供商 → 连接 Codex -→ OAuth 登录（端口 1455） -→ 5 小时 + 每周重置 +Dashboard → Providers → Connect Codex +→ OAuth login (port 1455) +→ 5-hour + weekly reset -模型： +Models: cx/gpt-5.2-codex cx/gpt-5.1-codex-max ``` -### Gemini CLI（免费 180K/月！） +#### 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). + +### Gemini CLI (FREE 180K/month!) ```bash -仪表板 → 提供商 → 连接 Gemini CLI +Dashboard → Providers → Connect Gemini CLI → Google OAuth -→ 每月 180K completions + 每天 1K +→ 180K completions/month + 1K/day -模型： +Models: gc/gemini-3-flash-preview gc/gemini-2.5-pro ``` -**最佳价值：** 巨大的免费额度！在付费层级之前使用。 +**Best Value:** Huge free tier! Use this before paid tiers. ### GitHub Copilot ```bash -仪表板 → 提供商 → 连接 GitHub -→ 通过 GitHub OAuth -→ 每月重置（每月 1 日） +Dashboard → Providers → Connect GitHub +→ OAuth via GitHub +→ Monthly reset (1st of month) -模型： +Models: gh/gpt-5 gh/claude-4.5-sonnet gh/gemini-3-pro @@ -1087,95 +1499,95 @@ OmniRoute 包含内置评估框架，用于针对黄金集测试 LLM 响应质
-
🔑 API Key 提供商
+🔑 API Key Providers
-### NVIDIA NIM（免费 1000 积分！） +### NVIDIA NIM (FREE developer access — 70+ models) -1. 注册：[build.nvidia.com](https://build.nvidia.com) -2. 获取免费 API key（包含 1000 推理积分） -3. 仪表板 → 添加提供商 → NVIDIA NIM： - - API Key：`nvapi-your-key` +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` -**模型：** `nvidia/llama-3.3-70b-instruct`、`nvidia/mistral-7b-instruct` 及 50+ 更多 +**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more -**专业建议：** OpenAI 兼容的 API — 与 OmniRoute 的格式转换完美配合！ +**Pro Tip:** OpenAI-compatible API — works seamlessly with OmniRoute's format translation! ### DeepSeek -1. 注册：[platform.deepseek.com](https://platform.deepseek.com) -2. 获取 API key -3. 仪表板 → 添加提供商 → DeepSeek +1. Sign up: [platform.deepseek.com](https://platform.deepseek.com) +2. Get API key +3. Dashboard → Add Provider → DeepSeek -**模型：** `deepseek/deepseek-chat`、`deepseek/deepseek-coder` +**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` -### Groq（免费层可用！） +### Groq (Free Tier Available!) -1. 注册：[console.groq.com](https://console.groq.com) -2. 获取 API key（包含免费层） -3. 仪表板 → 添加提供商 → Groq +1. Sign up: [console.groq.com](https://console.groq.com) +2. Get API key (free tier included) +3. Dashboard → Add Provider → Groq -**模型：** `groq/llama-3.3-70b`、`groq/mixtral-8x7b` +**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` -**专业建议：** 超快推理 — 最适合实时编程！ +**Pro Tip:** Ultra-fast inference — best for real-time coding! -### OpenRouter（100+ 模型） +### OpenRouter (100+ Models) -1. 注册：[openrouter.ai](https://openrouter.ai) -2. 获取 API key -3. 仪表板 → 添加提供商 → OpenRouter +1. Sign up: [openrouter.ai](https://openrouter.ai) +2. Get API key +3. Dashboard → Add Provider → OpenRouter -**模型：** 通过一个 API key 访问所有主要提供商的 100+ 模型。 +**Models:** Access 100+ models from all major providers through a single API key.
-
💰 低价提供商（备用）
+💰 Cheap Providers (Backup)
-### GLM-4.7（每日重置，$0.6/1M） +### GLM-4.7 (Daily reset, $0.6/1M) -1. 注册：[Zhipu AI](https://open.bigmodel.cn/) -2. 从 Coding Plan 获取 API key -3. 仪表板 → 添加 API Key： - - 提供商：`glm` - - API Key：`your-key` +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` -**使用：** `glm/glm-4.7` +**Use:** `glm/glm-4.7` -**专业建议：** Coding Plan 以 1/7 的价格提供 3 倍配额！每日 10:00 AM 重置。 +**Pro Tip:** Coding Plan offers 3× quota at 1/7 cost! Reset daily 10:00 AM. -### MiniMax M2.1（5 小时重置，$0.20/1M） +### MiniMax M2.1 (5h reset, $0.20/1M) -1. 注册：[MiniMax](https://www.minimax.io/) -2. 获取 API key -3. 仪表板 → 添加 API Key +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key +3. Dashboard → Add API Key -**使用：** `minimax/MiniMax-M2.1` +**Use:** `minimax/MiniMax-M2.1` -**专业建议：** 长上下文（1M Token）最便宜的选项！ +**Pro Tip:** Cheapest option for long context (1M tokens)! -### Kimi K2（$9/月固定） +### Kimi K2 ($9/month flat) -1. 订阅：[Moonshot AI](https://platform.moonshot.ai/) -2. 获取 API key -3. 仪表板 → 添加 API Key +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key +3. Dashboard → Add API Key -**使用：** `kimi/kimi-latest` +**Use:** `kimi/kimi-latest` -**专业建议：** 固定 $9/月 10M Token = $0.90/1M 有效成本！ +**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
-
🆓 免费提供商（应急备用）
+🆓 FREE Providers (Emergency Backup)
-### iFlow（8 个免费模型） +### iFlow (5 FREE models via OAuth) ```bash -仪表板 → 连接 iFlow -→ iFlow OAuth 登录 -→ 无限使用 +Dashboard → Connect iFlow +→ iFlow OAuth login +→ Unlimited usage -模型： +Models: if/kimi-k2-thinking if/qwen3-coder-plus if/glm-4.7 @@ -1183,26 +1595,26 @@ OmniRoute 包含内置评估框架，用于针对黄金集测试 LLM 响应质 if/deepseek-r1 ``` -### Qwen（3 个免费模型） +### Qwen (4 FREE models via Device Code) ```bash -仪表板 → 连接 Qwen -→ 设备码授权 -→ 无限使用 +Dashboard → Connect Qwen +→ Device code authorization +→ Unlimited usage -模型： +Models: qw/qwen3-coder-plus qw/qwen3-coder-flash ``` -### Kiro（免费 Claude） +### Kiro (Claude FREE) ```bash -仪表板 → 连接 Kiro -→ AWS Builder ID 或 Google/GitHub -→ 无限使用 +Dashboard → Connect Kiro +→ AWS Builder ID or Google/GitHub +→ Unlimited usage -模型： +Models: kr/claude-sonnet-4.5 kr/claude-haiku-4.5 ``` @@ -1210,51 +1622,51 @@ OmniRoute 包含内置评估框架，用于针对黄金集测试 LLM 响应质
-
🎨 创建组合
+🎨 Create Combos
-### 示例 1：最大化订阅 → 便宜备用 +### Example 1: Maximize Subscription → Cheap Backup ``` -仪表板 → 组合 → 创建新的 +Dashboard → Combos → Create New -名称：premium-coding -模型： - 1. cc/claude-opus-4-6（订阅主力） - 2. glm/glm-4.7（便宜备用，$0.6/1M） - 3. minimax/MiniMax-M2.1（最便宜的后备，$0.20/1M） +Name: premium-coding +Models: + 1. cc/claude-opus-4-6 (Subscription primary) + 2. glm/glm-4.7 (Cheap backup, $0.6/1M) + 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M) -在 CLI 中使用：premium-coding +Use in CLI: premium-coding ``` -### 示例 2：仅免费（零成本） +### Example 2: Free-Only (Zero Cost) ``` -名称：free-combo -模型： - 1. gc/gemini-3-flash-preview（每月 180K 免费） - 2. if/kimi-k2-thinking（无限制） - 3. qw/qwen3-coder-plus（无限制） +Name: free-combo +Models: + 1. gc/gemini-3-flash-preview (180K free/month) + 2. if/kimi-k2-thinking (unlimited) + 3. qw/qwen3-coder-plus (unlimited) -成本：永远 $0！ +Cost: $0 forever! ```
-
---
-## 🐛 故障排除
+## 故障排除
🔧 CLI 集成
+🔧 CLI Integration
### Cursor IDE ``` -设置 → 模型 → 高级： +Settings → Models → Advanced: OpenAI API Base URL: http://localhost:20128/v1 - OpenAI API Key: [从 OmniRoute 仪表板获取] + OpenAI API Key: [from OmniRoute dashboard] Model: cc/claude-opus-4-6 ``` ### Claude Code -使用仪表板中的 **CLI Tools** 页面一键配置，或手动编辑 `~/.claude/settings.json`。 +Use the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually. ### Codex CLI @@ -1267,13 +1679,13 @@ codex "your prompt" ### OpenClaw -**选项 1 — 仪表板（推荐）：** +**Option 1 — Dashboard (recommended):** ``` -仪表板 → CLI Tools → OpenClaw → 选择模型 → 应用 +Dashboard → CLI Tools → OpenClaw → Select Model → Apply ``` -**选项 2 — 手动：** 编辑 `~/.openclaw/openclaw.json`： +**Option 2 — Manual:** Edit `~/.openclaw/openclaw.json`: ```json { @@ -1289,156 +1701,420 @@ codex "your prompt" } ``` -> **注意：** OpenClaw 仅支持本地 OmniRoute。使用 `127.0.0.1` 而非 `localhost` 以避免 IPv6 解析问题。 +> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues. ### Cline / Continue / RooCode ``` -设置 → API 配置： - 提供商：OpenAI Compatible +Settings → API Configuration: + Provider: OpenAI Compatible Base URL: http://localhost:20128/v1 - API Key: [从 OmniRoute 仪表板获取] + 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. +
-
-- **运行时**: Node.js 20+
-- **语言**: TypeScript 5.9 — `src/` 和 `open-sse/` 中 **100% TypeScript**（v1.0.6）
-- **框架**: Next.js 16 + React 19 + Tailwind CSS 4
-- **数据库**: LowDB (JSON) + SQLite（领域状态 + 代理日志）
-- **流式传输**: Server-Sent Events (SSE)
-- **认证**: OAuth 2.0 (PKCE) + JWT + API Keys
-- **测试**: Node.js test runner（368+ 单元测试）
-- **CI/CD**: GitHub Actions（发布时自动 npm 发布 + Docker Hub）
-- **网站**: [omniroute.online](https://omniroute.online)
-- **包**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
+## 🛠️ Tech Stack
+
+点击展开故障排除指南
+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** -- 订阅配额耗尽 → 回退到 GLM/MiniMax -- 添加组合：`cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` +- Subscription quota out → Fallback to GLM/MiniMax +- Add combo: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` -**OAuth 令牌过期** +**OAuth token expired** -- OmniRoute 自动刷新 -- 如果问题持续：仪表板 → 提供商 → 重新连接 +- Auto-refreshed by OmniRoute +- If issues persist: Dashboard → Provider → Reconnect -**高成本** +**High costs** -- 在仪表板 → 成本中检查使用统计 -- 将主要模型切换为 GLM/MiniMax -- 对非关键任务使用免费层（Gemini CLI、iFlow） +- Check usage stats in Dashboard → Costs +- Switch primary model to GLM/MiniMax +- Use free tier (Gemini CLI, iFlow) for non-critical tasks -**仪表板在错误端口打开** +**Dashboard/API ports are wrong** -- 设置 `PORT=20128` 和 `NEXT_PUBLIC_BASE_URL=http://localhost:20128` +- `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 错误** +**Cloud sync errors** -- 验证 `BASE_URL` 指向您正在运行的实例 -- 验证 `CLOUD_URL` 指向预期的云端点 -- 保持 `NEXT_PUBLIC_*` 值与服务器端值一致 +- 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** -- 检查 `.env` 中的 `INITIAL_PASSWORD` -- 如未设置，默认密码为 `123456` +- Check `INITIAL_PASSWORD` in `.env` +- If unset, fallback password is `123456` -**没有请求日志** +**No request logs** -- 在 `.env` 中设置 `ENABLE_REQUEST_LOGS=true` +- Set `ENABLE_REQUEST_LOGS=true` in `.env` -**兼容 OpenAI 的提供商连接测试显示 "Invalid"** +**Connection test shows "Invalid" for OpenAI-compatible providers** -- 许多提供商不暴露 `/models` 端点 -- OmniRoute v1.0.6+ 包含通过 chat completions 的回退验证 -- 确保 base URL 包含 `/v1` 后缀 +- 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** + +#### Why does Antigravity / Gemini CLI OAuth fail on remote servers? + +The **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console. + +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 + +# For Gemini CLI: +GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com +GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret +``` + +**6. Restart OmniRoute** + +```bash +# npm: +npm run dev + +# Docker: +docker restart omniroute +``` + +**7. Try connecting again** + +Dashboard → Providers → Antigravity (or Gemini CLI) → OAuth + +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. + +--- + +
+
---
-## 🛠️
+🇧🇷 Versão em Português
+ +#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos? + +Os provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo. + +As credenciais OAuth embutidas no OmniRoute estão cadastradas **apenas para `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticação com: + +``` +Error 400: redirect_uri_mismatch +``` + +#### Solução: Configure suas próprias credenciais OAuth + +Você precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor. + +#### Passo a passo + +**1. Acesse o Google Cloud Console** + +Abra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) + +**2. Crie um novo OAuth 2.0 Client ID** + +- Clique em **"+ Create Credentials"** → **"OAuth client ID"** +- Tipo de aplicativo: **"Web application"** +- Nome: escolha qualquer nome (ex: `OmniRoute Remote`) + +**3. Adicione as Authorized Redirect URIs** + +No campo **"Authorized redirect URIs"**, adicione: + +``` +https://seu-servidor.com/callback +``` + +> Substitua `seu-servidor.com` pelo domínio ou IP do seu servidor (inclua a porta se necessário, ex: `http://45.33.32.156:20128/callback`). + +**4. Salve e copie as credenciais** + +Após criar, o Google mostrará o **Client ID** e o **Client Secret**. + +**5. Configure as variáveis de ambiente** + +No seu `.env` (ou nas variáveis de ambiente do Docker): + +```bash +# Para Antigravity: +ANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com +ANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret + +# Para Gemini CLI: +GEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com +GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret +GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret +``` + +**6. Reinicie o OmniRoute** + +```bash +# Se usando npm: +npm run dev + +# Se usando Docker: +docker restart omniroute +``` + +**7. Tente conectar novamente** + +Dashboard → Providers → Antigravity (ou Gemini CLI) → OAuth + +Agora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará. + +--- + +#### Workaround temporário (sem configurar credenciais próprias) + +Se não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**: + +1. O OmniRoute abrirá a URL de autorização do Google +2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto) +3. **Copie a URL completa** da barra de endereço do seu browser (mesmo que a página não carregue) +4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute +5. Clique em **"Connect"** + +> Este workaround funciona porque o código de autorização na URL é válido independente do redirect ter carregado ou não.
+
---
-## 📖 文档
+## 文档
-| 文档 | 描述 |
-| ----------------------------------- | ------------------------------------------------------ |
-| 🎯 **Endpoint-Aware Models** | Custom models declare supported endpoints + API format |
-| [用户指南](docs/USER_GUIDE.md) | 提供商、组合、CLI 集成、部署 |
-| [API 参考](docs/API_REFERENCE.md) | 所有端点及示例 |
-| [故障排除](docs/TROUBLESHOOTING.md) | 常见问题和解决方案 |
-| [架构](docs/ARCHITECTURE.md) | 系统架构和内部机制 |
-| [贡献指南](CONTRIBUTING.md) | 开发设置和指南 |
-| [OpenAPI 规范](docs/openapi.yaml) | OpenAPI 3.0 规范 |
-| [安全策略](SECURITY.md) | 漏洞报告和安全实践 |
+| Document | Description |
+| ---------------------------------------------- | --------------------------------------------------- |
+| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
+| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
+| [MCP Server](open-sse/mcp-server/README.md) | 16 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/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
+| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions |
+| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
+| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
+| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
+| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
+| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
-## 🗺️
+## 🗺️ Roadmap
-## 👥 贡献者
+OmniRoute has **210+ 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, P2C account selection |
+| 🔒 **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping |
+| 📊 **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model |
+| 🔄 **Provider Integrations** | 20+ | Dynamic model registry, provider 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
[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
-### 如何贡献
+### How to Contribute
-1. Fork 仓库
-2. 创建功能分支（`git checkout -b feature/amazing-feature`）
-3. 提交更改（`git commit -m 'Add amazing feature'`）
-4. 推送到分支（`git push origin feature/amazing-feature`）
-5. 打开 Pull Request
+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
-详细指南请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
-### 发布新版本
+### Releasing a New Version
```bash
-# 创建发布 — npm 发布自动完成
-gh release create v1.0.6 --title "v1.0.6" --generate-notes
+# Create a release — npm publish happens automatically
+gh release create v2.0.0 --title "v2.0.0" --generate-notes
```
---
-## 📊 Star 历史
+## 📊 Star History
## Stargazers over time
## [](https://starchart.cc/diegosouzapw/OmniRoute)
-## 🙏 致谢
+## 🙏 Acknowledgments
-特别感谢 **[decolua](https://github.com/decolua)** 的 **[9router](https://github.com/decolua/9router)** — 启发了本 fork 的原始项目。OmniRoute 在这个令人难以置信的基础上添加了额外功能、多模态 API 和完整的 TypeScript 重写。
+Special thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.
-特别感谢 **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — 启发了本 JavaScript 移植的原始 Go 实现。
+Special thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — the original Go implementation that inspired this JavaScript port.
---
-## 📄 许可证
+## 许可证
-MIT 许可证 — 详见 [LICENSE](LICENSE)。
+MIT License - see [LICENSE](LICENSE) for details.
---
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**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions) +- **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) -- **弹性**: 断路器、指数退避、反惊群、TLS 伪装 +- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing + +
- 用 ❤️ 为 24/7 编程的开发者打造
+ Built with ❤️ for developers who code 24/7
omniroute.online
+
diff --git a/docs/i18n/zh-CN/docs/FEATURES.md b/docs/i18n/zh-CN/docs/FEATURES.md
new file mode 100644
index 0000000000..ce4fb41a05
--- /dev/null
+++ b/docs/i18n/zh-CN/docs/FEATURES.md
@@ -0,0 +1,145 @@
+# OmniRoute — Dashboard Features Gallery (中文（简体）)
+
+🌐 **Languages:** 🇺🇸 [English](../../../../docs/FEATURES.md) · 🇪🇸 [es](../../es/docs/FEATURES.md) · 🇫🇷 [fr](../../fr/docs/FEATURES.md) · 🇩🇪 [de](../../de/docs/FEATURES.md) · 🇮🇹 [it](../../it/docs/FEATURES.md) · 🇷🇺 [ru](../../ru/docs/FEATURES.md) · 🇨🇳 [zh-CN](../../zh-CN/docs/FEATURES.md) · 🇯🇵 [ja](../../ja/docs/FEATURES.md) · 🇰🇷 [ko](../../ko/docs/FEATURES.md) · 🇸🇦 [ar](../../ar/docs/FEATURES.md) · 🇮🇳 [in](../../in/docs/FEATURES.md) · 🇹🇭 [th](../../th/docs/FEATURES.md) · 🇻🇳 [vi](../../vi/docs/FEATURES.md) · 🇮🇩 [id](../../id/docs/FEATURES.md) · 🇲🇾 [ms](../../ms/docs/FEATURES.md) · 🇳🇱 [nl](../../nl/docs/FEATURES.md) · 🇵🇱 [pl](../../pl/docs/FEATURES.md) · 🇸🇪 [sv](../../sv/docs/FEATURES.md) · 🇳🇴 [no](../../no/docs/FEATURES.md) · 🇩🇰 [da](../../da/docs/FEATURES.md) · 🇫🇮 [fi](../../fi/docs/FEATURES.md) · 🇵🇹 [pt](../../pt/docs/FEATURES.md) · 🇷🇴 [ro](../../ro/docs/FEATURES.md) · 🇭🇺 [hu](../../hu/docs/FEATURES.md) · 🇧🇬 [bg](../../bg/docs/FEATURES.md) · 🇸🇰 [sk](../../sk/docs/FEATURES.md) · 🇺🇦 [uk-UA](../../uk-UA/docs/FEATURES.md) · 🇮🇱 [he](../../he/docs/FEATURES.md) · 🇵🇭 [phi](../../phi/docs/FEATURES.md) · 🇧🇷 [pt-BR](../../pt-BR/docs/FEATURES.md)
+
+---
+
+Visual guide to every section of the OmniRoute dashboard.
+
+---
+
+## 🔌 Providers
+
+Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (iFlow, Qwen, Kiro). Kiro accounts include credit balance tracking — remaining credits, total allowance, and renewal date visible in Dashboard → Usage.
+
+
+
+---
+
+## 🎨 Combos
+
+Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks.
+
+
+
+---
+
+## 📊 Analytics
+
+Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns.
+
+
+
+---
+
+## 🏥 System Health
+
+Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states.
+
+
+
+---
+
+## 🔧 Translator Playground
+
+Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream).
+
+
+
+---
+
+## 🎮 Model Playground _(v2.0.9+)_
+
+Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics.
+
+---
+
+## 🎨 Themes _(v2.0.5+)_
+
+Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode.
+
+---
+
+## ⚙️ Settings
+
+Comprehensive settings panel with tabs:
+
+- **General** — System storage, backup management (export/import database)
+- **Appearance** — Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls
+- **Security** — API endpoint protection, custom provider blocking, IP filtering, session info
+- **Routing** — Model aliases, background task degradation
+- **Resilience** — Rate limit persistence, circuit breaker tuning
+- **Advanced** — Configuration overrides
+
+
+
+---
+
+## 🔧 CLI Tools
+
+One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping.
+
+
+
+---
+
+## 🤖 CLI Agents _(v2.0.11+)_
+
+Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with:
+
+- **Installation status** — Installed / Not Found with version detection
+- **Protocol badges** — stdio, HTTP, etc.
+- **Custom agents** — Register any CLI tool via form (name, binary, version command, spawn args)
+- **CLI Fingerprint Matching** — Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP
+
+---
+
+## 🖼️ Media _(v2.0.3+)_
+
+Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen.
+
+---
+
+## 📝 Request Logs
+
+Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details.
+
+
+
+---
+
+## 🌐 API Endpoint
+
+Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access.
+
+
+
+---
+
+## 🔑 API Key Management
+
+Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking.
+
+---
+
+## 📋 Audit Log
+
+Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history.
+
+---
+
+## 🖥️ Desktop Application
+
+Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install.
+
+Key features:
+
+- Server readiness polling (no blank screen on cold start)
+- System tray with port management
+- Content Security Policy
+- Single-instance lock
+- Auto-update on restart
+- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar)
+- Hardened Electron build packaging — symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+)
+
+📖 See [`electron/README.md`](../electron/README.md) for full documentation.
diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index eebf8d849c..6c27c706c0 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -1,7 +1,7 @@
openapi: 3.1.0
info:
title: OmniRoute API
- version: 3.3.1
+ version: 3.3.2
description: |
OmniRoute is a local-first AI API proxy router. It provides an OpenAI-compatible
endpoint that routes requests to multiple AI providers with load balancing,
diff --git a/package-lock.json b/package-lock.json
index 6004a1ad94..fd63879e90 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "omniroute",
- "version": "3.3.1",
+ "version": "3.3.2",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "omniroute",
- "version": "3.3.1",
+ "version": "3.3.2",
"hasInstallScript": true,
"license": "MIT",
"workspaces": [
diff --git a/package.json b/package.json
index 710a594aa6..0e999354dc 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "omniroute",
- "version": "3.3.1",
+ "version": "3.3.2",
"description": "Smart AI Router with auto fallback — route to FREE & cheap models, zero downtime. Works with Cursor, Cline, Claude Desktop, Codex, and any OpenAI-compatible tool.",
"type": "module",
"bin": {
omniroute.online